@open-everywhere/provider-slack 0.5.0 → 0.6.0

package/agent/app-manifest.ts

@@ -62,6 +62,24 @@ export interface SlackAppManifestOptions {
    * The MCP toggle itself (the app config's Agents section) has no manifest field, so it stays a click.
    */
   readonly personalMcp?: boolean;
+  /**
+   * The side panel's suggested prompts (OPE-2457) — the `slack.suggestedPrompts` setting, which the
+   * caller reads (this module imports nothing). Absent or empty ⇒ the manifest offers none. The setup
+   * CLI passes none: it runs before the app's settings resolve, and the post-deploy re-paste from the
+   * ops tool or `/setup` carries them.
+   */
+  readonly suggestedPrompts?: readonly { readonly title: string; readonly message: string }[];
+}
+
+/** Slack's limit on `features.agent_view.agent_description` (the manifest reference: 300). */
+export const SLACK_AGENT_DESCRIPTION_MAX = 300;
+
+/** The side panel's one-line description. Names the configured agent, never the brand on its own. */
+function slackAgentDescription(appName: string): string {
+  return `Ask ${appName} beside anything you are reading in Slack. It is your own direct-message conversation, with the same rules as a DM.`.slice(
+    0,
+    SLACK_AGENT_DESCRIPTION_MAX,
+  );
 }
 
 /** The path the person's OAuth sign-in returns to — core's `OE_OAUTH_CALLBACK_PATH`
@@ -104,6 +122,19 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
         // it delivers `app_home_opened` (below), and the front route publishes the page
         // (channels/slack-home.ts).
         app_home: { home_tab_enabled: true, messages_tab_enabled: true, messages_tab_read_only_enabled: false },
+        // THE SIDE PANEL (OPE-2457) — Slack's agent experience. With `agent_view` on, a person can
+        // open the app's Messages tab beside any channel, and what they send there is an ordinary
+        // `message.im` to their own DM seat (channels/slack-side-panel.ts). `agent_view`, not the
+        // older `assistant_view`: Slack's manifest reference says a NEW app can only use `agent_view`.
+        // 🔴 FOR AN EXISTING APP THE SWITCH IS ONE-WAY: Slack cannot move an app from `assistant_view`
+        // back, and its people need a hard refresh. An app that never had `assistant_view` (every
+        // install of this manifest before OPE-2457) has nothing to switch from.
+        agent_view: {
+          agent_description: slackAgentDescription(appName),
+          ...(opts.suggestedPrompts && opts.suggestedPrompts.length > 0
+            ? { suggested_prompts: opts.suggestedPrompts.map((p) => ({ title: p.title, message: p.message })) }
+            : {}),
+        },
         bot_user: { display_name: appName, always_online: true },
         // The "/oe" ZERO-INFERENCE control command (agent/commands/core.ts). Declared here rather
         // than left to a manual setup step because one of its subcommands is `/oe stop` (OPE-418),
@@ -119,7 +150,7 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             description: `${appName} control-plane commands (stop, status, budget) — no model turn.`,
             // Every subcommand `parseOeCommandTokens` accepts (packages/core/agent/commands/core.ts).
             // scripts/slack-app-manifest-test.ts fails if one is missing here.
-            usage_hint: "stop | status | budget [raise <usd> | clear] | rate <n> | help",
+            usage_hint: "stop | status | budget [raise <usd> | clear] | rate <n> | optout [on | off] | help",
             should_escape: false,
           },
         ],
@@ -212,6 +243,9 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             // knows. Without it the canvas refresh fails with `missing_scope`, logged and audited
             // per channel, and memory itself is unaffected.
             "canvases:write",
+            // The side panel (OPE-2457): Slack requires it for `app_context_changed`, the event whose
+            // subscription makes Slack attach the viewed room to each side-panel `message.im`.
+            "assistant:write",
             // Slack requires this bot scope on an app whose people connect to Slack's MCP server
             // (OPE-2421). Declared only when the app declares "search Slack as you".
             ...(personalMcp ? [SLACK_MCP_BOT_SCOPE] : []),
@@ -236,6 +270,7 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
           //   app_home_opened → no scope (the Home tab page, OPE-2451)
           //   channel_shared → channels:read, groups:read (re-run the memory canvas gate, OPE-2451)
           //   user_change → users:read (automatic offboarding on a deactivated member, OPE-2423)
+          //   app_context_changed → assistant:write (the side panel's viewed room, OPE-2457)
           // scripts/slack-app-manifest-test.ts derives the handled set from the code and fails if
           // this list drops one (OPE-2223).
           bot_events: [
@@ -250,6 +285,7 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             "app_home_opened",
             "channel_shared",
             "user_change",
+            "app_context_changed",
           ],
         },
         // The INTERACTIVITY Request URL — the SAME public route Event Subscriptions uses. Every

package/agent/channels/slack-events.ts

@@ -17,6 +17,7 @@
 // envelope reaches `routeMessageEvent`. Until then this is unit-tested but unmounted.
 
 import { slackContinuationToken } from "eve/channels/slack";
+import { parseSlackAppContext, type SlackAppContextRoom } from "./slack-side-panel.js";
 import { callSlackWebApi } from "./slack-web-api.js";
 import { slackBotToken } from "../setup/credentials.js";
 import { RateLimitExhaustedError } from "@open-everywhere/core/agent/adapter-api.js";
@@ -265,6 +266,10 @@ export interface ParsedMessageEvent {
    *  the wake envelope so the agent knows an image exists and can `describe_image` it. Empty/
    *  absent when the message carries no files. Never the bytes — just id/name/mimetype/url. */
   readonly attachments?: readonly WakeAttachment[];
+  /** The room the person was viewing in the side panel (OPE-2457), from the event's `app_context`.
+   *  UNVERIFIED — slack-side-panel.ts `sidePanelViewedRoom` gates it before any use. Absent on every
+   *  event that carries no channel entity, which is every non-panel message. */
+  readonly appContext?: SlackAppContextRoom;
 }
 
 /** Parse Slack's `files[]` (on a message event's inner message) into attachment references.
@@ -710,6 +715,7 @@ export function parseMessageEvent(envelope: SlackEventEnvelope): ParsedMessageEv
   const teamId = envelope.team_id ?? (typeof e.team === "string" ? e.team : undefined);
   const enterpriseId = slackEnterpriseIdFromEnvelope(envelope);
   const attachments = parseSlackFiles(inner.files);
+  const appContext = parseSlackAppContext(e);
   // TRUSTED PROVENANCE: record each IMAGE attachment's url_private under its Slack file id so
   // describe_image's `attachmentId` path (via the attachment plane's Slack resolver) can resolve the
   // model-named id → this event's url_private and fetch it with the bot token
@@ -738,6 +744,8 @@ export function parseMessageEvent(envelope: SlackEventEnvelope): ParsedMessageEv
     // Image/file attachments (docs Part B) — read off the same inner message the text came
     // from (so an edit's post-edit files win). Absent for the common no-file message.
     attachments,
+    // The side panel's viewed room (OPE-2457) rides the OUTER event, never an edit's inner message.
+    ...(appContext === undefined ? {} : { appContext }),
   };
 }
 
@@ -1058,6 +1066,10 @@ export interface SlackWakeOpts {
    *  (channels/seat-catch-up.ts `catchUpUnavailableReason`). Rendered as a trusted `<system-note>`;
    *  unset ⇒ no note, which is every Slack wake, because Slack registers a fetch. */
   readonly catchUpUnavailable?: string;
