@open-everywhere/provider-slack 0.1.0

package/agent/channels/slack-approval-card.ts

@@ -0,0 +1,275 @@
+// THE SLACK RETURN LEG FOR A BRIDGED APPROVAL CARD (OPE-1720) — what makes the button the unified
+// post arm now renders actually settle the approval it names.
+//
+// WHY THIS EXISTS RATHER THAN EVE'S OWN HITL ROUTE. eve's Slack channel has an interactivity seam for
+// its own `eve_input:` cards, and `slack-input-response.ts` is OE's admission on it. That seam cannot
+// serve this card, and the reason is structural rather than a not-yet: eve's own handler stores the
+// card it minted in the SLACK channel's state (`defaults.js` writes `state.pendingApprovalCards`) and
+// resolves the click against that channel's session address. A DM seat's parked request lives on the
+// UNIFIED window — another channel, another session, another state bag — so a click on a card OE
+// posted there has nothing for eve's route to resolve. It is OE's card, so it is OE's click.
+//
+// 🔴 THE SAME ADMISSION, THOUGH. `admitInputResponse` (core approvals/input-response-floor.ts) is the
+// ONE decision both HITL answer doors take, and `ingressSpendGate` with door `"answer"` is the same
+// spend floor `admitSlackInputResponse` consults FIRST for the same reason: a tap RESUMES a parked
+// turn, which is a decision to spend more on a scope nobody asked whether it could afford. This
+// module adds no floor of its own — it resolves the click, asks those two, and delivers.
+//
+// 🔴 A REFUSAL LEAVES THE CARD LIVE. Nothing here consumes a row on any outcome but a delivered
+// answer: the approval stays parked, the card stays tappable for somebody who may answer it, and the
+// question stays answerable IN WORDS through the text leg (`question-bridge.ts`), which is untouched.
+// That is the same "a refusal is not a drop" posture the text leg holds.
+
+import {
+  admitInputResponse,
+  APPROVAL_BUTTON_LABELS,
+  APPROVAL_CARD_REFUSED_AUDIT_ACTION as CORE_APPROVAL_CARD_REFUSED_AUDIT_ACTION,
+  APPROVAL_CARD_SETTLED_AUDIT_ACTION as CORE_APPROVAL_CARD_SETTLED_AUDIT_ACTION,
+  auditApprovalCardTap,
+  deploymentOrg,
+  forgetApprovalCardTicket,
+  forgetBridgedQuestion,
+  getOperationalStore,
+  ingressSpendGate,
+  parseApprovalClickId,
+  readBridgedQuestion,
+  readApprovalCardTicket,
+  resolveApprovalCardClick,
+  resolvePartition,
+  unifiedThreadRef,
+  SLACK_SPEND_BADGES,
+  type ApprovalCardRespondFn,
+  type BindableContext,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { slackClickerIsGuest, slackForm } from "./slack-events.js";
+
+const log = (m: string): void => console.log(`[open-everywhere:slack] approval card: ${m}`);
+
+/** The `input_response.routed` sibling for a tap: an approval settled through a BUTTON rather than a
+ *  typed reply. RE-EXPORTED FROM CORE, never re-spelled here — one action name for every surface, so
+ *  a scorer that joins on the row cannot under-count one of them (OPE-1856). */
+export const APPROVAL_CARD_SETTLED_AUDIT_ACTION = CORE_APPROVAL_CARD_SETTLED_AUDIT_ACTION;
+/** A verified tap that settled nothing, carrying WHICH refusal it was. Core-owned, as above. */
+export const APPROVAL_CARD_REFUSED_AUDIT_ACTION = CORE_APPROVAL_CARD_REFUSED_AUDIT_ACTION;
+
+/** The settle delivery this leg needs. CORE-OWNED and bound by the front route through
+ *  `approvalCardRespondVia(args.attachSession)` — re-exported here, never re-spelled, so the address
+ *  the answer takes cannot drift per surface (OPE-1863). */
+export type ApprovalRespondFn = ApprovalCardRespondFn;
+
+/** What one verified tap did, for the front route's log line. Never thrown — this endpoint answers a
+ *  person who is waiting, so every path returns. */
+export interface ApprovalCardClickOutcome {
+  readonly handled: boolean;
+  readonly reason: string;
+  /** A line to show the tapper alone, or undefined when the outcome needs no note. */
+  readonly notice?: string;
+}
+
+/** The `block_actions` fields this leg reads, narrowed so nothing here needs Slack's own types. */
+interface ParsedApprovalClick {
+  readonly actionId: string;
+  readonly channelId: string;
+  readonly userId: string;
+  readonly teamId?: string;
+}
+
+/**
+ * Read the one `oe_input:` action out of a verified `block_actions` payload. `undefined` when the
+ * payload is not one of ours or is missing a field the decision needs — the front route then leaves
+ * it alone rather than half-handling it.
+ *
+ * THE FIRST `oe_input:` ACTION WINS and the rest are ignored: Slack sends one action per click, and a
+ * payload carrying two of ours is not a shape this host mints.
+ */
+export function parseSlackApprovalClick(payload: unknown): ParsedApprovalClick | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const p = payload as Record<string, unknown>;
+  if (!Array.isArray(p.actions)) return undefined;
+  let actionId: string | undefined;
+  for (const a of p.actions as readonly unknown[]) {
+    const id = typeof a === "object" && a !== null ? (a as Record<string, unknown>).action_id : undefined;
+    if (typeof id === "string" && parseApprovalClickId(id) !== undefined) {
+      actionId = id;
+      break;
+    }
+  }
+  if (actionId === undefined) return undefined;
+  const channel = typeof p.channel === "object" && p.channel !== null ? (p.channel as Record<string, unknown>).id : undefined;
+  const user = typeof p.user === "object" && p.user !== null ? (p.user as Record<string, unknown>).id : undefined;
+  const team = typeof p.team === "object" && p.team !== null ? (p.team as Record<string, unknown>).id : undefined;
+  if (typeof channel !== "string" || channel.length === 0) return undefined;
+  if (typeof user !== "string" || user.length === 0) return undefined;
+  return { actionId, channelId: channel, userId: user, ...(typeof team === "string" && team.length > 0 ? { teamId: team } : {}) };
+}
+
+/** The bindable a partition resolve needs from a raw interactivity payload. The team id is the ONE
+ *  attribute that matters here, and it is read off the wire rather than through a placeholder — the
+ *  same reading, and the same reason, as `slackAuthTeamId` in slack-input-response.ts. */
+function bindableForClick(click: ParsedApprovalClick): BindableContext {
+  return {
+    channel: { kind: "slack" },
+    session: { auth: { current: { attributes: { ...(click.teamId ? { team_id: click.teamId } : {}), channel_id: click.channelId } } } },
+  } as unknown as BindableContext;
+}
+
+/**
+ * The host copy that rides the delivered answer's `text` — the LABEL THIS DEPLOYMENT PUT ON THE
+ * BUTTON, read back out of the same allowlist that minted it, so the transcript says what the person
+ * actually chose. A tap carries no words, and writing the person's prose for them is not an option.
+ * The fallback capitalises the eve-minted option id, which can only be reached by a row written
+ * before an id left the allowlist; the DECISION is never this value, because eve settles on
+ * `optionId` alone.
+ */
+function approvalAnswerText(optionId: string): string {
+  return APPROVAL_BUTTON_LABELS.get(optionId.toLowerCase())?.label ?? optionId.charAt(0).toUpperCase() + optionId.slice(1);
+}
+
+/** Show the tapper alone why nothing happened. EPHEMERAL, never a message in the room: the card is
+ *  still live for somebody who may answer it, and a public "you may not answer" note tells the room
+ *  nothing it needs. Best-effort — a failed notice never changes the verdict. */
+async function notifyTapper(channelId: string, userId: string, text: string): Promise<void> {
+  try {
+    await slackForm("chat.postEphemeral", new URLSearchParams({ channel: channelId, user: userId, text }).toString());
+  } catch (err) {
+    log(`refusal notice failed to post: ${String(err)}`);
+  }
+}
+
+/**
+ * Handle one verified `oe_input:` click: resolve it, admit it, deliver the answer to eve, consume the
+ * rows. NEVER THROWS — the front route has already 200'd the interaction, and an unhandled throw here
+ * would only lose the log line.
+ *
+ * 🔴 THE ANSWER TEXT IS HOST COPY, and it must be. A tap carries no words, so a transcript that read
+ * the button as the person's own prose would be inventing their words. What rides is the host label
+ * this deployment put on that button (`Approve` / `Cancel`), which is what the person actually chose,
+ * and the `optionId` beside it is what eve settles on — `resolveApprovalOutcome` reads `optionId`
+ * ALONE, so the text is transcript only and never the decision.
+ *
+ * 🔴 CONSUME-ONCE, AND BOTH ROWS. The ticket goes so a second tap on the same card cannot answer a
+ * request eve has already settled; the outstanding-question row goes so the room's NEXT message is an
+ * ordinary wake again rather than a second answer to a settled request. Both happen only after eve
+ * accepted the delivery, exactly as the text leg orders them.
+ *
+ * THE LIMIT OF THAT, stated rather than implied: the read and the delete are not one atomic step, and
+ * the delete runs only AFTER `respond` returns, so anything arriving while the first tap is still in
+ * flight resolves against rows that are both still present. Two such deliveries each spend an
+ * admission, each call `respond`, and each can write a settled audit row — so one approval can read
+ * as decided by two taps. It is not a second DECISION: both had to be admitted and both had to name
+ * an option the request offered, and eve's own resolution refuses the second delivery for a request
+ * it already settled. A delivery that arrives after the first settle RETURNED is the covered case —
+ * the ticket is gone and it resolves `no-ticket`.
+ *
+ * 🔴 A SECOND DELIVERY IS MOST LIKELY TO BE SLACK'S OWN, NOT A SECOND PERSON, and this handler does
+ * not ack until the settle returns. Slack expects an interactivity endpoint to answer within about
+ * three seconds; what it does past that — show the tapper a connection error, redeliver, or both —
+ * is VENDOR BEHAVIOUR THIS TREE HAS NOT MEASURED, so do not read the bound above as covering it.
+ * Acking first and settling in the background would remove the delay and widen exactly the window
+ * this paragraph describes; the ordering here takes the narrower window instead. Whoever measures
+ * the real behaviour should revisit that trade, with the measurement written down.
+ */
+export async function handleSlackApprovalCardClick(payload: unknown, respond: ApprovalRespondFn): Promise<ApprovalCardClickOutcome> {
+  // 🔴 HOISTED OUT OF THE `try` SO THE `catch` CAN STAMP ITS ROW (OPE-1856). A throw anywhere below
+  // — including from the partition resolve itself — must still leave a row saying this deployment
+  // took a tap and settled nothing; core's auditor accepts an absent partition for that case.
+  let tapper = "";
+  let auditPartition: ReturnType<typeof resolvePartition> | undefined;
+  try {
+    const click = parseSlackApprovalClick(payload);
+    if (click === undefined) return { handled: false, reason: "not an oe_input: click" };
+    const parsed = parseApprovalClickId(click.actionId);
+    if (parsed === undefined) return { handled: false, reason: "oe_input: action id did not parse" };
+    tapper = click.userId;
+    const org = deploymentOrg();
+    const store = getOperationalStore();
+    const partition = resolvePartition(bindableForClick(click));
+    auditPartition = partition;
+    // THE SPEND GATE FIRST, ahead of the identity admission — the same order and the same reason
+    // `admitSlackInputResponse` takes: over budget outranks identity, and a decline must not spend a
+    // roster lookup. Its refusal copy is its own; a decline here leaves the request PENDING.
+    const spend = await ingressSpendGate({
+      bindable: bindableForClick(click),
+      door: "answer",
+      principalId: click.userId,
+      workspaceRef: click.teamId ?? null,
+      badges: SLACK_SPEND_BADGES,
+      post: async (text) => {
+        await notifyTapper(click.channelId, click.userId, text);
+      },
+    });
+    if (spend === "declined") {
+      // AUDITED, not only logged (OPE-1856): a decline is this deployment refusing a person's tap,
+      // and a refusal nobody can count is indistinguishable from a tap that never arrived.
+      await auditApprovalCardTap({ platform: "slack", principalId: click.userId, partition, outcome: { kind: "refused", reason: "spend-declined" } });
+      log(`tap declined by the spend gate — the approval stays parked`);
+      return { handled: true, reason: "spend-declined" };
+    }
+    // The room the tap came from, in the SAME vocabulary the card's ticket stored — derived through
+    // core's own codec rather than spelled here, so the two sides cannot drift on the key's shape.
+    const containerKey = unifiedThreadRef({ platform: "slack", channelId: click.channelId }).channelKey;
+    const routing = await resolveApprovalCardClick(
+      { ticket: parsed.ticket, optionId: parsed.optionId, containerKey },
+      {
+        read: (ticket) => readApprovalCardTicket(store, org, ticket),
+        // The join with the TEXT leg — see the dep's own note. Fail-CLOSED on an unreadable row: a
+        // store this leg cannot read cannot say the request is still parked, and settling on that
+        // guess is the one direction that spends a governed decision twice.
+        stillOutstanding: async (bareToken, requestId) => {
+          const outstanding = await readBridgedQuestion(store, org, bareToken).catch(() => undefined);
+          return outstanding?.requestId === requestId;
+        },
+        admit: async () => {
+          // Leg B, the same positive guest verdict both other clicker floors use, and inert on an
+          // unreadable probe (`undefined` never refuses).
+          const answererIsGuest = await slackClickerIsGuest(click.userId, click.teamId).catch(() => undefined);
+          const verdict = await admitInputResponse({
+            org: partition.org,
+            platform: partition.platform,
+            workspace: partition.workspace,
+            surface: partition.surface,
+            surfaceKey: partition.surfaceKey,
+            principalId: click.userId,
+            responses: 1,
+            ...(answererIsGuest === undefined ? {} : { answererIsGuest }),
+          });
+          return { ok: verdict.ok, floor: verdict.ok ? verdict.floor : "", notice: verdict.ok ? "" : verdict.notice };
+        },
+      },
+    );
+    if (routing.kind === "refuse") {
+      await auditApprovalCardTap({ platform: "slack", principalId: click.userId, partition, outcome: { kind: "refused", reason: routing.reason } });
+      if (routing.notice !== undefined) await notifyTapper(click.channelId, click.userId, routing.notice);
+      log(`tap settled nothing (${routing.reason}) — the approval stays parked and answerable in words`);
+      return { handled: true, reason: routing.reason, ...(routing.notice ? { notice: routing.notice } : {}) };
+    }
+    const label = approvalAnswerText(routing.optionId);
+    // 🔴 DELIVERED BY SESSION ID, never by the window token (OPE-1863): a continuation token is
+    // channel-local, and this route is the SLACK channel's, so `from(bareToken)` here named a
+    // session that never existed and the settle threw into the catch below. The token's job is the
+    // outstanding-question row on the two lines that follow.
+    await respond(routing.sessionId, { requestId: routing.requestId, optionId: routing.optionId, text: label });
+    // CONSUME-ONCE, and only now that eve accepted the delivery. A throw above skips both, which
+    // leaves the card tappable and the question answerable — the safe direction.
+    await forgetApprovalCardTicket(store, org, parsed.ticket);
+    await forgetBridgedQuestion(store, org, routing.bareToken);
+    await auditApprovalCardTap({
+      platform: "slack",
+      principalId: click.userId,
+      partition,
+      outcome: { kind: "settled", requestId: routing.requestId, optionId: routing.optionId, floor: routing.floor },
+    });
+    log(`tap settled ${routing.requestId} as "${routing.optionId}" (floor ${routing.floor})`);
+    return { handled: true, reason: "settled" };
+  } catch (err) {
+    // The approval is still parked and the card is still tappable, so the honest outcome is to say so
+    // and leave both rows in place. Never a throw: this runs after the interaction was acknowledged.
+    // AUDITED, not only logged (OPE-1856): ship #212's S-EVE-CARD leg could not say whether its tap
+    // had been refused or had thrown, because neither arm left a row. `auditApprovalCardTap` never
+    // throws, so this cannot turn a failed tap into a failed response.
+    await auditApprovalCardTap({ platform: "slack", principalId: tapper, ...(auditPartition === undefined ? {} : { partition: auditPartition }), outcome: { kind: "refused", reason: "error" } });
+    log(`tap failed (${(err as Error)?.message ?? String(err)}) — nothing was settled, the approval stays parked`);
+    return { handled: true, reason: "error" };
+  }
+}
+

