@open-everywhere/provider-discord 0.1.0

package/agent/channels/discord-post.ts

@@ -0,0 +1,463 @@
+// Discord REST post for the `reply` tool (tools/reply.ts). This is the reply feature's own
+// Discord write seam — the parallel of slack-read.ts for the read tools, and of
+// slack-events.ts's `slackForm` for the Slack write path. It is kept separate from
+// channels/discord-gateway.ts (which has its OWN private create-message used by the completion
+// post-back) so the tools don't pull the whole gateway channel module into their import graph;
+// the auth pattern here mirrors that module's exactly. {@link discordEditMessage} is the same seam's
+// edit primitive, for the `edit_reply` tool (OPE-793).
+//
+// `Bot <token>` is Discord's scheme; the bot token is a SECRET — it rides only in the header,
+// NEVER in a log line, error string, or return value. Calls throw a clean, token-free error on
+// failure so the tool surfaces an honest result to the model (unlike the gateway's fail-silent
+// post-back, a tool must report whether the post actually landed).
+
+import { markNotApplied } from "@open-everywhere/core/agent/adapter-api.js";
+import { discordFetch } from "./discord-rest.js";
+
+const API = "https://discord.com/api/v10";
+
+/** Discord's hard per-message character cap — the ceiling {@link splitForDiscord} splits to and the
+ *  one {@link discordEditMessage} refuses past, stated once so the two can never disagree. */
+export const DISCORD_MESSAGE_MAX = 2000;
+
+function botHeaders(token: string): Record<string, string> {
+  return { authorization: `Bot ${token}`, "content-type": "application/json" };
+}
+
+function botToken(): string {
+  const token = process.env.DISCORD_BOT_TOKEN;
+  if (!token) {
+    throw new Error("DISCORD_BOT_TOKEN is not set — the reply tool needs the bot token to post to Discord.");
+  }
+  return token;
+}
+
+// Discord caps a message at 2000 chars. `splitForDiscord` breaks an over-cap reply into parts
+// that each fit, honouring three rules the reply-tool family needs (OPE-41):
+//   1. BOUNDARY-PREFERRING — cut at a paragraph/line break when one is in reach, else a sentence
+//      end, else a word boundary, and only hard-cut mid-word as a last resort. So a split lands
+//      between thoughts, not inside one.
+//   2. FENCE-SAFE — never leave a ```code fence dangling across the seam. When a cut falls inside
+//      an open fence, the part is CLOSED with ``` and the next part RE-OPENS the same fence (with
+//      its language), so every part renders as valid markdown on its own.
+//   3. NUMBERED ONLY WHEN >2 — a 1- or 2-part reply reads fine without ceremony; 3+ parts get a
+//      compact `[i/N]` header so the reader knows the order and that more is coming.
+// Guarantees forward progress and loses no CONTENT (a single boundary whitespace char is dropped
+// at each seam, exactly as the old splitter did; the fence markers + `[i/N]` headers are the only
+// added text). Lives HERE (the leaf write seam) so the unified reply arm (unified-reply.ts) can
+// split without importing the whole gateway channel module; discord-gateway.ts re-exports it, so
+// every existing importer keeps compiling untouched. Pure — exported for the test oracle.
+export function splitForDiscord(text: string, max = DISCORD_MESSAGE_MAX): string[] {
+  if (text.length <= max) return [text];
+  // Pass 1: split with the full budget. If it fits in ≤2 parts, no numbering ceremony.
+  const bare = splitRespectingFences(text, max);
+  if (bare.length <= 2) return bare;
+  // Pass 2: 3+ parts → number them. Re-split with a reduced budget so the `[i/N]\n` header still
+  // fits under the cap, then prefix the real header (N is known only after the re-split).
+  const numbered = splitRespectingFences(text, max - NUMBER_HEADER_RESERVE);
+  const n = numbered.length;
+  return numbered.map((part, i) => `[${i + 1}/${n}]\n${part}`);
+}
+
+// Reserve for the `[i/N]\n` header — `[9999/9999]\n` is 12 chars, more than any realistic reply.
+const NUMBER_HEADER_RESERVE = 12;
+const FENCE_CLOSE = "\n```";
+const FENCE_LINE = /^\s*```/;
+
+/** The fence opener (e.g. "```ts") still open after walking `body` from `start`, or null. Markdown
+ *  fences toggle (they don't nest), so a ``` line either opens — capturing its language — or closes. */
+function fenceStateAfter(start: string | null, body: string): string | null {
+  let opener = start;
+  for (const line of body.split("\n")) {
+    if (FENCE_LINE.test(line)) opener = opener === null ? line.trim() : null;
+  }
+  return opener;
+}
+
+/** Choose the cut index in (from, hardEnd], preferring a line break, then a sentence end, then a
+ *  word boundary, then a hard cut. `drop` is how many boundary whitespace chars to skip after the
+ *  cut so the seam doesn't duplicate them (a newline/space that separated the two parts). */
+function chooseCut(text: string, from: number, hardEnd: number): { end: number; drop: number } {
+  if (hardEnd >= text.length) return { end: text.length, drop: 0 };
+  const nl = text.lastIndexOf("\n", hardEnd);
+  if (nl > from) return { end: nl, drop: 1 }; // line/paragraph boundary (blank lines are newlines)
+  // Sentence end: the last ". "/"! "/"? " whose terminator sits within (from, hardEnd].
+  let sentence = -1;
+  for (const sep of [". ", "! ", "? "]) {
+    const i = text.lastIndexOf(sep, hardEnd - 1);
+    if (i > from && i + 1 < hardEnd) sentence = Math.max(sentence, i + 1); // keep the punctuation
+  }
+  if (sentence > from) return { end: sentence, drop: 1 };
+  const sp = text.lastIndexOf(" ", hardEnd);
+  if (sp > from) return { end: sp, drop: 1 };
+  return { end: hardEnd, drop: 0 }; // no boundary in reach → hard cut mid-word
+}
+
+/** Split `text` into parts whose RENDERED length (fence reopen prefix + body + fence close suffix)
+ *  never exceeds `renderBudget`, re-opening any fence left open across a seam. */
+function splitRespectingFences(text: string, renderBudget: number): string[] {
+  const parts: string[] = [];
+  let carried: string | null = null; // fence opener carried INTO the current part
+  let pos = 0;
+  while (pos < text.length) {
+    const reopen = carried !== null ? `${carried}\n` : "";
+    const avail = Math.max(1, renderBudget - reopen.length);
+    let cut = chooseCut(text, pos, Math.min(pos + avail, text.length));
+    let body = text.slice(pos, cut.end);
+    let endOpener = fenceStateAfter(carried, body);
+    let suffix = endOpener !== null ? FENCE_CLOSE : "";
+    // A still-open fence adds a closing ``` — if that tips the part over budget, recut shorter.
+    if (reopen.length + body.length + suffix.length > renderBudget && body.length > 1) {
+      cut = chooseCut(text, pos, Math.min(pos + avail - suffix.length, text.length));
+      body = text.slice(pos, cut.end);
+      endOpener = fenceStateAfter(carried, body);
+      suffix = endOpener !== null ? FENCE_CLOSE : "";
+    }
+    parts.push(`${reopen}${body}${suffix}`);
+    carried = endOpener;
+    pos = cut.end + cut.drop;
+  }
+  return parts;
+}
+
+/**
+ * Post a message to a Discord channel — `POST /channels/{id}/messages`. Returns the FIRST
+ * message's id (the audit/output anchor). Throws (never a null id) on a missing token, a non-ok
+ * status, or a response missing an id — the tool relays that to the model.
+ *
+ * OVER-CAP SPLIT (OPE-41): `content` longer than Discord's 2000-char limit is split via
+ * {@link splitForDiscord} and posted as SEVERAL messages in order, so the reply-tool path
+ * (reply-post.ts `dispatchReply`, which hands us the raw text) no longer hard-fails on a long
+ * reply the way a single over-cap POST would (400). A reply ANCHOR (`opts.replyToMessageId`)
+ * attaches only to the FIRST part — the continuation parts thread naturally after it. A
+ * within-cap `content` is one POST with the byte-identical body it always sent.
+ *
+ * `opts.replyToMessageId` anchors the (first) post as a Discord REPLY to that message
+ * (message_reference; fail_if_not_exists=false so a deleted anchor degrades to a plain post
+ * rather than a 400) — used by the single-window reply arm so the answer visibly attaches to
+ * the triggering mention.
+ */
+export async function discordPostMessage(channelId: string, content: string, opts?: { replyToMessageId?: string }): Promise<string> {
+  const parts = splitForDiscord(content);
+  let firstId: string | undefined;
+  for (const part of parts) {
+    if (!part.trim()) continue; // never POST an invisible empty part (Discord 400s on empty content)
+    // Anchor the reply only on the FIRST posted part; continuations follow it in the channel.
+    const id = await discordPostOne(channelId, part, firstId === undefined ? opts?.replyToMessageId : undefined);
+    firstId ??= id;
+  }
+  if (firstId === undefined) {
+    // DEFINITIVE (OPE-821): every part was blank, so no POST was ever issued and the room is
+    // unchanged. The post spine may release its dedupe claim on this.
+    throw markNotApplied(new Error(`Discord create-message had no content to post for channel ${channelId}`));
+  }
+  return firstId;
+}
+
+/**
+ * Open (or reuse) the 1:1 DM channel with `userId` — `POST /users/@me/channels` with a
+ * `recipient_id` (OPE-623). Returns the DM channel id, which every ordinary channel call above then
+ * addresses; Discord itself is idempotent here, so a second call for the same recipient returns the
+ * SAME channel rather than a second one.
+ *
+ * WHO CAN BE REACHED, AND WHAT A FAILURE MEANS. Discord delivers a bot DM only when the recipient
+ * shares a server with the bot AND has not turned off direct messages from server members. Neither
+ * is knowable in advance, so the refusal arrives as a 403 on the POST — an honest "this person
+ * cannot be DM'd", not a bug. It THROWS rather than resolving null, because every caller
+ * (`deliverDirectMessage`) has to be able to tell a delivered consent ask from an undelivered one:
+ * treating "could not open the channel" as a successful send would tell an initiator that somebody
+ * was asked to confirm when nobody was.
+ *
+ * Token handling matches every call in this module: the bot token rides only the header, and no
+ * response body ever reaches an error string.
+ */
+export async function discordOpenDmChannel(userId: string): Promise<string> {
+  const res = await discordFetch("POST /users/@me/channels", `${API}/users/@me/channels`, {
+    method: "POST",
+    headers: botHeaders(botToken()),
+    body: JSON.stringify({ recipient_id: userId }),
+  });
+  if (!res.ok) {
+    // DEFINITIVE (OPE-821): no message was posted — the channel was never opened — so a caller may
+    // retry or fall back without any risk of a double delivery. The status rides as a NUMBER, which
+    // carries no token and no response body.
+    throw markNotApplied(
+      Object.assign(new Error(`Discord could not open a DM channel (${res.status}) with user ${userId}`), { status: res.status }),
+    );
+  }
+  const body = (await res.json()) as { id?: unknown };
+  const id = typeof body?.id === "string" ? body.id.trim() : "";
+  if (!id) throw markNotApplied(new Error(`Discord open-DM returned no channel id for user ${userId}`));
+  return id;
+}
+
+// Discord component wire constants (stable public API integers). Defined locally for the same
+// reason approvals/discord-card.ts defines its own: importing eve's channel module for two integers
+// would widen this leaf write seam's graph.
+const COMPONENT_ACTION_ROW = 1;
+const COMPONENT_BUTTON = 2;
+const BUTTON_STYLE_SUCCESS = 3; // green — the affirmative answer
+const BUTTON_STYLE_DANGER = 4; //  red   — the rejecting answer
+
+/** One button on a DM, in Discord's own shape. `custom_id` is the CALLER's opaque routing key. */
+export interface DiscordDmButton {
+  readonly customId: string;
+  readonly label: string;
+  readonly intent: "affirm" | "reject";
+}
+
+/**
+ * Post `content` to a DM channel with a row of BUTTONS under it (OPE-622) — one
+ * `POST /channels/{id}/messages` carrying a components ACTION_ROW.
+ *
+ * 🔴 NO SPLIT, AND THAT IS DELIBERATE. `discordPostMessage` splits an over-cap reply into several
+ * messages; buttons cannot be split, and a row attached to the wrong part would sit under a
+ * fragment. So this refuses past Discord's 2000-character cap rather than truncating or fanning out,
+ * and both callers post core-owned copy: the identity consent ask, and the bridged approval card
+ * (channels/discord-post-arm.ts), whose own caller falls back to the splitting path past the cap.
+ *
+ * `opts.replyToMessageId` hangs the message under the one it answers, through the same
+ * `message_reference` the plain post path uses and with the same `fail_if_not_exists: false` degrade
+ * when the trigger is gone (OPE-1720 — a card posted onto a unified origin must land where the
+ * conversation is looking, exactly as its prose sibling does). ABSENT ⇒ a plain channel post.
+ *
+ * The bot token rides only the header, like every call in this module.
+ */
+export async function discordPostMessageWithButtons(
+  channelId: string,
+  content: string,
+  buttons: readonly DiscordDmButton[],
+  opts?: { readonly replyToMessageId?: string },
+): Promise<string> {
+  if (content.length > DISCORD_MESSAGE_MAX) {
+    throw markNotApplied(
+      new Error(`Discord create-message with buttons cannot split ${content.length} characters (cap ${DISCORD_MESSAGE_MAX}) for channel ${channelId}`),
+    );
+  }
+  const res = await discordFetch("POST /channels/{id}/messages", `${API}/channels/${channelId}/messages`, {
+    method: "POST",
+    headers: botHeaders(botToken()),
+    body: JSON.stringify({
+      content,
+      ...(opts?.replyToMessageId ? { message_reference: { message_id: opts.replyToMessageId, fail_if_not_exists: false } } : {}),
+      components: [
+        {
+          type: COMPONENT_ACTION_ROW,
+          components: buttons.map((b) => ({
+            type: COMPONENT_BUTTON,
+            style: b.intent === "affirm" ? BUTTON_STYLE_SUCCESS : BUTTON_STYLE_DANGER,
+            label: b.label,
+            custom_id: b.customId,
+          })),
+        },
+      ],
+    }),
+  });
+  if (!res.ok) {
+    throw Object.assign(new Error(`Discord create-message with buttons failed (${res.status}) for channel ${channelId}`), { status: res.status });
+  }
+  const body = (await res.json()) as { id?: unknown };
+  const id = typeof body?.id === "string" ? body.id : undefined;
+  // 🔴 DELIBERATELY UNMARKED, like discordPostOne's own missing-id branch: Discord answered 2xx, so
+  // the message IS in the channel — this host just cannot name it. Calling that definitive would
+  // license a retry that posts the ask twice.
+  if (!id) throw new Error(`Discord create-message with buttons returned no message id for channel ${channelId}`);
+  return id;
+}
+
+/** One raw `POST /channels/{id}/messages`. Kept private — every caller goes through
+ *  {@link discordPostMessage} so the 2000-char split is never bypassed. */
+async function discordPostOne(channelId: string, content: string, replyToMessageId?: string): Promise<string> {
+  const res = await discordFetch("POST /channels/{id}/messages", `${API}/channels/${channelId}/messages`, {
+    method: "POST",
+    headers: botHeaders(botToken()),
+    body: JSON.stringify({
+      content,
+      ...(replyToMessageId ? { message_reference: { message_id: replyToMessageId, fail_if_not_exists: false } } : {}),
+    }),
+  });
+  if (!res.ok) {
+    // The HTTP status rides as a NUMBER on the error (OPE-821), exactly as the edit arm below does
+    // it. The post spine reads it to tell a Discord REFUSAL (404 gone, 403 forbidden — nothing
+    // posted) from a 5xx or a timeout, which may have posted. A number carries no token and no
+    // response body, so this stays inside the token-free rule the header states.
+    throw Object.assign(new Error(`Discord create-message failed (${res.status}) for channel ${channelId}`), { status: res.status });
+  }
+  const body = (await res.json()) as { id?: unknown };
+  const id = typeof body?.id === "string" ? body.id : undefined;
+  // 🔴 DELIBERATELY UNMARKED. Discord answered 2xx, so the message IS in the channel — this host just
+  // cannot name it. Calling that definitive would license a retry that posts the message twice.
+  if (!id) throw new Error(`Discord create-message returned no message id for channel ${channelId}`);
+  return id;
+}
+
+/**
+ * Rewrite one already-posted message — `PATCH /channels/{id}/messages/{mid}` (OPE-793). Discord
+ * renders an "(edited)" marker, so the change is visible in the room.
+ *
+ * 🔴 NO SPLIT, AND THAT IS A REAL LIMIT RATHER THAN AN OMISSION. A message is ONE message: an
+ * over-cap edit cannot become several the way an over-cap POST can, so text past Discord's 2000-char
+ * cap is REFUSED here with an honest error the model can act on. Refusing beats truncating (silent
+ * data loss) and beats posting continuation messages (an edit must add nothing to the room).
+ *
+ * Ownership is decided upstream against the own-post ledger (core's channels/reply-edit.ts); Discord
+ * refusing to edit another author's message is the backstop under it. Token handling mirrors
+ * {@link discordPostMessage}: the bot token rides only the header and no response body ever reaches
+ * an error string.
+ */
+export async function discordEditMessage(channelId: string, messageId: string, content: string): Promise<void> {
+  if (content.length > DISCORD_MESSAGE_MAX) {
+    // DEFINITIVE (OPE-802): the call never leaves this host, so the message did not change and the
+    // model may post a new reply. The HTTP rejection below carries a status instead, which classes
+    // itself.
+    throw markNotApplied(
+      new Error(
+        `edit_reply couldn't update the Discord message — the new text is ${content.length} characters and Discord caps one message at ${DISCORD_MESSAGE_MAX}. A message cannot be split by an edit; shorten it, or post a new reply.`,
+      ),
+    );
+  }
+  const res = await discordFetch("PATCH /channels/{id}/messages/{id}", `${API}/channels/${channelId}/messages/${messageId}`, {
+    method: "PATCH",
+    headers: botHeaders(botToken()),
+    body: JSON.stringify({ content }),
+  });
+  if (!res.ok) {
+    // The HTTP status rides as a NUMBER on the error, not only inside the message. The edit spine
+    // (core's channels/reply-edit.ts) reads it for the failure audit row, so a platform rejection is
+    // visible in the trail with the status that caused it (OPE-798). A number carries no token and
+    // no response body, so this stays inside the token-free rule the header states.
+    throw Object.assign(new Error(`edit_reply couldn't update the Discord message (${res.status}) in channel ${channelId}`), {
+      status: res.status,
+    });
+  }
+}
+
+/**
+ * REACT (OPE-987): bare Slack-style shortcode name → the Discord-native unicode character this arm
+ * reacts with. The `react` tool's own `EMOJI_NAME_PATTERN` (core tools/react.ts) already restricts
+ * every model-given name to lowercase letters/digits/`_`/`+`/`-` — no colon, no raw unicode — so this
+ * table is the ONE place a bare name becomes something Discord's reaction endpoint accepts (a real
+ * unicode emoji, URL-encoded). Scoped to the vocabulary the noise doctrine and Tag's own acknowledge/
+ * status vocabulary actually reach for, mirroring GitHub's own answer to the same problem
+ * (github-post-arm.ts `GITHUB_REACTION_MAP`) rather than pulling in a general shortcode library —
+ * Discord's own reaction endpoint takes ANY unicode emoji, so this table is a vocabulary CHOICE, not
+ * a platform limit; growing it costs one line, never a migration.
+ */
+const DISCORD_EMOJI_MAP: Readonly<Record<string, string>> = {
+  thumbsup: "👍",
+  "+1": "👍",
+  thumbsdown: "👎",
+  "-1": "👎",
+  eyes: "👀",
+  white_check_mark: "✅",
+  heavy_check_mark: "✔️",
+  x: "❌",
+  tada: "🎉",
+  rocket: "🚀",
+  heart: "❤️",
+  fire: "🔥",
+  clap: "👏",
+  wave: "👋",
+  raised_hand: "✋",
+  raised_hands: "🙌",
+  pray: "🙏",
+  laughing: "😆",
+  joy: "😂",
+  confused: "😕",
+  thinking_face: "🤔",
+  hourglass: "⏳",
+  hourglass_flowing_sand: "⏳",
+  question: "❓",
+  exclamation: "❗",
+  warning: "⚠️",
+  octagonal_sign: "🛑",
+  "100": "💯",
+};
+
+/**
+ * REACT (OPE-987): `PUT /channels/{id}/messages/{mid}/reactions/{emoji}/@me` under the bot token —
+ * the SAME primitive `discordMessageOps.setReaction` calls for the host-placed ✋ glyph, but this one
+ * THROWS on failure (unlike that primitive, which is deliberately fail-soft — see its own header):
+ * a model-invoked `react` is a verb the model gets an honest answer from, not decoration beside work
+ * that is already running.
+ *
+ * An unmapped emoji name refuses DEFINITIVE (`markNotApplied`, OPE-825) before any byte leaves this
+ * host — the same shape GitHub's fixed content enum refuses with. A rejected PUT carries the HTTP
+ * status on the thrown error (token-free), so `platformFailureClass` can classify it without any
+ * string matching.
+ */
+export async function discordAddReaction(channelId: string, messageId: string, emojiName: string): Promise<void> {
+  const unicode = DISCORD_EMOJI_MAP[emojiName.toLowerCase()];
+  if (!unicode) {
+    throw markNotApplied(
+      new Error(
+        `react couldn't post to Discord — "${emojiName}" has no Discord emoji equivalent here; this deployment supports: ${Object.keys(DISCORD_EMOJI_MAP).join(", ")}.`,
+      ),
+    );
+  }
+  const res = await discordFetch(
+    "PUT /channels/{id}/messages/{id}/reactions/{emoji}/@me",
+    `${API}/channels/${channelId}/messages/${messageId}/reactions/${encodeURIComponent(unicode)}/@me`,
+    { method: "PUT", headers: botHeaders(botToken()) },
+  );
+  if (!res.ok) {
+    throw Object.assign(new Error(`react couldn't post to Discord — ${res.status} on channel ${channelId}`), { status: res.status });
+  }
+}
+
+/**
+ * READ-ONLY: the id of the thread that already hangs off `messageId`, or null when there is none.
+ *
+ * 🔴 IT NEVER CREATES A THREAD, and that is the whole reason it exists next to
+ * {@link discordThreadForMessage}. The EDIT path needs the same auto-thread the POST path opened
+ * (OPE-798), but at edit time a create would open a NEW empty thread that cannot hold the message
+ * being edited — a visible side effect in the room, and still a 404. So the edit path asks only
+ * "where did the reply land", and degrades to the base channel when the answer is "nowhere".
+ *
+ * Fail-soft to null on ANY failure (deleted trigger, missing permission, rate limit), matching the
+ * create-or-find sibling. Token handling is identical: the bot token rides only the header.
+ */
+export async function discordExistingThreadForMessage(channelId: string, messageId: string): Promise<string | null> {
+  try {
+    const msgRes = await discordFetch("GET /channels/{id}/messages/{id}", `${API}/channels/${channelId}/messages/${messageId}`, {
+      headers: botHeaders(botToken()),
+    });
+    if (!msgRes.ok) return null;
+    const msg = (await msgRes.json()) as { thread?: { id?: unknown } };
+    return typeof msg?.thread?.id === "string" ? msg.thread.id : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Open (or find) the thread hanging off a message — the unified reply arm's auto-thread leg.
+ * `POST /channels/{id}/messages/{mid}/threads`; when Discord answers THREAD_ALREADY_CREATED
+ * (a second reply to the same wake, or a crash-retry), falls back to reading the message's
+ * existing `thread.id`. Returns null on ANY failure (missing permission, deleted trigger,
+ * rate limit) — the caller degrades to the plain in-channel reply, never blocks the post.
+ * Token handling mirrors discordPostMessage: the bot token rides only the header, and no
+ * response body ever reaches an error string or return value.
+ */
+export async function discordThreadForMessage(channelId: string, messageId: string, name: string): Promise<string | null> {
+  try {
+    const res = await discordFetch(
+      "POST /channels/{id}/messages/{id}/threads",
+      `${API}/channels/${channelId}/messages/${messageId}/threads`,
+      {
+        method: "POST",
+        headers: botHeaders(botToken()),
+        body: JSON.stringify({ name: name.slice(0, 100) || "thread", auto_archive_duration: 1440 }),
+      },
+    );
+    if (res.ok) {
+      const body = (await res.json()) as { id?: unknown };
+      return typeof body?.id === "string" ? body.id : null;
+    }
+    // Already threaded (idempotency): read the existing thread id off the message itself.
+    return await discordExistingThreadForMessage(channelId, messageId);
+  } catch {
+    return null;
+  }
+}
+

package/agent/channels/discord-read.ts

@@ -0,0 +1,140 @@
+// The Discord read adapter — EXTRACTED from core channels/channel-read.ts (OPE-114 stage 4). A real
+// `GET /channels/{id}/messages` (bot token) mapped through linesFromDiscordMessages into the neutral
+// RenderedLine[]; registered via registerReadAdapter from registerDiscordProvider(). Discord threads
+// ARE their own channel ids (one endpoint covers a base channel AND a thread — see
+// discord-backscroll.ts), so readThread reads the thread's OWN id, carried in `thread_ts` (the
+// generic verb's per-surface "thread identifier"). The generic per-surface allowlist gate
+// (assertSurfaceAllowed) is SHARED from core (barrel) — it is platform-parameterised.
+//
+// The bot token is a SECRET — header only, never logged. Fail-LOUD (unlike fail-soft backscroll
+// enrichment): a read must surface its error. The requester is injectable for offline tests.
+
+import {
+  assertSurfaceAllowed,
+  bindFrom,
+  resolvePartition,
+  refutedReadAuthorIds,
+  type BindableContext,
+  type RenderedLine,
+  type WakeReadAddress,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { linesFromDiscordMessages, type DiscordRoleProbe } from "./discord-backscroll.js";
+import { discordAuthorRoles } from "../approvals/discord-admin.js";
+
+const DISCORD_CHANNEL_DEFAULT_LIMIT = 50;
+const DISCORD_THREAD_DEFAULT_LIMIT = 100;
+const DISCORD_MAX_PAGE = 100;
+
+/** A Discord messages GET — mirrors discord-backscroll.ts's live requester but fail-LOUD. Injectable. */
+export type DiscordReadRequester = (channelId: string, limit: number) => Promise<unknown>;
+
+const liveDiscordRead: DiscordReadRequester = async (channelId, limit) => {
+  const token = process.env.DISCORD_BOT_TOKEN;
+  if (!token) throw new Error("read: DISCORD_BOT_TOKEN is not set — the Discord read tools need the bot token.");
+  const qs = new URLSearchParams({ limit: String(Math.min(limit, DISCORD_MAX_PAGE)) }).toString();
+  const res = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages?${qs}`, {
+    headers: { authorization: `Bot ${token}` },
+  });
+  if (!res.ok) throw new Error(`read: Discord GET messages failed (HTTP ${res.status}) for channel ${channelId}.`);
+  return res.json();
+};
+
+/**
+ * Map a raw Discord messages array (newest-first) to oldest-first RenderedLine[] — reusing
+ * linesFromDiscordMessages for the exact system/empty drop + sender classification. Pure; exported
+ * for the render test.
+ *
+ * `author` IS UNCHANGED (the sender id, else `(unknown)`). OPE-474 adds the two GRADING fields
+ * beside it, taken from the sender classification linesFromDiscordMessages already made: a `user`
+ * line carries its `authorId`, and a `bot`/`agent` line is marked a machine and drops out of the
+ * probe. An `unknown` line carries neither, which is the fail-open answer for an author nobody can
+ * name.
+ */
+export function discordLinesFromRaw(raw: unknown): RenderedLine[] {
+  if (!Array.isArray(raw)) return [];
+  const ordered = [...(raw as Array<Record<string, unknown>>)].reverse(); // Discord: newest-first → oldest-first
+  return linesFromDiscordMessages(ordered).map((l) => ({
+    author: l.senderId ?? "(unknown)",
+    ts: l.ts,
+    text: l.text,
+    ...(l.senderType === "bot" || l.senderType === "agent"
+      ? { bot: true }
+      : l.senderType === "user" && l.senderId !== undefined
+        ? { authorId: l.senderId }
+        : {}),
+  }));
+}
+
+// --- the OPE-474 non-member author leg ---------------------------------------------------------
+//
+// 🔴 DISCORD CANNOT REFUTE AN AUTHOR ITSELF, at all. It has no organisation concept — guild
+// membership IS the boundary, and a community guild admits the world — so the ONLY author-grain
+// evidence here is the operator's author-trust register (identity/author-trust.ts, OPE-516). This is
+// the same conclusion discord-backscroll.ts's `gradeDiscordContextLines` reached for the wake leg,
+// and this adapter deliberately reproduces its shape rather than a second one.
+//
+// `member.pending` — the trigger's own screening signal — is NOT available here either, and the
+// reason is structural rather than an omission: it rides the gateway relay's MESSAGE_CREATE member
+// object, and Discord's documented Message object (what `GET /channels/{id}/messages` returns) has
+// no `member` field at all.
+//
+// THE ROLE PROBE IS COST-GATED THEN FAIL-OPEN, in that order — {@link refutedReadAuthorIds} runs the
+// gate and this supplies the probe:
+//   1. UNARMED guild (the default posture): no register query is worth building, so NO role fetch
+//      runs. Zero new I/O.
+//   2. ARMED guild: each DISTINCT author gets ONE TTL-cached {@link discordAuthorRoles} call.
+//   3. `undefined` from the probe means CANNOT CHECK, and the join skips that author entirely —
+//      never an unverified `[]`. On a guild armed the documented-usual way
+//      (`{ membership: "discord/<g>/role:*" }`) an unverified empty array would make every author
+//      look role-less and therefore `external`, which marked ordinary colleagues' messages. That
+//      exact bug was caught in OPE-475; the contract that prevents it is in read-author-trust.ts.
+
+export const discordReadAdapter = {
+  platform: "discord" as const,
+  /**
+   * OPE-929 — Discord's own spelling of "which room and which thread is this turn in".
+   *
+   * 🔴 A DISCORD THREAD IS ITS OWN CHANNEL. There is no thread id inside a channel to carry, so the
+   * CONTAINER and the THREAD ROOT are the same snowflake on a thread turn, and `readThread` is the
+   * verb that reads it (it fetches `threadTs` directly — see below). The turn is a thread turn when
+   * the ingress stamped a PARENT channel id, which is exactly what `domainSurface` carries: the
+   * mapper sets it only from `parent_channel_id`, so its presence IS "this is a thread".
+   *
+   * A base-channel turn has no parent stamp, so it reports no thread root and `read_thread` refuses
+   * it honestly.
+   */
+  wakeAddress(ctx: BindableContext): WakeReadAddress | undefined {
+    const b = bindFrom(ctx);
+    const container = typeof b.target?.["channelId"] === "string" ? (b.target["channelId"] as string) : undefined;
+    if (!container) return undefined;
+    return { container, ...(b.domainSurface ? { threadRoot: container } : {}) };
+  },
+  async readChannel(ctx: BindableContext, channel: string, limit?: number, req: DiscordReadRequester = liveDiscordRead): Promise<readonly RenderedLine[]> {
+    await assertSurfaceAllowed(ctx, "discord", channel);
+    return discordLinesFromRaw(await req(channel, limit ?? DISCORD_CHANNEL_DEFAULT_LIMIT));
+  },
+  async readThread(ctx: BindableContext, channel: string, threadTs: string, limit?: number, req: DiscordReadRequester = liveDiscordRead): Promise<readonly RenderedLine[]> {
+    // A Discord thread is its own channel id — read `thread_ts` (the thread's id), allowlist-checked.
+    await assertSurfaceAllowed(ctx, "discord", threadTs);
+    return discordLinesFromRaw(await req(threadTs, limit ?? DISCORD_THREAD_DEFAULT_LIMIT));
+  },
+  /** OPE-474 / OPE-534 — the register leg only (see the note above). It answers with the refuted
+   *  AUTHOR IDS, because core reads the one answer twice: the turn mark and the `withhold` body
+   *  replacement. `roleProbe` is injected ONLY so a test can drive the grading offline; every live
+   *  call defaults to the TTL-cached live probe. */
+  async refutedAuthorIds(ctx: BindableContext, lines: readonly RenderedLine[], roleProbe: DiscordRoleProbe = discordAuthorRoles): Promise<readonly string[]> {
+    const p = resolvePartition(ctx);
+    // `workspace` is the GUILD id for a guild surface, and the DM partner's user id for a DM
+    // (discord-identity.ts `bindDiscord`). A DM's key can never be an armed tenant — arming is by
+    // guild — so the cost gate answers `false` there without a lookup, which is the right answer:
+    // a DM has no guild membership to refute against.
+    const tenantKey = p.workspaceKey;
+    const guildId = p.workspace;
+    return await refutedReadAuthorIds(lines, tenantKey, {
+      memberships: async (authorId) => {
+        const roles = await roleProbe(guildId, authorId);
+        return roles === undefined ? undefined : roles.map((r) => `${tenantKey}/role:${r}`);
+      },
+    });
+  },
+};