+  /** OE's own trusted note for this wake (`<system-note>`): fixed words around host-checked ids only.
+   *  Set by the DM door alone — the side panel's viewed room and the person's opt-out
+   *  (slack-side-panel.ts `slackDmSystemNote`). Unset ⇒ no note, byte-identical to before. */
+  readonly systemNote?: string;
   /**
    * THE NAME-DROP HYDRATION, ON THE SEAT ROAD (OPE-1725). The surrounding conversation
    * {@link routeNameDropEvent} fetches for a name-drop, as RAW {@link ContextLine}s — renderWake
@@ -1142,6 +1154,7 @@ function slackJudgedWake(
     ...(addressing === "name-drop" ? { nameDrop: { followUp: "follows-on-reply" as const } } : {}),
     // The catch-up bound, stated on the wake that could not take one ({@link SlackWakeOpts.catchUpUnavailable}).
     ...(opts.catchUpUnavailable !== undefined ? { catchUpUnavailable: opts.catchUpUnavailable } : {}),
+    ...(opts.systemNote !== undefined ? { systemNote: opts.systemNote } : {}),
     // The name-drop hydration's side-channel slot ({@link SlackWakeOpts.contextLines}). Spread
     // conditionally so a wake that states none carries no key at all — the shape every
     // characterization golden was taken against.

package/agent/channels/slack-front.ts

@@ -120,7 +120,13 @@ import {
   tailAuthorGrain,
   dmWindowRegistryKey,
   stampSurfaceEventVerified,
+  readPersonOptOut,
+  auditPersonOptOutRefusal,
+  PERSON_OPT_OUT_SHORTCUT_NOTICE,
+  PERSON_OPT_OUT_UNREADABLE_NOTICE,
+  type PersonOptOutState,
 } from "@open-everywhere/core/agent/adapter-api.js";
+import { sidePanelViewedRoom, slackDmSystemNote } from "./slack-side-panel.js";
 import {
   renderWakeMessage,
   slackChannelFactsFor,
@@ -219,7 +225,10 @@ export type FrontDecision =
   /** An `oe_home:` click on the Home tab (OPE-2451) — ours: run a button, or open an item's modal. */
   | { readonly kind: "home-click"; readonly reason: string; readonly click: ParsedHomeClick }
   /** A submission of the Home tab's own modal (OPE-2451) — ours: run the action, republish the page. */
