@open-everywhere/provider-discord 0.1.0

package/agent/channels/discord-identity.ts

@@ -0,0 +1,269 @@
+// Pure Discord→OpenEverywhere identity capture. The Discord channel (discord.ts) calls these
+// to stow RAW Discord facts (guild/channel/user ids + the channel `type`) into the
+// session auth context's `attributes`. The INTERPRETATION of those facts into
+// mode/visibility lives here too (discordMode/discordVisibility) — the one tested place
+// for the security-critical "is this private?" decision, mirroring Slack's split (the
+// Slack interpretation lives in agent/identity/binding.ts; per the build brief the
+// Discord interpretation is co-located here so the test can call it directly, and the
+// binding mapper imports it). This file imports no eve types — only OpenEverywhere's own
+// SessionMode / Visibility — so it stays trivially unit-testable.
+
+import type {
+  SessionMode,
+  Visibility,
+  Trust,
+  BindableContext,
+  IdentityMapper,
+  RawIdentity,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { rootDmGrainAttrs } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** Structural match for eve's SessionAuthContext (attributes + principal). */
+export interface OpenEverywhereDiscordAuth {
+  readonly authenticator: string;
+  readonly principalId: string;
+  readonly principalType: string;
+  readonly attributes: Record<string, string>;
+}
+
+// Discord channel `type` integers we distinguish (as strings, since auth attributes
+// are strings). https://discord.com/developers/docs/resources/channel#channel-object-channel-types
+// 1 = DM, 3 = GROUP_DM; everything else with a guild id is a guild text channel /
+// thread (0 GUILD_TEXT, 5 GUILD_ANNOUNCEMENT, 10/11/12 threads, 15 FORUM, …).
+const DISCORD_CHANNEL_DM = "1";
+const DISCORD_CHANNEL_GROUP_DM = "3";
+
+export interface DiscordIdentityInput {
+  readonly userId: string;
+  /** The guild (server) id — present iff invoked in a server; absent for DMs. */
+  readonly guildId?: string;
+  readonly channelId: string;
+  /** Discord numeric channel `type` as a string ("1" DM, "3" group DM, else guild). */
+  readonly channelType?: string;
+  /**
+   * Positively-confirmed @everyone VIEW_CHANNEL — only set when a (future) enrichment
+   * proves the guild channel is readable by everyone. Absent today (Discord interactions
+   * carry no such bit), so the binding fails closed to private. See discordVisibility.
+   */
+  readonly everyoneCanView?: boolean;
+  /**
+   * The PARENT channel id when `channelId` is a THREAD (Discord threads are their own
+   * channel ids, so without this a thread's surface key can never match a domain that
+   * lists its parent channel, and channel-scoped spend caps never see thread turns —
+   * backlog item 22). Set at ingress where it's known for free (the auto-thread re-key:
+   * the parent IS the base channel the mention landed in) or via the cached REST lookup
+   * (channels/discord-channel-info.ts) for messages arriving in an existing thread.
+   * BEST-EFFORT: absent → the binding falls back to thread grain (today's behaviour) —
+   * this only ever WIDENS a thread to its parent's domain/cap scope, never gates a turn.
+   */
+  readonly parentChannelId?: string;
+  /**
+   * Whether the acting guild member is PENDING — has not yet completed the guild's membership
+   * screening (Community-server rules / verification gate). Discord carries `member.pending`
+   * on the interaction payload (and on gateway member objects) for FREE — no privileged intent
+   * and no REST call. A pending member is not a fully-admitted participant, so it demotes the
+   * surface's trust to `external` (the closest Discord analog of a "guest / unverified" account).
+   * `undefined` (the common case — most guilds run no screening, so the field is simply absent,
+   * or a DM has no guild member) → no verdict, existing fail-closed/vouch behaviour. See
+   * discordTrust for exactly what this signal does and does NOT prove.
+   */
+  readonly memberPending?: boolean;
+  /**
+   * The id of the message that triggered this turn, when the ingress knows one (OPE-671). A
+   * slash-command interaction carries none (Discord interactions are not message events), so this
+   * is set only by the gateway's message-relay path, where the raw message id is known for free.
+   * See {@link RawIdentity.anchorMessageId} for why this rides a SEPARATE field from `threadTs`.
+   */
+  readonly messageId?: string;
+}
+
+/** Build the auth context OpenEverywhere dispatches with — raw facts as string attributes. */
+export function buildDiscordAuth(input: DiscordIdentityInput): OpenEverywhereDiscordAuth {
+  const attributes: Record<string, string> = {
+    channel_id: input.channelId,
+    user_id: input.userId,
+  };
+  if (input.guildId) attributes.guild_id = input.guildId;
+  if (input.channelType) attributes.channel_type = input.channelType;
+  if (typeof input.everyoneCanView === "boolean") attributes.everyone_can_view = String(input.everyoneCanView);
+  if (input.parentChannelId) attributes.parent_channel_id = input.parentChannelId;
+  if (typeof input.memberPending === "boolean") attributes.member_pending = String(input.memberPending);
+  if (input.messageId) attributes.message_id = input.messageId;
+  // Root-DM grain stamp (window-tool-gating §D-DM, widened to group DMs): a 1:1 DM (type 1, or no
+  // guild) OR a group DM (type 3 ⇒ "mpim") is a STANDING seat ⇒ narrowed hands — both are closed
+  // multi-party conversations with no channel identity. discordMode's "channel" branch (a positive
+  // guild id) is unambiguously excluded, so a real guild channel/thread is never over-narrowed.
+  const dmMode = discordMode(input.channelType, input.guildId);
+  Object.assign(attributes, rootDmGrainAttrs(dmMode === "dm" || dmMode === "mpim"));
+  return { authenticator: "discord", principalId: input.userId, principalType: "discord-user", attributes };
+}
+
+/**
+ * The PARENT channel id when a raw payload's `channel` partial is a THREAD (types
+ * 10/11/12) — Discord stamps `parent_id` on thread channel objects, so the interaction
+ * path gets the item-22 thread→parent grain for free (the gateway's message path has no
+ * channel partial and pays a cached REST lookup instead — discord-channel-info.ts).
+ * Non-threads return undefined: a base channel's `parent_id` is its CATEGORY, never a
+ * grain anchor. Defensive — the payload is Discord's raw JSON. Pure.
+ */
+export function threadParentFromRawChannel(raw: Record<string, unknown>): string | undefined {
+  const ch = raw["channel"];
+  if (ch && typeof ch === "object") {
+    const c = ch as Record<string, unknown>;
+    const isThread = c["type"] === 10 || c["type"] === 11 || c["type"] === 12;
+    const parent = c["parent_id"];
+    if (isThread && typeof parent === "string" && parent.length > 0) return parent;
+  }
+  return undefined;
+}
+
+/**
+ * Discord channel type / guild presence → session mode (channel | dm | mpim).
+ * A guild id positively marks a server channel/thread; a DM (1) and group DM (3) are
+ * the only non-channel surfaces. With no type captured, the absence of a guild id
+ * reliably marks a DM with the bot (interactions outside a guild are DMs).
+ */
+export function discordMode(channelType: string | undefined, guildId: string | undefined): SessionMode {
+  if (channelType === DISCORD_CHANNEL_DM) return "dm";
+  if (channelType === DISCORD_CHANNEL_GROUP_DM) return "mpim";
+  if (guildId && guildId.length > 0) return "channel";
+  return "dm"; // no guild → a DM surface
+}
+
+/**
+ * Discord facts → visibility. FAIL CLOSED. Unlike Slack (an explicit is_private bit
+ * on the channel), Discord exposes NO clean public/private signal on an inbound
+ * interaction: guild-channel readability is governed by per-role permission overwrites
+ * (@everyone's VIEW_CHANNEL), which the interaction payload doesn't carry. So:
+ *   - DMs / group-DMs are inherently private surfaces (never public).
+ *   - Guild text channels / threads default to `private` too — conservative, so a
+ *     surface's learnings stay surface-tier and never leak up to shared (workspace)
+ *     memory on an under-specified event.
+ * Only a positively-confirmed @everyone-readable channel (everyoneCanView="true", from
+ * a future enrichment that probes the @everyone role's permissions) yields `public`.
+ * When in doubt, private.
+ */
+export function discordVisibility(everyoneCanView: string | undefined, mode: SessionMode): Visibility {
+  if (mode === "dm" || mode === "mpim") return "private"; // DMs / group-DMs are never public
+  if (everyoneCanView === "true") return "public"; // explicit @everyone-readable guild channel
+  return "private"; // unknown @everyone readability -> fail closed
+}
+
+/**
+ * The `member.pending` flag from a raw Discord interaction / gateway payload — Discord's
+ * membership-screening bit, stamped on the guild `member` object when the server runs a rules /
+ * verification gate. Pure + defensive (raw JSON). `true`/`false` are returned as-is; anything
+ * else (no `member`, a DM, an older payload) → `undefined`. Free at ingress: no privileged
+ * intent, no REST lookup.
+ */
+export function discordMemberPendingFromRaw(raw: Record<string, unknown>): boolean | undefined {
+  const m = raw["member"];
+  if (m && typeof m === "object") {
+    const p = (m as Record<string, unknown>)["pending"];
+    if (typeof p === "boolean") return p;
+  }
+  return undefined;
+}
+
+/**
+ * Discord member → trust (memory gate). Discord has NO org-employee concept — a guild is the
+ * only boundary, and guilds are routinely PUBLIC community servers, so being a guild member is
+ * NOT proof of internal trust (that always requires an operator vouch / OE_TRUST). The one
+ * POSITIVE demotion signal Discord hands us for free is `member.pending`: a member who has not
+ * completed the guild's membership screening is unverified, so a pending member DEMOTES to
+ * `external` — the Discord analog of a Slack guest / stranger, and it overrides an operator
+ * vouch exactly as Slack's restricted-DM-partner verdict does (bindFrom precedence).
+ *
+ * What it PROVES (pending=true): the user has not cleared the guild's rules/verification gate →
+ * demote. What it does NOT prove (pending=false / absent): internal trust — most guilds run no
+ * screening at all, so the field is usually absent, and even a fully-admitted member of a public
+ * guild is a stranger. So a non-pending member yields `undefined` (no verdict): the surface
+ * stays fail-closed to `external` unless the operator vouches — mirroring Slack, where channel
+ * membership alone never grants internal trust.
+ */
+export function discordTrust(memberPending: string | undefined): Trust | undefined {
+  if (memberPending === "true") return "external"; // membership screening incomplete → demote (wins over vouch)
+  return undefined; // non-pending / unknown → no verdict → existing fail-closed/vouch chain
+}
+
+// --- the identity MAPPER (moved out of core identity/binding.ts in OPE-114 stage 4) ---------
+// Interprets the raw facts the Discord channel stowed in auth attributes (guild_id, channel_id,
+// channel_type, user_id, everyone_can_view, parent_channel_id, member_pending). workspace = the
+// GUILD (server) — the org boundary; a DM (no guild) keys to the caller's own user id so the DM
+// surface stays isolated. mode/visibility/trust interpretation lives in the helpers above (the one
+// tested place). Registered by registerDiscordProvider() via the registerIdentityMapper seam.
+//
+// The three attribute helpers are LOCAL COPIES of core binding.ts's module-private probes (attr /
+// authOf / authPrincipalId) — deliberately not barrel ports (they are three-line structural reads
+// over the public BindableContext shape; a mapper author outside core reads its own platform's
+// attributes itself, exactly as bindNotion does in @open-everywhere/provider-notion).
+
+type AuthAttrs = Readonly<Record<string, string | readonly string[]>> | undefined;
+
+function discordAuthOf(ctx: BindableContext): { attributes?: AuthAttrs; principalId?: string } | null {
+  return ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? null;
+}
+
+function discordAttr(a: AuthAttrs, keys: readonly string[]): string | undefined {
+  if (!a) return undefined;
+  for (const k of keys) {
+    const v = a[k];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (Array.isArray(v) && typeof v[0] === "string" && v[0].length > 0) return v[0];
+  }
+  return undefined;
+}
+
+function discordPrincipalId(ctx: BindableContext): string | undefined {
+  const p = discordAuthOf(ctx)?.principalId;
+  return p && p.length > 0 ? p : undefined;
+}
+
+export const bindDiscord: IdentityMapper = (ctx): RawIdentity => {
+  const a = discordAuthOf(ctx)?.attributes;
+  const channelId = discordAttr(a, ["channel_id", "channelId"]);
+  const guildId = discordAttr(a, ["guild_id", "guildId"]);
+  const channelType = discordAttr(a, ["channel_type", "channelType"]);
+  const everyoneCanView = discordAttr(a, ["everyone_can_view", "everyoneCanView"]);
+  const userId = discordAttr(a, ["user_id", "userId"]);
+  const messageId = discordAttr(a, ["message_id", "messageId"]);
+  const mode = discordMode(channelType, guildId);
+  return {
+    // Guild = the org boundary; a DM (no guild) keys to the caller's user id.
+    workspace: guildId ?? userId,
+    surface: channelId,
+    // A THREAD turn carries its parent channel id (stamped at ingress), so domain membership /
+    // spend caps resolve at the PARENT channel grain, matching Slack. Absent → thread grain.
+    domainSurface: discordAttr(a, ["parent_channel_id", "parentChannelId"]),
+    mode,
+    visibility: discordVisibility(everyoneCanView, mode),
+    // Trust: guild membership alone is NEVER internal (public servers are strangers); the one
+    // positive free signal is member.pending (OPE-60) → discordTrust demotes it to external.
+    trust: discordTrust(discordAttr(a, ["member_pending", "memberPending"])),
+    principalId: discordPrincipalId(ctx) ?? userId,
+    // THE ENGAGEMENT-REGISTRY KEY (OPE-661). Discord has no thread ts: a thread is its own channel,
+    // so the gateway keys the registry by the channel id — `engagementKey(msg)` returns
+    // `msg.channelId`, and the wake gate reads back `getThreadEngagement(partition, msg.channelId)`.
+    // The same id is this binding's `surface`, so `discord/<guild>/<channelId>` + `<channelId>`
+    // addresses the exact row the gate consults. Publishing it here is what lets `stand_down` mark
+    // that row; without it the tool found no anchor and threw on every Discord turn.
+    //
+    // GUILD SURFACES ONLY, and the omission is the honest half. The gate short-circuits a DM before
+    // the engagement read (`isDm || mentionsBot ? null : …`), so a mark on a DM key would suppress
+    // nothing. A DM therefore carries NO anchor, and `stand_down` says it could not stop rather than
+    // writing a row that changes nothing.
+    ...(mode === "channel" && channelId ? { engagementKey: channelId } : {}),
+    // THE STOP-HAND ANCHOR (OPE-671). `threadTs` stays Slack-shaped (see its own field doc on
+    // SurfaceBinding — ~twenty consumers read it as a Slack thread_ts API parameter), so a Discord
+    // message id rides its OWN field instead, exactly the OPE-661 precedent for `engagementKey`.
+    // Set whenever the ingress knows the triggering message (the gateway's relay path); absent on a
+    // slash-command interaction (no message) and on any fire with no live trigger — both already
+    // degrade safely, since hooks/turn-anchor.ts's ✋ placement is fail-soft on a missing anchor.
+    // UNLIKE `engagementKey`, not restricted to guild channels — a Discord DM turn has a real
+    // triggering message too, and a DM delegation is just as stoppable as a guild one.
+    ...(messageId ? { anchorMessageId: messageId } : {}),
+    // Post-back needs the channel id; the guild id + channel type ride along as RAW FACTS so a
+    // routine fire (no live interaction) can re-derive workspace (guild) and mode (dm vs channel).
+    target: channelId ? { channelId, ...(guildId ? { guildId } : {}), ...(channelType ? { channelType } : {}) } : undefined,
+  };
+};

package/agent/channels/discord-interaction-defer.ts

@@ -0,0 +1,123 @@
+// THE DEFERRED INTERACTION RESPONSE (OPE-1282) — how a Discord door answers work that outlasts the
+// three-second interaction token.
+//
+// WHAT WAS WRONG. Discord gives an interactions endpoint THREE SECONDS to answer, and it does NOT
+// redeliver an expired token. A door that decides first and answers second — `await the work, then
+// return the reply` — therefore has a window in which the work really lands and the person sees a
+// red "This interaction failed" over it. `access/discord-grant-click.ts` is that shape: an APPROVE
+// spends a 2000 ms borrow-read budget, then a CAS, a grant insert, audit rows and an awaited post
+// into the requesting room. When it overruns, the owner believes their approval failed while a
+// conversation can already spend their credential, and a second tap answers "that request is no
+// longer open" — true, and reading like a second failure. Slack does not have this: it redelivers an
+// interactivity payload it has not seen answered. Discord does not.
+//
+// THE SHAPE THAT CLOSES IT — ack, then decide, then edit:
+//   1. Answer the interaction IMMEDIATELY with {@link deferredEphemeralResponse} (`type 5`,
+//      DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE, `flags 64`). Discord renders "thinking…", privately,
+//      and the token is now good for fifteen minutes instead of three seconds.
+//   2. Do the work off the response path, under the host's `waitUntil`.
+//   3. Replace the placeholder with the real answer through {@link editOriginalInteractionResponse}.
+//
+// 🔴 THE EPHEMERAL FLAG RIDES THE DEFER, NOT THE EDIT, and that is not a style choice. Discord fixes
+// a response's visibility at the FIRST response; the follow-up edit carries no flags and cannot
+// change it. A defer sent without `flags 64` makes the eventual answer PUBLIC — on the grant door
+// that would publish one person's credential decision into the channel. The flag is therefore part
+// of the ack, and a test pins it.
+//
+// 🔴 THE FOLLOW-UP NEEDS NO BOT TOKEN AND NO NEW CONFIGURATION. The interaction webhook route is
+// authenticated by the interaction TOKEN itself, and both halves of the address — `application_id`
+// and `token` — ride the interaction payload Discord already signed. {@link interactionFollowUp}
+// reads them from that verified envelope and returns `undefined` when either is missing, which is
+// what lets a caller fall back to answering synchronously rather than deferring into silence.
+//
+// 🔴 THE INTERACTION TOKEN IS A CREDENTIAL. It authorises anyone holding it to write as the app for
+// fifteen minutes. It never reaches a log line, an error string or an audit row from this module —
+// `editOriginalInteractionResponse` builds the URL and reports only the HTTP status.
+//
+// EVERY WRITE GOES THROUGH `discordFetch` (the OPE-1236 seam), so the follow-up honours a 429's
+// `retry_after` like every other Discord write. `discord-rest-seam-test.ts` §3 reds on a bare
+// `fetch(` in this package, and this module holding its own would be exactly that.
+
+import { discordFetch, type DiscordFetchDeps } from "./discord-rest.js";
+
+const API = "https://discord.com/api/v10";
+
+/** Discord interaction-response wire constants, defined locally for the same reason each door
+ *  defines its own: this package holds no shared wire-constant module, and a door that cannot read
+ *  its own numbers is harder to review than one that repeats them. */
+const RESPONSE_DEFERRED_CHANNEL_MESSAGE = 5; // DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE
+const EPHEMERAL = 64; // MessageFlags.EPHEMERAL — only the clicker sees it
+
+/** The address a follow-up edit is sent to: the app, and the interaction's own bearer token. */
+export interface InteractionFollowUp {
+  readonly applicationId: string;
+  /** 🔴 A CREDENTIAL for fifteen minutes. Never logged, never audited, never in an error string. */
+  readonly token: string;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * The follow-up address carried by one verified interaction envelope, or `undefined` when either
+ * half is absent.
+ *
+ * 🔴 `undefined` MUST MEAN "DO NOT DEFER". A door that deferred without an address would ack with
+ * "thinking…" and then have no way to say anything else — a permanent placeholder, which is worse
+ * than the slow answer this whole module exists to replace. Callers fall back to the synchronous
+ * shape instead. Unreachable on a real Discord payload (both fields are always present); written as
+ * a real branch because the alternative failure is silent and permanent.
+ */
+export function interactionFollowUp(raw: unknown): InteractionFollowUp | undefined {
+  if (!isObject(raw)) return undefined;
+  const applicationId = str(raw["application_id"]);
+  const token = str(raw["token"]);
+  return applicationId === undefined || token === undefined ? undefined : { applicationId, token };
+}
+
+/** The immediate ack: "thinking…", visible only to the clicker. See the header for why the flag
+ *  cannot be moved to the follow-up. */
+export function deferredEphemeralResponse(): Record<string, unknown> {
+  return { type: RESPONSE_DEFERRED_CHANNEL_MESSAGE, data: { flags: EPHEMERAL } };
+}
+
+/**
+ * Replace the deferred placeholder with the real answer.
+ *
+ * NEVER THROWS. This runs off the response path, under `waitUntil`, on a decision that has ALREADY
+ * been made and written — an unsent follow-up costs the person their explanation, and throwing here
+ * would additionally poison whatever else that background promise carries. Returns whether the edit
+ * landed, so a caller can log the difference.
+ *
+ * The URL's `@original` is the deferred message itself; Discord has no other handle on it.
+ */
+export async function editOriginalInteractionResponse(
+  followUp: InteractionFollowUp,
+  content: string,
+  deps: DiscordFetchDeps = {},
+): Promise<boolean> {
+  try {
+    const res = await discordFetch(
+      "PATCH /webhooks/{application.id}/{interaction.token}/messages/@original",
+      `${API}/webhooks/${encodeURIComponent(followUp.applicationId)}/${encodeURIComponent(followUp.token)}/messages/@original`,
+      {
+        method: "PATCH",
+        // NO `authorization` HEADER, deliberately: the interaction token in the path IS the
+        // authorisation, and Discord rejects this route when a bot token is sent alongside it.
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ content }),
+      },
+      deps,
+    );
+    return res.ok;
+  } catch {
+    // A 429 that outlasts the seam's attempts arrives as `RateLimitExhaustedError`; a transport
+    // failure arrives as itself. Neither may escape — see the paragraph above.
+    return false;
+  }
+}

