@open-everywhere/provider-slack 0.7.0 → 0.8.1

package/agent/access/slack-attachment-fetch.ts

@@ -42,6 +42,7 @@ import {
   type EgressRefusalCause,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import { slackBotToken } from "../setup/credentials.js";
+import type { AuditDetail } from "@open-everywhere/core/agent/adapter-api.js";
 
 // THE CREDENTIAL'S IDENTITY, FOR THE AUDIT ROW (OPE-1547) — the ref NAME, never the value. This is
 // the one host-side seam that attaches a credential, so before this ticket it was the one place
@@ -140,7 +141,7 @@ export async function fetchSlackAttachment(ctx: BindableContext, ref: TrustedSla
   // referenced here; the row carries the ref name only, which is the identity an operator looks up.
   // `route` is the dispatch route — it was called `via` until OPE-1547, the same field name the
   // SANDBOX plane used for the stamping connection.
-  const row = (outcome: "allowed" | "failed", extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+  const row = (outcome: "allowed" | "failed", extra: AuditDetail = {}): AuditDetail => ({
     ...hostCallAuditFields({
       host: safe.url.hostname,
       verb: ATTACHMENT_VERB,

package/agent/app-manifest.ts

@@ -150,7 +150,7 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             description: `${appName} control-plane commands (stop, status, budget) — no model turn.`,
             // Every subcommand `parseOeCommandTokens` accepts (packages/core/agent/commands/core.ts).
             // scripts/slack-app-manifest-test.ts fails if one is missing here.
-            usage_hint: "stop | status | budget [raise <usd> | clear] | rate <n> | optout [on | off] | watch [more | less | none] | help",
+            usage_hint: "stop | status | budget [raise <usd> | clear] | rate <n> | optout [on | off] | watch [more | less | none] | cover [on | off] | suggest [on | off] | help",
             should_escape: false,
           },
         ],
@@ -243,8 +243,21 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             // knows. Without it the canvas refresh fails with `missing_scope`, logged and audited
             // per channel, and memory itself is unaffected.
             "canvases:write",
+            // canvases.sections.lookup — find a memory canvas made before the `memory_canvas` row
+            // existed, by the marker line it carries (OPE-2587, core channels/slack-canvas-list.ts
+            // `memoryCanvasAmong`). Without it such a canvas held only as a channel tab is not found:
+            // its refresh and take-down record `failed` and `clear-failed`, and nothing is overwritten.
+            "canvases:read",
+            // slackLists.items.list / .create / .update — the agent's own List writes (OPE-2521,
+            // core tools/update_list.ts): it reads a List's rows to match one by name, then adds or
+            // changes rows on a person's approval. `canvases:write` above also covers the agent's own
+            // canvas writes (canvases.create, canvases.edit; core tools/write_canvas.ts).
+            "lists:read",
+            "lists:write",
             // The side panel (OPE-2457): Slack requires it for `app_context_changed`, the event whose
-            // subscription makes Slack attach the viewed room to each side-panel `message.im`.
+            // subscription makes Slack attach the viewed room to each side-panel `message.im`. It also
+            // covers `assistant.threads.setStatus`, the status line a turn shows while it works: the
+            // mention door's, and the DM seat's (OPE-2629, channels/slack-agent-session.ts).
             "assistant:write",
             // Slack requires this bot scope on an app whose people connect to Slack's MCP server
             // (OPE-2421). Declared only when the app declares "search Slack as you".
@@ -271,6 +284,8 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
           //   channel_shared → channels:read, groups:read (re-run the memory canvas gate, OPE-2451)
           //   user_change → users:read (automatic offboarding on a deactivated member, OPE-2423)
           //   app_context_changed → assistant:write (the side panel's viewed room, OPE-2457)
+          //   agent_session_stopped → chat:write (Slack's native Stop button on an agent session,
+          //     OPE-2519; Slack shows the button only to an app subscribed to it)
           // scripts/slack-app-manifest-test.ts derives the handled set from the code and fails if
           // this list drops one (OPE-2223).
           bot_events: [
@@ -286,6 +301,7 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             "channel_shared",
             "user_change",
             "app_context_changed",
+            "agent_session_stopped",
           ],
         },
         // The INTERACTIVITY Request URL — the SAME public route Event Subscriptions uses. Every

package/agent/channels/slack-agent-session.ts

@@ -0,0 +1,338 @@
+// THE SLACK AGENT SESSION (OPE-2519) — Slack's native Stop, the session title, and the "needs you" state.
+//
+// Slack's agent experience shows each conversation with the app as an AGENT SESSION, keyed by the
+// channel and the thread root (docs.slack.dev/ai/agent-sessions, re-read 2026-10-14). A session has a
+// lifecycle status (`processing`, `active`, `suspended`, `closed`) and a title. This file owns the three
+// things OE does with it:
+//
+//   • STOP. While a session is `processing`, Slack shows a Stop button, but only to an app that
+//     subscribes to `agent_session_stopped`. A press arrives as that event. It takes the SAME cancel
+//     path as the ✋ reaction and `/oe stop` (`cancelAnchoredTurn`): no session is minted, no model is
+//     called, nothing is spent. Slack does not move the status itself, so the route sets `active`.
+//   • TITLE. A top-level message the person sends in their DM with the app opens a new conversation,
+//     and gets a short title from the words the person TYPED (`authoredText`). The lines of a
+//     forwarded or quoted message are another conversation's words, so they never title it. The host
+//     derives the title in code: no model writes it. Slack applies a `title` only when the call
+//     CREATES the session, so a title the person typed over ours is never overwritten. A thread reply,
+//     a shortcut and a group DM get no title.
+//   • STATE. Core's turn-anchor hook sets the session `processing` when a turn starts, and at the park
+//     `suspended` when the turn reported through `update_status` that it waits on a person
+//     (`needs_input` or `blocked`), else `active` (channels/surface-session-state.ts). This file
+//     registers the Slack setter: it names the session from the delivery's auth attributes. The
+//     person's next message sets `processing`, then parks `active` unless it reports again that it
+//     waits on the person. A job's result wake names no session, so its turn sets no state.
+//   • THE WORKING SIGNS (OPE-2629). The same setter shows the 👀 and the status line on the session's
+//     root while a turn works, and clears both at the park. See `setSlackDmWorkingSigns`.
+//   • A FORWARDED JOB's WAIT (OPE-2536). A job the DM seat forwards to the work session can end waiting
+//     on the person: it asked a question in the room (`ask_room`), or it needs their own sign-in. The
+//     work session has no `update_status`, so the host sets the session `suspended` at the job's
+//     settlement (core channels/work-surface-wait.ts). This file registers the PIN for that: the
+//     session's id and the three attributes that name it again, kept on the job.
+//
+// WHICH SESSIONS. Only the person's 1:1 DM with the app (the Messages tab and the side panel), where
+// Slack lists the person's agent sessions. The DM door stamps the session's thread root on the wake's
+// auth (`agent_session_ts`): a top-level message opens its own session, keyed by its own `ts`, and a
+// thread reply belongs to its thread's session. A channel thread gets no state from OE.
+//
+// Every call here is best-effort. A workspace without Slack's agent features answers an error, which
+// is logged and changes nothing else.
+
+import {
+  cancelAnchoredTurn,
+  resolvePartition,
+  STATUS_REACTION,
+  swallowRoomOp,
+  turnAnchorKey,
+  turnChannelKey,
+  type AttachSessionForCancel,
+  type CancelResult,
+  type SurfaceSessionPinner,
+  type SurfaceSessionSetter,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { bindableForSlackIds, slackForm, type SlackEventEnvelope } from "./slack-events.js";
+
+/** Slack's event for a press of the session's Stop button. */
+export const AGENT_SESSION_STOPPED_EVENT = "agent_session_stopped";
+
+/** The longest title OE sets. Slack accepts 200 characters; a session list shows far fewer. */
+export const SLACK_SESSION_TITLE_MAX = 60;
+
+/** The session states OE sets. */
+export type SlackSessionStatus = "processing" | "active" | "suspended";
+
+/** The auth attribute the DM door stamps with the session's thread root (slack-front.ts `scheduleDmWake`). */
+const AGENT_SESSION_TS_ATTRIBUTE = "agent_session_ts";
+
+/**
+ * The mark a PINNED bag carries (OPE-2629). A forwarded job's settlement sets the session's state from
+ * its pin, not from a turn, so the setter must not touch the turn's working signs for it: a turn of the
+ * same session can be running at that moment, and its 👀 must stay until its own park.
+ */
+const SESSION_PIN_ATTRIBUTE = "oe_session_pin";
+
+/** The form-call seam: `slackForm` in production, a recorder in the tests. */
+export type SlackFormCall = (method: string, body: string) => Promise<Record<string, unknown> | undefined>;
+
+// --- the title ------------------------------------------------------------------------------------
+
+/** Slack's three escaped characters, decoded. */
+function decodeSlackEntities(text: string): string {
+  return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+/**
+ * The session title for a conversation that opens with `text`, or undefined when nothing readable is
+ * left. Pure. It keeps the first non-empty line, renders a link as its label, a channel as `#name`, and
+ * drops a member or group mention (no raw id reaches the title). It strips `*`, `~` and backticks, and
+ * keeps `_`, so an identifier such as `oe_config` stays intact. A long line is cut at a word and ends
+ * with `…`.
+ */
+export function slackSessionTitle(text: string | undefined): string | undefined {
+  if (typeof text !== "string") return undefined;
+  const rendered = text
+    // A member mention, with or without a label: dropped.
+    .replace(/<@[A-Z0-9]+(?:\|[^>]*)?>/g, " ")
+    // A channel mention: its name when Slack sent one, else dropped.
+    .replace(/<#[A-Z0-9]+\|([^>]+)>/g, "#$1")
+    .replace(/<#[A-Z0-9]+>/g, " ")
+    // A special or group mention (`<!here>`, `<!subteam^S1|@team>`): dropped.
+    .replace(/<![^>]*>/g, " ")
+    // A link: its label, else the address.
+    .replace(/<[^>|]+\|([^>]+)>/g, "$1")
+    .replace(/<([^>]+)>/g, "$1");
+  const line = decodeSlackEntities(rendered)
+    .split(/\r?\n/)
+    .map((l) => l.replace(/[*~`]+/g, "").replace(/\s+/g, " ").trim())
+    .find((l) => l.length > 0);
+  if (line === undefined) return undefined;
+  if (line.length <= SLACK_SESSION_TITLE_MAX) return line;
+  const head = line.slice(0, SLACK_SESSION_TITLE_MAX - 1);
+  const cut = head.lastIndexOf(" ");
+  return `${(cut >= SLACK_SESSION_TITLE_MAX / 2 ? head.slice(0, cut) : head).trimEnd()}…`;
+}
+
+// --- the status call -------------------------------------------------------------------------------
+
+/** One `agents.sessions.setStatus` call. */
+export interface SlackSessionStatusCall {
+  readonly channelId: string;
+  /** The session's thread root. */
+  readonly threadTs: string;
+  readonly status: SlackSessionStatus;
+  /** Applied only when this call creates the session. */
+  readonly title?: string;
+}
+
+/** The form body of {@link SlackSessionStatusCall}. Pure. */
+export function slackSessionStatusForm(call: SlackSessionStatusCall): string {
+  const body = new URLSearchParams({ channel_id: call.channelId, thread_ts: call.threadTs, status: call.status });
+  if (call.title !== undefined && call.title.length > 0) body.set("title", call.title);
+  return body.toString();
+}
+
+/** Set a session's status (and, on creation, its title). True when Slack answered `ok`. Never throws. */
+export async function setSlackSessionStatus(call: SlackSessionStatusCall, form: SlackFormCall = slackForm): Promise<boolean> {
+  try {
+    const res = await form("agents.sessions.setStatus", slackSessionStatusForm(call));
+    if (res?.ok === true) return true;
+    console.warn(`[open-everywhere:slack-session] agents.sessions.setStatus ${call.status} was not applied (${call.channelId}/${call.threadTs}): ${String(res?.error ?? "no answer")}`);
+    return false;
+  } catch (err) {
+    console.warn(`[open-everywhere:slack-session] agents.sessions.setStatus ${call.status} failed (${call.channelId}/${call.threadTs}): ${String(err)}`);
+    return false;
+  }
+}
+
+/**
+ * The session a delivery's auth attributes name, or undefined for none. Only a delivery the DM door
+ * stamped (`agent_session_ts`) names one: a shortcut, a group DM and every channel carry no stamp, so
+ * they never set a session's state, even on a threaded message. Pure.
+ */
+export function slackAgentSessionOf(attributes: Readonly<Record<string, unknown>>): { readonly channelId: string; readonly threadTs: string } | undefined {
+  if (attributes.channel_type !== "im") return undefined;
+  const channelId = attributes.channel_id;
+  const stamped = attributes[AGENT_SESSION_TS_ATTRIBUTE];
+  if (typeof channelId !== "string" || channelId.length === 0 || typeof stamped !== "string" || stamped.length === 0) return undefined;
+  return { channelId, threadTs: stamped };
+}
+
+/**
+ * The Slack pinner (OPE-2536): the session a delivery names, as the setter's own id and the three
+ * attributes that name it again. A forwarded job keeps this, so its settlement can set the session
+ * `suspended` long after the delivery's auth is gone. Ids only, never text. Pure.
+ */
+export const slackSurfaceSessionPin: SurfaceSessionPinner = (attributes) => {
+  const session = slackAgentSessionOf(attributes);
+  if (!session) return undefined;
+  return {
+    id: `${session.channelId}:${session.threadTs}`,
+    attributes: { channel_id: session.channelId, channel_type: "im", [AGENT_SESSION_TS_ATTRIBUTE]: session.threadTs, [SESSION_PIN_ATTRIBUTE]: "1" },
+  };
+};
+
+// --- the working signs ------------------------------------------------------------------------------
+//
+// 🔴 THE DM SEAT'S 👀 AND STATUS LINE LIVE HERE (OPE-2629). A 1:1 DM runs on the `unified` channel, so
+// none of the Slack channel's own handlers reach it: `onInbound` (the 👀) and the `turn.started`
+// renderer (the status line) serve only eve's native mention door. Before this, a person who DMed
+// the app saw neither during the turn. Core's turn-anchor hook calls this setter at every DM turn's
+// start (`processing`) and park (`active` or `suspended`), so the signs ride the same two calls:
+//   • 👀 on the session's thread root — the message itself when it is top-level, the same root the
+//     mention door's 👀 uses for a threaded one. Added at `processing`, removed at the park.
+//   • Slack's assistant status (`assistant.threads.setStatus`) on that root: `Working...` at
+//     `processing`, cleared at the park. The flat DM reply does not clear it, so the park must.
+// A forwarded job's settlement (OPE-2536) also calls this setter, from the job's PIN. A turn of the
+// same session can run at that moment, so a pinned bag (`SESSION_PIN_ATTRIBUTE`) moves the session
+// state only and leaves the signs to the turn's own park.
+// A turn that fails for good emits `session.failed` and never parks, so its signs stay: the 👀 until
+// the session's next turn parks, and the status line until Slack expires it.
+
+/** The status line a DM turn shows while it works — the same words the mention door's `turn.started` shows. */
+export const SLACK_DM_WORKING_STATUS = "Working...";
+
+/** The 👀 the bot sets while it works (core status/status.ts `STATUS_REACTION.working`). */
+const WORKING_REACTION = STATUS_REACTION.working;
+
+/**
+ * What an operator does when one sign call fails with a setup error (`SIGN_SETUP_ERRORS`). The sign
+ * needs a scope or the agent view, and both come from the app manifest, so the fix is the manifest
+ * paste. Logged once per method and error, so a workspace without the feature does not log it on
+ * every turn.
+ */
+const SIGN_SETUP_FIX: Readonly<Record<string, string>> = {
+  "reactions.add": "the 👀 needs the reactions:write bot scope",
+  "reactions.remove": "the 👀 needs the reactions:write bot scope",
+  "assistant.threads.setStatus": "the DM status line needs the assistant:write bot scope and the agent view (features.agent_view)",
+};
+/** Slack's answers that mean the app lacks a scope or a feature: a setup gap, not a passing fault. */
+const SIGN_SETUP_ERRORS = new Set(["missing_scope", "feature_disabled", "not_allowed_token_type", "not_allowed", "access_denied"]);
+/** Slack's answers that say the sign is already in the state asked for. */
+const SIGN_NO_OP_ERRORS = new Set(["already_reacted", "no_reaction"]);
+const warnedSignErrors = new Set<string>();
+
+/** One sign call. Never throws; a failure is logged once per method and error, with the setup fix. */
+async function sendSign(form: SlackFormCall, method: string, body: URLSearchParams): Promise<void> {
+  let error: string;
+  try {
+    const res = await form(method, body.toString());
+    if (res?.ok === true) return;
+    error = String(res?.error ?? "no answer");
+  } catch (err) {
+    error = String(err);
+  }
+  if (SIGN_NO_OP_ERRORS.has(error)) return;
+  const key = `${method}:${error}`;
+  if (warnedSignErrors.has(key)) return;
+  warnedSignErrors.add(key);
+  const fix = SIGN_SETUP_ERRORS.has(error)
+    ? `${SIGN_SETUP_FIX[method] ?? "this sign needs a manifest scope"}. Fix: paste the app manifest again (App Manifest → Save Changes) and reinstall if Slack asks`
+    : "the sign is best-effort and the turn goes on";
+  console.warn(`[open-everywhere:slack-session] ${method} failed (${error}) — ${fix}. Logged once per process.`);
+}
+
+/** Test-only: forget which sign failures were already logged. */
+export function _resetSignWarningsForTest(): void {
+  warnedSignErrors.clear();
+}
+
+/**
+ * Show or clear the DM turn's working signs on the session's root: the 👀 and the status line. The
+ * two calls run in parallel, because the turn waits on this setter. A swallowed room op (the egress
+ * spoof) sends neither. Never throws.
+ */
+async function setSlackDmWorkingSigns(session: { readonly channelId: string; readonly threadTs: string }, working: boolean, form: SlackFormCall = slackForm): Promise<void> {
+  if (swallowRoomOp(`a slack DM working sign ${working ? "add" : "remove"}`)) return;
+  const reaction = new URLSearchParams({ channel: session.channelId, name: WORKING_REACTION, timestamp: session.threadTs });
+  const status = new URLSearchParams({ channel_id: session.channelId, thread_ts: session.threadTs, status: working ? SLACK_DM_WORKING_STATUS : "" });
+  await Promise.all([sendSign(form, working ? "reactions.add" : "reactions.remove", reaction), sendSign(form, "assistant.threads.setStatus", status)]);
+}
+
+/** The Slack setter core's turn-anchor hook calls (registered in register.ts). */
+export function slackSurfaceSessionSetter(form: SlackFormCall = slackForm): SurfaceSessionSetter {
+  return async (attributes, status) => {
+    const session = slackAgentSessionOf(attributes);
+    if (!session) return undefined;
+    const fromTurn = attributes[SESSION_PIN_ATTRIBUTE] === undefined;
+    await Promise.all([setSlackSessionStatus({ ...session, status }, form), ...(fromTurn ? [setSlackDmWorkingSigns(session, status === "processing", form)] : [])]);
+    return `${session.channelId}:${session.threadTs}`;
+  };
+}
+
+// --- the Stop button -------------------------------------------------------------------------------
+
+/** One press of the Stop button, as the route reads it. */
+export interface ParsedSessionStop {
+  readonly channelId: string;
+  /** The session's thread root. */
+  readonly threadTs: string;
+  /** Who pressed Stop. */
+  readonly userId: string;
+  /** From the `event_callback` envelope: Slack does not put it in the event. */
+  readonly teamId?: string;
+  readonly eventTs?: string;
+}
+
+/** Parse an `agent_session_stopped` envelope, or null for anything else. Pure. */
+export function parseAgentSessionStopped(envelope: SlackEventEnvelope): ParsedSessionStop | null {
+  if (envelope?.type !== "event_callback") return null;
+  const e = envelope.event as Record<string, unknown> | undefined;
+  if (!e || e.type !== AGENT_SESSION_STOPPED_EVENT) return null;
+  const channelId = typeof e.channel === "string" ? e.channel : "";
+  const threadTs = typeof e.thread_ts === "string" ? e.thread_ts : "";
+  const userId = typeof e.user === "string" ? e.user : "";
+  if (!channelId || !threadTs || !userId) return null;
+  const teamId = typeof envelope.team_id === "string" && envelope.team_id.length > 0 ? envelope.team_id : undefined;
+  return {
+    channelId,
+    threadTs,
+    userId,
+    ...(teamId ? { teamId } : {}),
+    ...(typeof e.event_ts === "string" ? { eventTs: e.event_ts } : {}),
+  };
+}
+
+/** A 1:1 DM channel id. Only there does the stop fall back to the channel's newest turn. */
+function isDmChannel(channelId: string): boolean {
+  return channelId.startsWith("D");
+}
+
+/** What the Stop route needs. */
+export interface SessionStopDeps {
+  /** eve's I/O-free cancel door, the same one the ✋ arm uses. */
+  readonly attachSession: AttachSessionForCancel;
+  /** The cancel path. Absent means the live `cancelAnchoredTurn`. */
+  readonly cancel?: typeof cancelAnchoredTurn;
+  /** The status call. Absent means the live {@link setSlackSessionStatus}. */
+  readonly setStatus?: (call: SlackSessionStatusCall) => Promise<boolean>;
+}
+
+/**
+ * Stop the turn a Stop press names, then set the session `active`.
+ *
+ * The turn is found by the session's thread first (the key the ✋ arm uses for a thread root). In the
+ * person's 1:1 DM it falls back to the DM's newest turn, because a top-level DM message keys its turn by
+ * the channel alone. In a shared channel it does not fall back: there the newest turn can belong to
+ * another thread, and cancelling nothing beats cancelling a guess. The status is set whatever the
+ * cancel answers, because a session left `processing` keeps its spinner for an hour. Never throws.
+ */
+export async function routeAgentSessionStop(ev: ParsedSessionStop, deps: SessionStopDeps): Promise<CancelResult> {
+  const p = resolvePartition(bindableForSlackIds({ teamId: ev.teamId, channelId: ev.channelId, userId: ev.userId }));
+  const anchorKey = turnAnchorKey("slack", ev.channelId, ev.threadTs);
+  const channelKey = isDmChannel(ev.channelId) ? turnChannelKey("slack", ev.channelId) : undefined;
+  let result: CancelResult;
+  try {
+    result = await (deps.cancel ?? cancelAnchoredTurn)({
+      org: p.org,
+      platform: "slack",
+      workspace: p.workspace,
+      requestedBy: ev.userId,
+      via: "stop-button",
+      query: { ...(anchorKey ? { anchorKey } : {}), ...(channelKey ? { channelKey } : {}) },
+      attachSession: deps.attachSession,
+    });
+  } catch (err) {
+    result = { outcome: "error", message: `stop failed: ${String(err)}` };
+  }
+  await (deps.setStatus ?? setSlackSessionStatus)({ channelId: ev.channelId, threadTs: ev.threadTs, status: "active" }).catch(() => false);
+  return result;
+}

package/agent/channels/slack-attachments.ts

@@ -33,6 +33,7 @@ import {
   registerAttachmentResolver,
   AttachmentOversizeError,
   type SlackAttachmentRow,
+  type BindableContext,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import { fetchSlackAttachment } from "../access/slack-attachment-fetch.js";
 
@@ -135,6 +136,24 @@ export async function resolveSlackAttachmentDurable(fileId: string, org?: string
   }
 }
 
+/**
+ * The size-guarded byte pull over a TRUSTED `url_private`: the bot-token, host-pinned fetch, then the Content-Length
+ * pre-check (rejects with {@link AttachmentOversizeError} phase "declared" BEFORE the body is read), then the post-read
+ * cap (phase "actual"). Two callers: the guarded resolver below, and the voice-clip loader (slack-voice-clips.ts),
+ * which reads a clip off the event that woke the agent. Both pass an event-supplied URL, never a model string.
+ */
+export async function pullSlackAttachmentBytes(ctx: BindableContext, ref: { readonly urlPrivate: string; readonly id?: string }, maxBytes: number): Promise<Uint8Array> {
+  const res = await fetchSlackAttachment(ctx, ref);
+  if (!res.ok) throw new Error(`fetching the upload failed (HTTP ${res.status})`);
+  // Content-Length pre-check off the declared length — reject before reading the body.
+  const declared = Number.parseInt(res.headers.get("content-length") ?? "", 10);
+  if (Number.isFinite(declared) && declared > maxBytes) throw new AttachmentOversizeError(declared, "declared", maxBytes);
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  // Post-read cap — a chunked response can exceed the (possibly-absent) Content-Length.
+  if (bytes.byteLength > maxBytes) throw new AttachmentOversizeError(bytes.byteLength, "actual", maxBytes);
+  return bytes;
+}
+
 /**
  * Register Slack as an attachment-plane resolver (channels/attachments.ts) — the neutral seam
  * describe_image consults so its contract carries no per-platform union arm. The resolver wraps the
@@ -169,17 +188,7 @@ export function registerSlackAttachmentResolver(): void {
         ref: `slack-file:${attachmentId}`,
         mimeType: rec.mimeType,
         name: rec.name,
-        async pull({ maxBytes }) {
-          const res = await fetchSlackAttachment(ctx, { urlPrivate: rec.urlPrivate, id: attachmentId });
-          if (!res.ok) throw new Error(`fetching the upload failed (HTTP ${res.status})`);
-          // Content-Length pre-check off the declared length — reject before reading the body.
-          const declared = Number.parseInt(res.headers.get("content-length") ?? "", 10);
-          if (Number.isFinite(declared) && declared > maxBytes) throw new AttachmentOversizeError(declared, "declared", maxBytes);
-          const bytes = new Uint8Array(await res.arrayBuffer());
-          // Post-read cap — a chunked response can exceed the (possibly-absent) Content-Length.
-          if (bytes.byteLength > maxBytes) throw new AttachmentOversizeError(bytes.byteLength, "actual", maxBytes);
-          return bytes;
-        },
+        pull: ({ maxBytes }) => pullSlackAttachmentBytes(ctx, { urlPrivate: rec.urlPrivate, id: attachmentId }, maxBytes),
       };
     },
   });