-  | { readonly kind: "home-submit"; readonly reason: string; readonly submission: ParsedHomeSubmission };
+  | { readonly kind: "home-submit"; readonly reason: string; readonly submission: ParsedHomeSubmission }
+  /** An `app_context_changed` (OPE-2457) — ours, and nothing to do. The subscription exists only so
+   *  Slack attaches the viewed room to each side-panel `message.im`; the change itself wakes nothing. */
+  | { readonly kind: "context-change"; readonly reason: string };
 
 /**
  * Best-effort decode of a urlencoded interactivity body into an `oe_approval:` block_actions
@@ -446,6 +455,13 @@ export function classifyEnvelope(rawBody: string, contentType: string): FrontDec
     if (open) return { kind: "home-open", reason: "app_home_opened (home tab) — publish the person's page", open };
     return { kind: "forward", reason: "app_home_opened for a tab other than home — nothing to publish" };
   }
+  if (eventType === "app_context_changed") {
+    // THE SIDE PANEL (OPE-2457). Slack fires this each time the person moves the panel to another
+    // room. The room that matters arrives on the `message.im` they then send (`app_context`), so a
+    // change alone wakes nothing — but it is acknowledged HERE rather than forwarded, because a
+    // forward costs eve a parse and a re-verify for every click the person makes in Slack.
+    return { kind: "context-change", reason: "app_context_changed — the room rides the next side-panel message; nothing to wake" };
+  }
   if (eventType === "user_change") {
     // OPE-2423: slackChannel drops it, and a DEACTIVATED user is ours — automatic offboarding.
     return { kind: "user-change", reason: "user_change — a deactivation report candidate", env };
@@ -667,6 +683,13 @@ export interface FrontOptions {
    *  governance DM-delivery arm. Defaults to the live call; FAIL-CLOSED: undefined ⇒ the shortcut
    *  wakes nothing and says so, never a wake in a guessed room. Injectable for tests. */
   readonly openDirectMessageChannel?: (userId: string) => Promise<string | undefined>;