package/agent/channels/discord-message-ops.ts

@@ -0,0 +1,127 @@
+// The Discord SurfaceMessageOps — the bot-token REST transport for the ANCILLARY chat message ops
+// generic core features dispatch through channels/surface-message-ops.ts (OPE-114 stage 4):
+//   - postText   — a plain create-message (the hosted-artifact URL, the float notice, the approval
+//                  decision notice). `replyToMessageId` anchors it via message_reference. Rides the
+//                  reply feature's own write seam (discord-post.ts discordPostMessage — the 2000-char
+//                  split + reply anchor already live there).
+//   - editMessage — PATCH /channels/{id}/messages/{mid} (an approval notice's decided-state rewrite).
+//   - postFiles  — a hand-rolled multipart/form-data create-message (post_file's uploads). eve's
+//                  Discord API is JSON-only, so payload_json + one files[i] part per file.
+//   - permalink  — the message's own URL (request_access's PR body, OPE-303). NO network: Discord's
+//                  message URL is a pure composition of ids we already hold.
+// Registered by registerDiscordProvider(). The bot token is a SECRET — header only, never logged; on
+// failure we surface the STATUS only.
+
+import type { SurfaceMessageOps, OutboundFile } from "@open-everywhere/core/agent/adapter-api.js";
+import { discordPostMessage } from "./discord-post.js";
+import { discordFetch } from "./discord-rest.js";
+
+const API = "https://discord.com/api/v10";
+
+function botToken(): string {
+  const token = process.env.DISCORD_BOT_TOKEN;
+  if (!token) throw new Error("DISCORD_BOT_TOKEN is not set — the bot token is required to post to Discord.");
+  return token;
+}
+
+export const discordMessageOps: SurfaceMessageOps = {
+  platform: "discord",
+  postText(channelId, text, opts) {
+    return discordPostMessage(channelId, text, opts?.replyToMessageId ? { replyToMessageId: opts.replyToMessageId } : undefined);
+  },
+  async editMessage(channelId, messageId, text) {
+    const res = await discordFetch("PATCH /channels/{id}/messages/{id}", `${API}/channels/${channelId}/messages/${messageId}`, {
+      method: "PATCH",
+      headers: { authorization: `Bot ${botToken()}`, "content-type": "application/json" },
+      // 🔴 `components: []` STRIPS THE BUTTONS, AND IT IS LOAD-BEARING (OPE-1260). Discord leaves a
+      // message's components untouched when a PATCH omits them, so without this line a card rewritten
+      // to a closed state kept four live buttons over copy saying the request was already over.
+      // Slack's own rewrite behaves this way already: `chat.update` sends a replacement `blocks`
+      // array and the buttons go with it.
+      //
+      // THE CALLER INVENTORY, because the strip is only safe while it holds. This arm is reached from
+      // ONE place — core's `channels/surface-message-ops.ts` `editSurfaceText` — whose only production
+      // caller is `access/credential-grant-card.ts` `rewriteGrantCard`. That helper now has FOUR
+      // callers: the sweep's expiry, the approve-time catalogue refusal, and (OPE-1278) the owner's
+      // own approve and decline. ALL FOUR RUN ONLY AFTER THE ASK ROW IS TERMINAL OR DECIDED — each
+      // one follows the CAS that closed the ask — so the strip still deletes no live control. An
+      // owner on Discord reaches this arm; an owner on Slack reaches `chat.update` instead.
+      // 🔴 A CALLER THAT MEANS "EDIT THE BODY, KEEP THE BUTTONS" MUST NOT USE THIS ARM — it has no way
+      // to say so, and this line would delete a live control. The core interface says the same.
+      body: JSON.stringify({ components: [], content: text }),
+    });
+    if (!res.ok) throw new Error(`Discord edit-message failed (${res.status}) for channel ${channelId}`);
+  },
+  /**
+   * `https://discord.com/channels/<guild|@me>/<channel>/<message>` — the canonical Discord message
+   * link, composed rather than fetched (there is no getPermalink API and none is needed).
+   *
+   * 🔴 THE DM CASE IS WHY `ref.dm` EXISTS AND A HEURISTIC WOULD NOT DO. A Discord DM binds
+   * `workspace` to the USER id (core identity/binding.ts), and a user id and a guild id are both
+   * snowflakes — indistinguishable by shape. Putting a user id in the guild slot yields a URL that
+   * looks right and resolves to nothing, which is worse than no link at all in a PR body an admin
+   * reads to decide a grant. So a DM composes the `@me` form, and a channel with no workspace
+   * resolves `undefined` rather than guessing either way.
+   *
+   * ⚠️ NOT YET REACHED BY THE ONE CORE CONSUMER, and the reason is in the BINDING, not here.
+   * `request_access` asks for a permalink to `binding.threadTs`, and this bundle's identity mapper
+   * (channels/discord-identity.ts) does not set that field at all — Discord threads are their own
+   * channel ids, so the binding carries a `channelId` and no per-message anchor. So a Discord
+   * access request still freezes no permalink, exactly as before, and its PR body falls back to
+   * naming the channel + scope. Giving the mapper a `threadTs` is not a free fix: that field also
+   * drives approval-card threading and the float notice, so it is its own change. Written down
+   * rather than left to be rediscovered — this method is correct and currently idle.
+   */
+  async permalink(ref) {
+    const guild = ref.dm ? "@me" : ref.workspace;
+    return guild ? `https://discord.com/channels/${guild}/${ref.channelId}/${ref.messageId}` : undefined;
+  },
+  /**
+   * `{PUT|DELETE} /channels/{id}/messages/{mid}/reactions/{emoji}/@me` — the bot's own reaction,
+   * URL-encoded. This is the transport behind core's ✋ stop affordance (OPE-418).
+   *
+   * NEVER THROWS, deliberately, unlike the three ops above: a reaction is decoration beside work
+   * that is already running, so a missing permission must cost the turn its stop button, not the
+   * turn. A DELETE of a reaction that was never added 404s — that is the idempotent no-op, not an
+   * error.
+   */
+  async setReaction(channelId, messageId, emoji, on) {
+    const encoded = encodeURIComponent(emoji);
+    try {
+      const res = await discordFetch(
+        on ? "PUT /channels/{id}/messages/{id}/reactions/{emoji}/@me" : "DELETE /channels/{id}/messages/{id}/reactions/{emoji}/@me",
+        `${API}/channels/${channelId}/messages/${messageId}/reactions/${encoded}/@me`,
+        { method: on ? "PUT" : "DELETE", headers: { authorization: `Bot ${botToken()}` } },
+      );
+      if (!res.ok && !(!on && res.status === 404)) {
+        console.warn(`[open-everywhere:discord] reaction ${on ? "add" : "remove"} failed (${res.status}) for message ${messageId}`);
+      }
+    } catch (err) {
+      console.warn(`[open-everywhere:discord] reaction ${on ? "add" : "remove"} error: ${(err as Error)?.message ?? String(err)}`);
+    }
+  },
+  async postFiles(channelId, files: readonly OutboundFile[], comment) {
+    const form = new FormData();
+    const attachments = files.map((file, i) => ({ id: i, filename: file.filename, ...(file.caption ? { description: file.caption } : {}) }));
+    form.append("payload_json", JSON.stringify({ ...(comment ? { content: comment } : {}), attachments }));
+    files.forEach((file, i) => {
+      // A fresh ArrayBuffer copy so the Blob owns contiguous bytes regardless of the source view.
+      const ab = file.bytes.buffer.slice(file.bytes.byteOffset, file.bytes.byteOffset + file.bytes.byteLength) as ArrayBuffer;
+      form.append(`files[${i}]`, new Blob([ab], { type: file.contentType }), file.filename);
+    });
+    // No explicit content-type header — fetch derives the multipart boundary from the FormData.
+    const res = await discordFetch("POST /channels/{id}/messages", `${API}/channels/${channelId}/messages`, {
+      method: "POST",
+      headers: { authorization: `Bot ${botToken()}` },
+      body: form,
+    });
+    if (!res.ok) throw new Error(`Discord create-message (files) failed (HTTP ${res.status}) for channel ${channelId}`);
+    // Discord's create-message response carries the new message's own `id` — the same field
+    // discordPostOne reads for a plain text post (discord-post.ts). Hand it back so post_file's
+    // audit row can stamp `detail.id`, matching the reply path's shape (OPE-932). DELIBERATELY
+    // UNMARKED when absent, like discordPostOne: a 2xx means the message IS in the channel — this
+    // host just cannot name it, never an error worth failing an otherwise-successful upload over.
+    const body = (await res.json().catch(() => undefined)) as { id?: unknown } | undefined;
+    return typeof body?.id === "string" ? body.id : undefined;
+  },
+};