package/agent/channels/slack-attachments.ts

@@ -0,0 +1,195 @@
+// Trusted Slack attachment registry — the provenance bridge between a Slack event's
+// `files[].url_private` and the `describe_image` tool.
+//
+// THE PROBLEM IT SOLVES. A Slack image sits behind `url_private`, which needs the bot token to
+// download. That token must NEVER ride a model-chosen URL (an exfil channel). So describe_image
+// can't let the model hand it a Slack URL string — but the model still needs to point at *which*
+// image it wants to see. This registry is the indirection: the wake pipeline (parseMessageEvent)
+// registers each image attachment's `url_private` under its Slack FILE ID (trusted provenance —
+// the event, not the model). describe_image's slack-attachment path takes a model-named file id,
+// resolves it HERE to the event-supplied `url_private`, and hands THAT to the authenticated fetch
+// helper (access/slack-attachment-fetch.ts). A model-supplied URL string can therefore never reach
+// the token-bearing fetch — the model can only *name* an id that a real event already recorded.
+//
+// BOUNDED: a long-lived process must not accumulate url_private entries without limit, so the map
+// evicts oldest-first past a cap. An evicted id simply fails closed in describe_image ("no such
+// attachment") — a re-post (or a fresh wake) re-registers it. url_private links are themselves
+// short-lived Slack-side, so unbounded retention would be pointless as well as leaky.
+//
+// THE CROSS-PROCESS HALF (task #107). The map above is PROCESS-LOCAL, so a DELEGATED worker — a
+// one-shot task in a SEPARATE session/process from the seat that saw the upload (delegation-reshape-
+// plan-2026-07-16.md) — can't resolve a file id it never received, and "read this uploaded file"
+// couldn't be delegated. `persistSlackAttachment` mirrors each event attachment into the DURABLE
+// operational store (org-scoped, TTL-pruned), and `resolveSlackAttachmentDurable` reads in-memory
+// first (same-process fast path) then the store (cross-process). Written ONLY from the trusted parse
+// path — never a model string — the same provenance contract the in-memory map holds. Non-image
+// uploads are persisted too (the in-memory map is image-only for describe_image), so the raw-bytes
+// read path (read_file_upload) can resolve a CSV/text/log an image reader never registered.
+
+import {
+  getOperationalStore,
+  deploymentOrg,
+  resolvePartition,
+  registerAttachmentResolver,
+  AttachmentOversizeError,
+  type SlackAttachmentRow,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { fetchSlackAttachment } from "../access/slack-attachment-fetch.js";
+
+/** A resolved attachment record — its `urlPrivate` came from a Slack event's `files[].url_private`
+ *  (trusted provenance), never a model-supplied string. */
+export interface SlackAttachmentRecord {
+  /** The Slack `url_private` download URL from the event's `files[]`. */
+  readonly urlPrivate: string;
+  /** IANA media type from the event (`files[].mimetype`), when known — describe_image uses it
+   *  because the id-based ref carries no filename extension to infer from. */
+  readonly mimeType?: string;
+  /** Original filename from the event, when known — the raw-bytes read path (read_file_upload)
+   *  infers a type from its extension when the mimetype is absent. */
+  readonly name?: string;
+  /** The Slack team id the event belonged to (for future multi-bot token routing). */
+  readonly teamId?: string;
+  /** The platform that minted this attachment id — always "slack" for records written here. Stamped
+   *  at ingest so the attachment plane's provenance is explicit end to end (channels/attachments.ts). */
+  readonly platform?: "slack";
+}
+
+/** How long a durable attachment row is retained. Slack `url_private` links are short-lived
+ *  server-side, and a delegated worker resolves its brief within hours — a day bounds the table
+ *  without stranding a legitimately slow task. */
+const SLACK_ATTACHMENT_TTL_MS = 24 * 60 * 60 * 1000;
+
+const MAX_ENTRIES = 1000;
+const registry = new Map<string, SlackAttachmentRecord>();
+
+/**
+ * Record an image attachment's trusted `url_private` under its Slack file id. THIS LIST IS THE
+ * AUDIT LIST for "who may write a fetchable url_private into the registry", so keep it exact.
+ * Two writers, both of trusted provenance:
+ *   • `parseMessageEvent` (slack-events.ts) — an Events API message, which only arrives for a room
+ *     the app is subscribed to and in;
+ *   • `registerAttachments` in the front route's SHORTCUT branch (slack-front.ts) — a message
+ *     shortcut, which Slack delivers even for a room the app is NOT in. It therefore registers
+ *     only what that branch's readability and wake gates admitted (OPE-1442). The shortcut PARSER
+ *     registers nothing: it runs at classification time, in front of those gates.
+ * A falsy id or an empty url is ignored (nothing to resolve later). Re-registering an id refreshes
+ * its recency.
+ */
+export function registerSlackAttachment(fileId: string | undefined, rec: SlackAttachmentRecord): void {
+  if (!fileId || !rec.urlPrivate) return;
+  if (registry.has(fileId)) registry.delete(fileId); // refresh insertion order (LRU-ish)
+  registry.set(fileId, { ...rec, platform: "slack" }); // stamp provenance for the attachment plane
+  while (registry.size > MAX_ENTRIES) {
+    const oldest = registry.keys().next().value;
+    if (oldest === undefined) break;
+    registry.delete(oldest);
+  }
+}
+
+/** The trusted record for a Slack file id, or undefined when this session never saw an event
+ *  carrying it (→ describe_image fails closed rather than fetching an arbitrary URL). PROCESS-LOCAL:
+ *  a cross-process worker must go through {@link resolveSlackAttachmentDurable}. */
+export function resolveSlackAttachment(fileId: string): SlackAttachmentRecord | undefined {
+  return registry.get(fileId);
+}
+
+/**
+ * Mirror one event attachment into the DURABLE store (task #107) so a delegated worker in a
+ * SEPARATE process can resolve it. Called ONLY from the trusted parse-consumption path (slack-front),
+ * with `org` resolved from the same event — never a model-supplied string. Best-effort: a store
+ * failure must never break the wake (the in-memory path still serves the same-process seat), so it
+ * swallows and logs. `org` defaults to the deployment org (single-tenant) when omitted.
+ */
+export async function persistSlackAttachment(fileId: string | undefined, rec: SlackAttachmentRecord, org?: string): Promise<void> {
+  if (!fileId || !rec.urlPrivate) return;
+  const row: SlackAttachmentRow = {
+    urlPrivate: rec.urlPrivate,
+    ...(rec.mimeType ? { mimeType: rec.mimeType } : {}),
+    ...(rec.name ? { name: rec.name } : {}),
+    ...(rec.teamId ? { teamId: rec.teamId } : {}),
+  };
+  try {
+    await getOperationalStore().putSlackAttachment(org ?? deploymentOrg(), fileId, row, new Date().toISOString(), SLACK_ATTACHMENT_TTL_MS);
+  } catch (err) {
+    console.warn(`[open-everywhere:slack-attachments] dropped a durable attachment row for "${fileId}": ${String(err)}`);
+  }
+}
+
+/**
+ * Resolve a file id ACROSS processes: the in-memory registry first (same-process fast path), then
+ * the durable store (the cross-process bridge a delegated worker needs). Returns undefined when
+ * neither knows the id (→ the caller fails closed rather than fetching an arbitrary URL). `org`
+ * defaults to the deployment org (single-tenant) when omitted.
+ */
+export async function resolveSlackAttachmentDurable(fileId: string, org?: string): Promise<SlackAttachmentRecord | undefined> {
+  const local = registry.get(fileId);
+  if (local) return local;
+  try {
+    const row = await getOperationalStore().getSlackAttachment(org ?? deploymentOrg(), fileId);
+    // Stamp provenance on the durable read too (the store is Slack-specific) so every resolved
+    // SlackAttachmentRecord carries `platform`, cross-process included.
+    return row ? { ...row, platform: "slack" } : undefined;
+  } catch (err) {
+    console.warn(`[open-everywhere:slack-attachments] durable attachment lookup for "${fileId}" failed: ${String(err)}`);
+    return undefined;
+  }
+}
+
+/**
+ * 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
+ * SAME two guarantees the in-memory/durable registry + host-pinned fetch already provide:
+ *   • it resolves a model-named id ONLY through the trusted registry (in-memory then durable,
+ *     org-scoped) — an id no real Slack event recorded returns `undefined`, so the plane fails
+ *     closed rather than fetching an arbitrary URL;
+ *   • the download rides `fetchSlackAttachment` (bot token, HOST-PINNED to Slack, SSRF-guarded,
+ *     redirect:error) against the event-supplied `url_private` — never a model string.
+ * A recognised id whose fetch fails THROWS (the plane surfaces it as a fetch failure), distinct
+ * from an unknown id (undefined). Idempotent per platform key.
+ */
+export function registerSlackAttachmentResolver(): void {
+  registerAttachmentResolver({
+    platform: "slack",
+    async resolve(attachmentId, ctx) {
+      const rec = await resolveSlackAttachmentDurable(attachmentId, resolvePartition(ctx).org);
+      if (!rec) return undefined; // not a Slack id we saw → let the plane fail closed
+      const res = await fetchSlackAttachment(ctx, { urlPrivate: rec.urlPrivate, id: attachmentId });
+      if (!res.ok) throw new Error(`fetching Slack attachment "${attachmentId}" failed (HTTP ${res.status})`);
+      return { bytes: new Uint8Array(await res.arrayBuffer()), ref: `slack-file:${attachmentId}`, mimeType: rec.mimeType };
+    },
+    // Size-guarded variant (task #107) for read_file_upload's raw-bytes read path. It resolves the
+    // TRUSTED record up front (no fetch) so the caller can refuse a type before any download, then
+    // defers the host-pinned, bot-token fetch to `pull` — which preserves the Content-Length
+    // pre-check EXACTLY: it rejects (AttachmentOversizeError, phase "declared") off the declared
+    // length BEFORE reading the body, and re-checks the actual byte count after (phase "actual").
+    async resolveGuarded(attachmentId, ctx) {
+      const rec = await resolveSlackAttachmentDurable(attachmentId, resolvePartition(ctx).org);
+      if (!rec) return undefined; // not a Slack id we saw → let the plane fail closed
+      return {
+        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;
+        },
+      };
+    },
+  });
+}
+
+// NOTE (OPE-114 stage 4): the resolver is no longer wired at module load — registerSlackProvider()
+// (agent/register.ts) calls registerSlackAttachmentResolver() at boot, the same "register in every
+// process" posture (register-adapters.ts runs in every process that can execute describe_image).
+
+/** Test seam: clear the in-memory registry so a test starts from empty. */
+export function _resetSlackAttachmentsForTest(): void {
+  registry.clear();
+}