+  /** The person opt-out read (OPE-2436): may the agent act on this person's content? Defaults to
+   *  core's `readPersonOptOut`, which is fail-CLOSED (an unreadable store reads as opted out).
+   *  Injectable for tests. */
+  readonly personOptOutFor?: (org: string, principalId: string) => Promise<PersonOptOutState>;
+  /** Tell one person, privately in their own DM, why a shortcut they pressed did nothing (OPE-2436).
+   *  Best-effort. Defaults to `conversations.open` + `chat.postMessage`. Injectable for tests. */
+  readonly postPrivateNotice?: (userId: string, text: string) => Promise<void>;
   /** The trigger author's two membership facts, from ONE `users.info` probe — the exact pair every
    *  wake route in slack-events.ts resolves. Two readers: the native `app_mention` forward's
    *  external-policy gate, which calls it only when that policy is not inert (so a deployment on the
@@ -1066,6 +1089,13 @@ export function buildFrontHandler(innerHandler: RouteHandler, opts: FrontOptions
   const seatedSurface = opts.seatedSurfaceFor ?? slackDomainUsesUnifiedWindow;
   const mentionPolicyFor = opts.mentionPolicyFor ?? slackSingleWindowMentionPolicy;
   const openDirectMessageChannel = opts.openDirectMessageChannel ?? liveOpenDirectMessageChannel;
+  const personOptOutFor = opts.personOptOutFor ?? readPersonOptOut;
+  const postPrivateNotice =
+    opts.postPrivateNotice ??
+    (async (userId: string, text: string) => {
+      const dm = await openDirectMessageChannel(userId);
+      if (dm) await slackForm("chat.postMessage", new URLSearchParams({ channel: dm, text }).toString());
+    });
   const resolveDmSeat = opts.resolveDmSeat ?? ((org, dm, atIso) => liveGetOrCreateDmSeat(org, dm, atIso));
   const touchDmSeatFn = opts.touchDmSeatFn ?? liveTouchDmSeat;
   const dmPartnerTrustFor = opts.dmPartnerTrustFor ?? liveDmPartnerTrust;
@@ -1572,9 +1602,25 @@ export function buildFrontHandler(innerHandler: RouteHandler, opts: FrontOptions
       // by design (the seat is one long-lived session over the whole DM, so replaying history a live
       // session already holds would duplicate it) — the tail is exactly the case that reasoning does
       // not cover, because a rotation is when the session stops holding it.
+      // THE SIDE PANEL (OPE-2457) AND THE PERSON OPT-OUT (OPE-2436) — two host facts for a 1:1 DM, in
+      // one trusted note. The viewed room passes every strictest-default gate first
+      // (slack-side-panel.ts); the opt-out tells the seat not to promise memory the write road will
+      // refuse anyway. A group DM states neither: it has no single person, and no panel.
+      const systemNote = isGroup
+        ? undefined
+        : slackDmSystemNote({
+            viewedRoom: await sidePanelViewedRoom({
+              room: ev.appContext,
+              teamId: ev.teamId,
+              partnerTrust,
+              channelInternal: async (id) => (await channelFactsFor(id)).internal === true,
+            }),
+            personOptOut: ev.userId ? await personOptOutFor(p.org, ev.userId) : undefined,
+          });
       const message = renderWakeMessage(ev, () => atIso, {
         dm: true,
         trust: wakeTrust,
+        ...(systemNote === undefined ? {} : { systemNote }),
         // The FENCE BACKSTOP for the whole DM family (OPE-1486) — the SAME refutation the taint stamp
         // and the policy gate read, so the three cannot disagree about one author. On a 1:1 it is a
         // no-op in practice (a refuted partner is already `unauth`, and `unauth` is already fenced);
@@ -1912,6 +1958,32 @@ export function buildFrontHandler(innerHandler: RouteHandler, opts: FrontOptions
       // Keyed on the click, not the message — a person may invoke the same shortcut on the same
       // message twice on purpose, and only Slack's redelivery of ONE click is a duplicate.
       if (!(await notYetSeenKey(shortcutWakeKey(sc), sev))) return new Response(null, { status: 200 });
+      // 🔴 THE PERSON OPT-OUT (OPE-2436). A message shortcut hands the agent somebody's message to act
+      // on — summarise it, answer it, file it. When the message's AUTHOR opted out of agent actions on
+      // their content and somebody ELSE pressed the button, nothing wakes: one refusal row, and a
+      // private line to the person who pressed it. The author's own shortcut on their own message is
+      // their own request, so it wakes as before. The read is fail-closed (core `readPersonOptOut`).
+      const shortcutAuthor = sc.kind === "message" ? sc.message?.userId : undefined;
+      if (shortcutAuthor && shortcutAuthor !== sc.userId) {
+        const p = resolvePartition(bindableFor(sev));
+        const authorOptOut = await personOptOutFor(p.org, shortcutAuthor);
+        if (authorOptOut.optedOut) {
+          console.log(`[open-everywhere:slack-front] message shortcut "${sc.callbackId}" in ${shortcutChannelId}: refused — the message's author opted out`);
+          args.waitUntil(
+            Promise.allSettled([
+              auditPersonOptOutRefusal(
+                { org: p.org, platform: p.platform, workspace: p.workspace, surface: p.surface, principalKey: shortcutAuthor },
+                "message-shortcut",
+                { requestedBy: sc.userId, storeReadable: authorOptOut.readable },
+              ),
+              // An unreadable store is the fail-closed GUESS, never the author's decision, so the presser
+              // is not told the author asked for anything.
+              postPrivateNotice(sc.userId, authorOptOut.readable ? PERSON_OPT_OUT_SHORTCUT_NOTICE : PERSON_OPT_OUT_UNREADABLE_NOTICE),
+            ]),
+          );
+          return new Response(null, { status: 200 });
+        }
+      }
       // BOTH halves of the attachment registry, seeded ONLY on a click that reaches a DISPATCHER —
       // the in-memory one for this process's seat, the durable one for a delegated worker in
       // another. (A dispatcher can still refuse further down, as `routeSupervisorEvent`'s own
@@ -2319,6 +2391,8 @@ export function buildFrontHandler(innerHandler: RouteHandler, opts: FrontOptions
       return OK();
     }
 
+    if (decision.kind === "context-change") return OK();
+
     if (decision.kind === "user-change") {
       // AUTOMATIC OFFBOARDING (OPE-2423). The signature above has authenticated the envelope, so its
       // `team_id` is the workspace that delivered this report. Every other decision — the

package/agent/channels/slack-home.ts

@@ -1,5 +1,5 @@
 // THE SLACK APP HOME TAB (OPE-2451) — the person's own page: what the agent remembers about them,
-// what their domains know, and (OPE-2456, later) their rules. Core owns the page model
+// what their domains know, and their rules (OPE-2456). Core owns the page model
 // (`home/home-view.ts`); this module is the Slack half: it parses the three Slack deliveries the
 // page needs, builds the VERIFIED viewer, renders Block Kit, and drives the dialogs.
 //
@@ -36,6 +36,8 @@ import {
   runHomeAction,
   SLACK_HOME_WIRE,
   type BindableContext,
+  type Domain,
+  type DomainMembershipProbe,
   type HomeBlock,
   type HomeDomainMembership,
   type HomeViewer,
@@ -252,6 +254,8 @@ function homeActionModal(input: {
   readonly itemText: string;
   readonly title: string;
   readonly yes: string;
+  /** What the confirmation does, from the section that owns the action. */
+  readonly note?: string;
 }): Record<string, unknown> {
   const quoted = escapeSlackText(clip(input.itemText, 2800));
   return {
@@ -274,7 +278,7 @@ function homeActionModal(input: {
           ]
         : [
             { type: "section", text: { type: "mrkdwn", text: `> ${quoted}` } },
-            { type: "context", elements: [{ type: "mrkdwn", text: "I remove this line from your memory everywhere it is stored. You cannot undo it." }] },
+            { type: "context", elements: [{ type: "mrkdwn", text: escapeSlackText(input.note ?? "I remove this line from your memory everywhere it is stored. You cannot undo it.") }] },
           ],
   };
 }
@@ -348,8 +352,14 @@ export async function buildSlackHomeViewer(ids: ParsedHomeInteraction, deps: Sla
   };
 }
 