package/agent/channels/discord-origin-codec.ts

@@ -0,0 +1,105 @@
+// The Discord UnifiedWakeOrigin codec — MOVED VERBATIM out of core's channels/wake-origin-codecs.ts
+// (OPE-114 stage 4). STORED-DATA COMPATIBILITY IS THE CONTRACT: a Discord origin is JSON-serialised
+// into the durable operational store and fail-closed re-validated on read, so every behaviour here
+// is frozen by core's scripts/wake-origin-fixtures-test.ts (run from the app root with this bundle's
+// boot wiring). Validator tolerances (typeof-only optional checks, extra unknown fields) are
+// LOAD-BEARING for rows already on disk — never tighten them here.
+//
+// The `UnifiedWakeOrigin` TYPE union (including BOTH discord arms) stays in core — it is the wire
+// schema for stored rows; only the codec BEHAVIOUR lives in the bundle, registered by
+// registerDiscordProvider() (../register.ts).
+//
+// OPE-315 added a SECOND discord arm — a `dm: true`-discriminated DM/group-DM variant — so the
+// validator became an XOR. Every existing GUILD row keeps validating byte for byte: the guild branch
+// is the old predicate verbatim, and the additions are all on the new positive discriminant.
+
+import type { UnifiedWakeOrigin, WakeOriginCodec } from "@open-everywhere/core/agent/adapter-api.js";
+
+type DiscordOrigin = Extract<UnifiedWakeOrigin, { platform: "discord" }>;
+
+/** COLON-FREE by construction (a task windowId is `[^:]+` — core channels/window-key.ts): any colon
+ *  in a raw surface id is folded to `_`, deterministically, so spawn + ingress agree on identity. */
+const noColon = (s: string): string => s.replace(/:/g, "_");
+
+/** A DM-variant origin — narrowed on the positive discriminant, never on the ABSENCE of guildId. */
+const isDmOrigin = (o: DiscordOrigin): o is Extract<DiscordOrigin, { dm: true }> => "dm" in o && o.dm === true;
+
+export const discordWakeOriginCodec: WakeOriginCodec<DiscordOrigin> = {
+  validate: (o) => {
+    // TWO valid shapes, enforced as an XOR (never both, never neither) — the Linear arm's model.
+    //  • GUILD: a non-empty guildId + NO `dm`. Unchanged from the original single shape, byte for
+    //    byte: guildId is REQUIRED because the Discord privacy floor
+    //    (discord-gateway.ts discordSingleWindowPrivacyOk) can never have admitted a guildless
+    //    surface into a shared window, and this validator enforces the same invariant on the reply
+    //    path. `messageId` and `autoThreadName` stay typeof-only optionals.
+    //  • DM (OPE-315): `dm === true` + NO guildId + NO autoThreadName. A DM/group-DM reply needs
+    //    only the channel id (POST /channels/{id}/messages under the bot token).
+    //
+    // 🔴 THE XOR IS DELIBERATELY BIDIRECTIONAL. "dm:true AND a guildId" is INVALID — not "the guild
+    // wins", not "the dm wins". That is the IMPERSONATION direction: a DM-shaped row that acquired
+    // guild authority would reach the guild-keyed threadRef, markThreadEngaged, and `discord/<guild>`
+    // vouch keys. And the guild arm still refuses guildless BY OMISSION (D1): nothing here relaxes
+    // it, so `divertDiscordWakeToUnifiedWindow`'s `guildId: msg.guildId ?? ""` fall-through stays
+    // invalid exactly as before — pinned by the two unmodified guildless-rejection fixture rows.
+    //
+    // autoThreadName is forbidden on the DM shape (D4) because the reply leg's auto-thread branch is
+    // guild-keyed (discord-post-arm.ts writes `discord/${origin.guildId}` engagement rows); a DM
+    // carrying it would mint `discord/undefined/...`. messageId is allowed — cosmetic
+    // message_reference anchoring with no guild-shaped consequence. That is the whole line: forbid
+    // exactly the fields with guild-keyed effects.
+    //
+    // OPE-1719 adds `thread` to the GUILD shape only, and it is a LITERAL-`true` optional rather
+    // than a typeof-boolean optional: the field's whole job is to be a POSITIVE thread signal, so
+    // `thread: false` must not validate and then read as "a thread that says it is not one". It is
+    // forbidden on the DM shape because a Discord DM has no threads at all — the same "forbid
+    // exactly the fields whose effects the shape cannot carry" line `autoThreadName` sits on.
+    if (typeof o.channelId !== "string" || o.channelId.length === 0) return false;
+    if (o.messageId !== undefined && typeof o.messageId !== "string") return false;
+    const isDm = o.dm === true && o.guildId === undefined && o.autoThreadName === undefined && o.thread === undefined;
+    const isGuild =
+      o.dm === undefined &&
+      typeof o.guildId === "string" &&
+      o.guildId.length > 0 &&
+      (o.autoThreadName === undefined || typeof o.autoThreadName === "string") &&
+      (o.thread === undefined || o.thread === true);
+    return isDm || isGuild;
+  },
+  // The DM namespace is `discord/dm/<channelId>` — a literal `dm` segment where a guild id sits on
+  // the guild shape. Collision-free because a Discord guild id is a decimal snowflake and can never
+  // be the string "dm". Relied on rather than enforced at the type level, so it is asserted in the
+  // fixtures oracle; if it were ever violated the blast radius is ROUTING (a shared thread-ownership
+  // row + taskWindowId prefix), not authority — a reply still goes to the stored origin.
+  threadRef: (origin) =>
+    isDmOrigin(origin)
+      ? { channelKey: noColon(`discord/dm/${origin.channelId}`), threadKey: noColon(origin.channelId) }
+      : { channelKey: noColon(`discord/${origin.guildId}/${origin.channelId}`), threadKey: noColon(origin.channelId) },
+  // THE POSITIVE SIGNAL, and nothing else (OPE-1719). A Discord thread is its own channelId, so the
+  // id proves nothing; the gateway stamps `thread: true` at mint from the relay payload's channel
+  // type, and this reads exactly that stamp. Every other shape — a plain guild channel, a DM, and
+  // every stored row minted before the field existed — reads FALSE and routes to the standing seat,
+  // which is the fail-closed direction and byte-identical to the behaviour this replaced.
+  isThreadScoped: (origin) => !isDmOrigin(origin) && origin.thread === true,
+  containerId: (origin) => origin.channelId,
+  // THE PLACEMENT AXIS (OPE-1826). Discord is the SECOND surface whose post placement sits OUTSIDE
+  // its conversation identity, and until this member existed nothing said so: `threadRef` keys on the
+  // channel id alone (a Discord thread IS its own channel id), while the post arm hangs the answer on
+  // `messageId` as a `message_reference`. So two wakes in one channel are ONE conversation naming two
+  // different messages to reply under — Slack's `replyAnchorTs` shape exactly.
+  //
+  // 🔴 `messageId` ONLY, NEVER `autoThreadName`. The post arm reads both and only one is a PLACEMENT:
+  // `autoThreadName` decides whether the answer opens a NEW thread off the message, which MOVES the
+  // post out of the conversation it was asked in. The carry's own guarantee is that it can place a
+  // post and never move one, so the name is deliberately outside this axis and outside the carry
+  // below. A DM origin carries no message anchor at all — there is nothing to hang under in a 1:1 —
+  // and answers `undefined` through the same emptiness-is-absence read every other field takes.
+  placementRef: (origin) => (typeof origin.messageId === "string" && origin.messageId.length > 0 ? origin.messageId : undefined),
+  // THE CARRY (OPE-1826), narrowing-only and byte-for-byte the contract Slack's arm holds: fill a
+  // placement the target LACKS, never overwrite one, change no other field. A target that already
+  // names a message keeps it, because the model named THAT wake and answering it where it was asked
+  // is the honest reading. Core re-validates the result and re-tests the conversation, so this arm
+  // can fill a gap and cannot move a post even if this line were wrong.
+  carryPlacement: (target, source) =>
+    !(target.messageId && target.messageId.length > 0) && typeof source.messageId === "string" && source.messageId.length > 0
+      ? ({ ...target, messageId: source.messageId } as DiscordOrigin)
+      : target,
+};