-/** The domains a person belongs to through an internal channel. Fail-soft: a failed page ends the walk. */
-async function slackDomainMemberships(userId: string, workspaceKey: string, deps: SlackHomeDeps): Promise<HomeDomainMembership[]> {
+/** The domains a person belongs to through an internal channel. Fail-soft: a failed page ends the walk.
+ *  The Home tab lists a domain only when it has memory to show (`keep`). */
+async function slackDomainMemberships(
+  userId: string,
+  workspaceKey: string,
+  deps: SlackHomeDeps,
+  keep: (domain: Domain) => boolean = (d) => d.memory !== undefined,
+): Promise<HomeDomainMembership[]> {
   const domains = getConfig().loadDomains();
   const byDomain = new Map<string, HomeDomainMembership>();
   let cursor: string | undefined;
@@ -367,7 +377,7 @@ async function slackDomainMemberships(userId: string, workspaceKey: string, deps
       if (!channelId) continue;
       const surfaceKey = `${workspaceKey}/${channelId}`;
       const domain = domainForChannel(surfaceKey, domains);
-      if (!domain || domain.memory === undefined) continue;
+      if (!domain || !keep(domain)) continue;
       if (!(await deps.channelInternal(channelId))) continue;
       const existing = byDomain.get(domain.name);
       const room = { surfaceKey, nativeId: channelId };
@@ -379,6 +389,30 @@ async function slackDomainMemberships(userId: string, workspaceKey: string, deps
   return [...byDomain.values()];
 }
 
+/**
+ * THE DM QUESTION'S MEMBERSHIP PROBE (OPE-2452), registered as Slack's `DomainMembershipProbe`. The SAME
+ * trust gate the Home tab applies, applied to the person who asks from their DM: a full member of the
+ * workspace (`users.info`, fail-closed), and only the domain channels Slack confirms internal
+ * (`conversations.info`, fail-closed). Unlike the Home tab it keeps a domain with no memory: a domain
+ * with no silo still has a seat that can answer.
+ */
+export function slackDomainMembershipProbe(deps: SlackHomeDeps = liveSlackHomeDeps()): DomainMembershipProbe {
+  return async ({ principalId, workspaceKey }) => {
+    try {
+      const [platform, teamId] = workspaceKey.split("/");
+      if (platform !== "slack" || !teamId || principalId.length === 0) return { fullMember: false, rooms: [] };
+      if ((await deps.authorIsMember(principalId, teamId)) !== true) return { fullMember: false, rooms: [] };
+      const memberships = await slackDomainMemberships(principalId, workspaceKey, deps, () => true);
+      return {
+        fullMember: true,
+        rooms: memberships.flatMap((m) => m.rooms.map((r) => ({ domain: m.domain.name, surfaceKey: r.surfaceKey, origin: { platform: "slack" as const, channelId: r.nativeId } }))),
+      };
+    } catch {
+      return { fullMember: false, rooms: [] };
+    }
+  };
+}
+
 // ── THE THREE HANDLERS ──────────────────────────────────────────────────────────────────────────
 
 /** The audit action every publish attempt writes. Declared in core's registry (operational). */
@@ -449,6 +483,7 @@ export async function handleHomeClick(click: ParsedHomeClick, deps: SlackHomeDep
       itemText: located.text,
       title: located.action.confirm?.title ?? `${located.action.label}`,
       yes: located.action.confirm?.yes ?? "Save",
+      ...(located.action.confirm?.note !== undefined ? { note: located.action.confirm.note } : {}),
     }),
   });
   return res?.ok === true;

package/agent/channels/slack-side-panel.ts

@@ -0,0 +1,104 @@
+// THE SLACK SIDE PANEL (OPE-2457) — the person's own DM seat, opened beside whatever they are reading.
+//
+// Slack's agent experience (the `agent_view` manifest feature, docs.slack.dev/ai) shows the app's
+// Messages tab in a panel the person can open from anywhere in Slack. A message the person sends there
+// arrives as an ordinary `message.im`, so it wakes the SAME DM seat a DM wakes: no new seat type, no
+// new session, no new grant. What the panel adds is one fact — the room the person is looking at —
+// which Slack attaches to the `message.im` as `app_context` once the app subscribes to
+// `app_context_changed`.
+//
+// 🔴 THE VIEWED ROOM IS CONTEXT, NEVER ACCESS. The seat learns the room's id in a trusted host note
+// and nothing else: no history, no name, no member list. A read of that room still goes through the
+// rules that already apply to the DM, so opening the panel beside a channel gives the seat none of
+// that channel's reads. The note says so to the model in the same words.
+//
+// 🔴 THE STRICTEST DEFAULT FOR GUESTS AND EXTERNAL ROOMS. The id rides the note only when ALL hold:
+//   • the person is a full member of the workspace (the DM-partner probe answered `internal`);
+//   • the entity is a channel id of THIS workspace (its `team_id` equals the event's team);
+//   • Slack confirms the channel internal (`conversations.info`, the same TTL-cached, fail-closed
+//     verdict every wake route reads) — a Slack Connect channel, or one the app cannot see, fails it.
+// Anything else passes nothing, silently: the person still gets an answer, just without the room.
+
+/** Slack's entity type for a conversation id inside `app_context.entities`. */
+export const SLACK_CHANNEL_ENTITY_TYPE = "slack#/types/channel_id";
+
+/** A public (`C…`) or private (`G…`) channel id. A DM (`D…`) is not a room the panel adds. */
+const CHANNEL_ID = /^[CG][A-Z0-9]{2,}$/u;
+
+/** The room the person was viewing when they wrote, as Slack reported it. Unverified until
+ *  {@link sidePanelViewedRoom} checks it. */
+export interface SlackAppContextRoom {
+  readonly channelId: string;
+  /** The workspace the entity belongs to. */
+  readonly teamId?: string;
+}
+
+/**
+ * The most relevant CHANNEL entity of a `message.im`'s `app_context`, or undefined. Slack orders
+ * entities by relevance, so the first channel entity wins. Pure and tolerant: any other shape answers
+ * undefined, which is the no-context default.
+ */
+export function parseSlackAppContext(event: Readonly<Record<string, unknown>>): SlackAppContextRoom | undefined {
+  const ctx = event.app_context;
+  if (ctx === null || typeof ctx !== "object") return undefined;
+  const entities = (ctx as { entities?: unknown }).entities;
+  if (!Array.isArray(entities)) return undefined;
+  for (const raw of entities) {
+    if (raw === null || typeof raw !== "object") continue;
+    const e = raw as Record<string, unknown>;
+    if (e.type !== SLACK_CHANNEL_ENTITY_TYPE || typeof e.value !== "string" || !CHANNEL_ID.test(e.value)) continue;
+    return { channelId: e.value, ...(typeof e.team_id === "string" && e.team_id.length > 0 ? { teamId: e.team_id } : {}) };
+  }
+  return undefined;
+}
+
+/** What {@link sidePanelViewedRoom} needs from the wake. */
+export interface SidePanelGate {
+  readonly room: SlackAppContextRoom | undefined;
+  /** The DM's own workspace. */
+  readonly teamId: string | undefined;
+  /** The DM-partner probe's verdict on the person. Only `internal` admits a room. */
+  readonly partnerTrust: "internal" | "external" | undefined;
+  /** Slack's fail-closed internal verdict for one channel. */
+  readonly channelInternal: (channelId: string) => Promise<boolean>;
+}
+
+/** The viewed room's id, or undefined when any gate in the module header refuses it. Never throws. */
+export async function sidePanelViewedRoom(gate: SidePanelGate): Promise<string | undefined> {
+  const { room } = gate;
+  if (!room || gate.partnerTrust !== "internal") return undefined;
+  if (!gate.teamId || room.teamId !== gate.teamId) return undefined;
+  const internal = await gate.channelInternal(room.channelId).catch(() => false);
+  return internal ? room.channelId : undefined;
+}
+
+/**
+ * The trusted host note for a DM-seat wake: the viewed room, and the person's opt-out (OPE-2436), in
+ * FIXED words around host-checked ids — the only text the envelope's `<system-note>` may carry (see
+ * `WakeEnvelopeInput.systemNote`). Undefined when there is nothing to say.
+ */
+export function slackDmSystemNote(input: {
+  readonly viewedRoom?: string;
+  /** The person's opt-out answer. `readable: false` is the fail-closed guess, and gets its own line. */
+  readonly personOptOut?: { readonly optedOut: boolean; readonly readable: boolean };
+}): string | undefined {
+  const lines: string[] = [];
+  if (input.viewedRoom) {
+    lines.push(
+      `The person wrote this from the side panel while viewing the room ${input.viewedRoom} (Slack shows <#${input.viewedRoom}> as its link). ` +
+        "That is context only. It gives this conversation none of that room's access: a read of that room follows the rules that already apply here.",
+    );
+  }
+  if (input.personOptOut?.optedOut && input.personOptOut.readable) {
+    lines.push(
+      "This person has opted out of agent actions on their own content. Nothing from this conversation is saved to memory. " +
+        "Do not promise to remember anything. If they ask, tell them their opt-out is on.",
+    );
+  } else if (input.personOptOut?.optedOut) {
+    lines.push(
+      "The person's opt-out setting could not be read just now, so this turn may not be saved to memory. " +
+        "Do not promise to remember anything, and do not tell them their opt-out is on.",
+    );
+  }
+  return lines.length > 0 ? lines.join(" ") : undefined;
+}