@open-everywhere/provider-slack 0.4.0 → 0.6.0

package/agent/channels/slack-memory-canvas.ts

@@ -0,0 +1,382 @@
+// THE DOMAIN MEMORY CANVAS (OPE-2451) — a domain's channels show what the domain knows, as the
+// channel's own canvas (the tab Slack pins at the top of a channel), and the canvas is rewritten
+// whenever a silo the domain names changes.
+//
+// HOW IT STAYS CURRENT. Every durable silo write passes the one write road (core
+// memory/write-road.ts), which notifies the observers a surface registers. This module is Slack's
+// observer: for each domain whose `memory` list names the written silo, it re-reads the domain's
+// silos and rewrites the canvas of each of the domain's channels the app sits in.
+//
+// 🔴 THE TRUST GATE HOLDS FOR A CANVAS, AND IS NARROWER THAN THE ROOM GATE. A canvas is shown to
+// everyone in the channel, so it is written ONLY into a channel `conversations.info` confirms
+// internal (never a Slack Connect channel, never one whose facts could not be read) AND whose every
+// member `users.info` confirms a full workspace member (never a channel with a guest, a stranger, an
+// unresolvable member, or more members than one page lists). Both checks fail closed.
+//
+// 🔴 THE GATE ALSO TAKES A CANVAS DOWN. A canvas written while the channel passed would outlive the
+// room's trust: share the channel, or add a guest, and the old canvas stays on screen. So a refresh
+// that fails the gate REPLACES the app's own canvas with a notice that holds no memory, and the two
+// trust events re-run the gate at once (a person joins — `member_joined_channel`; the channel is
+// shared — `channel_shared`, slack-front.ts). The room verdict is read FRESH for every canvas
+// decision, never from the wake path's cache, which would say "internal" for up to its TTL after a
+// share. A channel whose domain stops showing a canvas gets the same take-down. Every lookup the
+// take-down needs fails CLOSED to `clear-failed`. What the gate cannot do is notice a change no event
+// reports, until the next memory write or trust event re-runs it (docs/capabilities/memory.md lists
+// every limit).
+//
+// 🔴 A CANVAS THE APP DID NOT CREATE IS NEVER TOUCHED. A channel has at most one channel canvas, and
+// people write their own. When the channel already has one, the app rewrites it only when
+// `files.info` names the app's own bot user as its creator. A person's canvas stays theirs, and the
+// refusal is logged and audited so an operator can see why a channel shows no memory.
+//
+// 🔴 WHAT A CANVAS DOES NOT DO. It is a READ view. Members correct or forget a line by asking the
+// agent in the channel, which goes through the tools and the approval card like any other change.
+// An edit made directly in the canvas is overwritten on the next memory write — the canvas says so.
+
+import {
+  agentDisplayName,
+  appendAudit,
+  domainForChannel,
+  domainsNamingSilo,
+  getConfig,
+  readDomainMemory,
+  renderMemoryMarkdown,
+  type Domain,
+  type MemoryWriteEvent,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { confirmChannelInternalFresh, slackAuthorIsMember, slackForm } from "./slack-events.js";
+import { encodeSlackForm } from "./slack-web-api.js";
+
+/** The audit action every refresh attempt writes, one row per channel. Declared in core's registry. */
+const MEMORY_CANVAS_ACTION = "memory.canvas_refresh";
+
+/** The most channels one refresh rewrites. A domain wider than this is refreshed in its first N. */
+const MEMORY_CANVAS_CHANNELS_MAX = 20;
+/** How many pages of the bot's channel list a refresh walks (200 per page). */
+const BOT_CHANNEL_PAGES_MAX = 5;
+/** Slack caps a canvas document; the rendered memory stops well below it and says so. */
+const CANVAS_MARKDOWN_MAX = 90_000;
+
+export type CanvasOutcome =
+  | "created"
+  | "updated"
+  | "unchanged"
+  | "skipped-external"
+  | "skipped-guest"
+  | "skipped-foreign"
+  | "skipped-disabled"
+  | "cleared-external"
+  | "cleared-guest"
+  | "cleared-disabled"
+  | "clear-failed"
+  | "failed";
+
+/** The most members a canvas channel may have and still be checked person by person (one page of
+ *  `conversations.members`). A larger channel is refused rather than half-checked. */
+const MEMBER_CHECK_MAX = 200;
+
+export interface MemoryCanvasDeps {
+  /** One Slack Web API call; undefined on any failure. */
+  readonly call: (method: string, body: Record<string, unknown>) => Promise<Record<string, unknown> | undefined>;
+  /** Is this channel confirmed internal? false on any doubt. 🔴 The live dep reads it FRESH (it drops
+   *  the cached verdict first): a cached `internal` from before a share must never clear the gate. */
+  readonly channelInternal: (channelId: string) => Promise<boolean>;
+  /** Is this person a full member of the workspace? undefined when the lookup failed. The shared
+   *  `users.info` probe (slack-events.ts `slackAuthorIsMember`). */
+  readonly authorIsMember: (userId: string, teamId: string | undefined) => Promise<boolean | undefined>;
+  readonly now?: () => Date;
+}
+
+/** The live deps: every call through `slackForm` (the one Web API seam, fail-soft), the room verdict
+ *  read FRESH, and the shared per-person membership probe. */
+export function liveMemoryCanvasDeps(): MemoryCanvasDeps {
+  return {
+    call: (method, body) => slackForm(method, encodeSlackForm(body)),
+    channelInternal: confirmChannelInternalFresh,
+    authorIsMember: slackAuthorIsMember,
+  };
+}
+
+/**
+ * Make memory text safe for a canvas a whole channel reads. A remembered line is member-authored
+ * text, and canvas markdown turns `![](@U…)` into a mention and `<!channel>`-shaped text into a ping
+ * on some clients. A memory view must never notify anyone, so both forms are defused. PURE.
+ */
+export function defuseCanvasText(markdown: string): string {
+  return markdown.replace(/!\[/g, "!\\[").replace(/<([@!#])/g, "‹$1");
+}
+
+/** The canvas document for one domain. PURE apart from the read the caller already did. */
+function memoryCanvasMarkdown(domain: Domain, groups: Parameters<typeof renderMemoryMarkdown>[1], nowIso: string): string {
+  const name = agentDisplayName();
+  const body = renderMemoryMarkdown(`What ${name} knows — ${domain.title ?? domain.name}`, groups, nowIso);
+  const footer =
+    `\n---\n${name} keeps this canvas up to date from this domain's memory. ` +
+    `To correct or forget a line, ask ${name} in this channel. A direct edit to this canvas is replaced on the next memory change.\n`;
+  const text = defuseCanvasText(body);
+  const cut = text.length > CANVAS_MARKDOWN_MAX ? text.slice(0, CANVAS_MARKDOWN_MAX) + "\n\n_This canvas is full. Ask in this channel for the rest._\n" : text;
+  return cut + footer;
+}
+
+/** The channels the app is in that a domain owns, as `{ channelId, surfaceKey }`, capped. */
+async function domainChannels(teamId: string, domains: readonly Domain[], deps: MemoryCanvasDeps): Promise<Map<string, { channelId: string; surfaceKey: string }[]>> {
+  const out = new Map<string, { channelId: string; surfaceKey: string }[]>();
+  const all = getConfig().loadDomains();
+  const wanted = new Set(domains.map((d) => d.name));
+  let cursor: string | undefined;
+  let total = 0;
+  for (let page = 0; page < BOT_CHANNEL_PAGES_MAX && total < MEMORY_CANVAS_CHANNELS_MAX; page++) {
+    const res = await deps.call("users.conversations", {
+      types: "public_channel,private_channel",
+      exclude_archived: true,
+      limit: 200,
+      ...(cursor ? { cursor } : {}),
+    });
+    if (res?.ok !== true || !Array.isArray(res.channels)) break;
+    for (const c of res.channels) {
+      const channelId = typeof (c as { id?: unknown })?.id === "string" ? (c as { id: string }).id : undefined;
+      if (!channelId) continue;
+      const surfaceKey = `slack/${teamId}/${channelId}`;
+      const owner = domainForChannel(surfaceKey, all);
+      if (!owner || !wanted.has(owner.name)) continue;
+      if (total >= MEMORY_CANVAS_CHANNELS_MAX) break;
+      out.set(owner.name, [...(out.get(owner.name) ?? []), { channelId, surfaceKey }]);
+      total++;
+    }
+    cursor = typeof (res.response_metadata as { next_cursor?: unknown })?.next_cursor === "string" ? (res.response_metadata as { next_cursor: string }).next_cursor : undefined;
+    if (!cursor) break;
+  }
+  return out;
+}
+
+/**
+ * Does every member of the channel resolve as a full workspace member? FAIL-CLOSED: a failed list, a
+ * channel larger than one page, or any member the probe cannot confirm answers false.
+ *
+ * 🔴 WHY THE ROOM GATE IS NOT ENOUGH HERE. `conversations.info` answers whether a channel is SHARED.
+ * It says nothing about who sits in it, and Slack lets a multi-channel or single-channel guest join an
+ * ordinary private channel (see slack-events.ts, the per-author membership probe, OPE-466). A wake in
+ * such a channel still reads the domain's memory — that is the room gate as it stands — but a canvas
+ * puts every line in front of every member at once, unasked. So the canvas asks the per-person
+ * question the room gate does not.
+ */
+async function everyMemberIsFull(channelId: string, teamId: string | undefined, botUserId: string | undefined, deps: MemoryCanvasDeps): Promise<boolean> {
+  const res = await deps.call("conversations.members", { channel: channelId, limit: MEMBER_CHECK_MAX });
+  if (res?.ok !== true || !Array.isArray(res.members)) return false;
+  const next = (res.response_metadata as { next_cursor?: unknown } | undefined)?.next_cursor;
+  if (typeof next === "string" && next.length > 0) return false;
+  for (const m of res.members) {
+    if (typeof m !== "string" || m.length === 0) return false;
+    if (m === botUserId) continue;
+    if ((await deps.authorIsMember(m, teamId)) !== true) return false;
+  }
+  return true;
+}
+
+/**
+ * The document that REPLACES the app's own canvas when its channel stops passing the gate. It holds no
+ * memory at all, by construction: it is built from the agent's name alone.
+ */
+function withdrawnCanvasMarkdown(): string {
+  const name = agentDisplayName();
+  return (
+    `# ${name}'s memory canvas was withdrawn\n\n` +
+    `This channel is shared outside the workspace, or one of its members is not a full member, so ${name} no longer shows a domain's memory here. ` +
+    `The memory itself is unchanged. Members can still ask ${name} about it where the domain's memory is readable.\n`
+  );
+}
+
+/** Why a canvas decision withdrew (or must withdraw) the app's canvas. `disabled`: the channel no
+ *  longer belongs to a domain that shows one (`memoryCanvas: false`, no `memory`, or no domain). */
+type WithdrawReason = "external" | "guest" | "disabled";
+
+/**
+ * Take the app's OWN canvas down in one channel, if it has one. FAIL-CLOSED ON EVERY LOOKUP: a failed
+ * `conversations.info`, a failed `files.info`, or an unknown bot identity answers `clear-failed`, never
+ * a skip — the caller cannot rule out that the app's canvas is still on screen, and the audit row must
+ * say so. `skipped-*` is kept for the two answers that PROVE nothing of ours is there: no channel
+ * canvas at all, or a canvas whose creator is somebody else.
+ */
+async function withdrawIfOurs(channelId: string, reason: WithdrawReason, botUserId: string | undefined, deps: MemoryCanvasDeps): Promise<CanvasOutcome> {
+  const info = await deps.call("conversations.info", { channel: channelId });
+  if (info?.ok !== true) return "clear-failed";
+  const existing = canvasIdOf(info);
+  if (!existing) return `skipped-${reason}`;
+  const file = await deps.call("files.info", { file: existing });
+  if (file?.ok !== true) return "clear-failed";
+  const creator = (file.file as { user?: unknown } | undefined)?.user;
+  if (botUserId === undefined) return "clear-failed";
+  if (creator !== botUserId) return `skipped-${reason}`;
+  const cleared = await deps.call("canvases.edit", {
+    canvas_id: existing,
+    changes: [{ operation: "replace", document_content: { type: "markdown", markdown: withdrawnCanvasMarkdown() } }],
+  });
+  return cleared?.ok === true ? `cleared-${reason}` : "clear-failed";
+}
+
+function canvasIdOf(info: Record<string, unknown>): string | undefined {
+  const props = (info.channel as { properties?: { canvas?: { file_id?: unknown } } } | undefined)?.properties;
+  return typeof props?.canvas?.file_id === "string" ? props.canvas.file_id : undefined;
+}
+
+/**
+ * Write one channel's canvas — or, with `markdown: null`, only RECHECK it. Never throws.
+ *
+ * 🔴 THE GATE RUNS BEFORE EVERY DECISION, AND A FAILED GATE TAKES THE APP'S OWN CANVAS DOWN (OPE-2451,
+ * the brain's security review). A canvas the app wrote while the channel passed outlives the room's
+ * trust otherwise: once the channel is shared, or a guest joins, a refresh that merely SKIPS leaves
+ * every line of the domain's memory on screen for the new audience. So on either refusal the app
+ * replaces its own canvas with {@link withdrawnCanvasMarkdown} ({@link withdrawIfOurs}). A canvas a
+ * PERSON made is never touched, in either direction.
+ *
+ * `null` markdown is the recheck the trust EVENTS run: it takes the canvas down on a failed gate and
+ * writes nothing on a passing one (`unchanged`). `joinedUserId` is the person a join event named: they
+ * are probed DIRECTLY, because Slack's member list may not carry them yet when the event arrives.
+ */
+export async function publishChannelCanvas(
+  channelId: string,
+  markdown: string | null,
+  botUserId: string | undefined,
+  deps: MemoryCanvasDeps,
+  teamId?: string,
+  joinedUserId?: string,
+): Promise<CanvasOutcome> {
+  const blocked: "external" | "guest" | undefined = !(await deps.channelInternal(channelId))
+    ? "external"
+    : (joinedUserId !== undefined && joinedUserId !== botUserId && (await deps.authorIsMember(joinedUserId, teamId)) !== true) ||
+        !(await everyMemberIsFull(channelId, teamId, botUserId, deps))
+      ? "guest"
+      : undefined;
+  if (blocked) return withdrawIfOurs(channelId, blocked, botUserId, deps);
+  if (markdown === null) return "unchanged";
+  const info = await deps.call("conversations.info", { channel: channelId });
+  if (info?.ok !== true) return "failed";
+  const existing = canvasIdOf(info);
+  if (!existing) {
+    const created = await deps.call("conversations.canvases.create", { channel_id: channelId, document_content: { type: "markdown", markdown } });
+    return created?.ok === true ? "created" : "failed";
+  }
+  // Ownership before any write: only a canvas the app's own bot user created is the app's to replace.
+  const file = await deps.call("files.info", { file: existing });
+  const creator = file?.ok === true ? (file.file as { user?: unknown } | undefined)?.user : undefined;
+  if (botUserId === undefined || creator !== botUserId) return "skipped-foreign";
+  const edited = await deps.call("canvases.edit", { canvas_id: existing, changes: [{ operation: "replace", document_content: { type: "markdown", markdown } }] });
+  return edited?.ok === true ? "updated" : "failed";
+}
+
+/** What woke a canvas decision: a memory write, or one of the two trust events. */
+export type CanvasTrigger = "memory-write" | "member-joined" | "channel-shared";
+
+/**
+ * Recheck ONE channel's canvas after a trust event (a person joined it, or it was shared). The front
+ * route schedules it, and it writes one `memory.canvas_refresh` row.
+ *
+ * 🔴 IT RUNS IN EVERY CHANNEL, NOT ONLY A CANVAS-SHOWING DOMAIN'S. A channel whose domain no longer
+ * shows a canvas — `memoryCanvas: false`, no `memory`, or a channel moved out of every domain — may
+ * still hold the canvas the app wrote while it did. Skipping it would leave that canvas up with no gate
+ * ever running on it again, so such a channel gets the clear-only path (`cleared-disabled` when the
+ * app's canvas was there). The cost is two Slack reads per person joining a channel with no canvas.
+ */
+export async function recheckChannelCanvas(
+  input: {
+    readonly org: string;
+    readonly teamId: string;
+    readonly channelId: string;
+    readonly trigger: Exclude<CanvasTrigger, "memory-write">;
+    readonly joinedUserId?: string;
+  },
+  deps: MemoryCanvasDeps,
+): Promise<CanvasOutcome> {
+  const surfaceKey = `slack/${input.teamId}/${input.channelId}`;
+  const domain = domainForChannel(surfaceKey, getConfig().loadDomains());
+  const shows = domain !== undefined && domain.memory !== undefined && domain.memoryCanvas !== false;
+  const auth = await deps.call("auth.test", {});
+  const botUserId = auth?.ok === true && typeof auth.user_id === "string" ? auth.user_id : undefined;
+  const outcome = await (shows
+    ? publishChannelCanvas(input.channelId, null, botUserId, deps, input.teamId, input.joinedUserId)
+    : withdrawIfOurs(input.channelId, "disabled", botUserId, deps)
+  ).catch((): CanvasOutcome => "clear-failed");
+  if (outcome !== "unchanged" && outcome !== "skipped-disabled") {
+    console.log(`[open-everywhere:slack-canvas] ${input.trigger} recheck, channel ${input.channelId}: ${outcome}`);
+  }
+  await appendAudit({
+    org: input.org,
+    platform: "slack",
+    workspace: input.teamId,
+    surface: input.channelId,
+    action: MEMORY_CANVAS_ACTION,
+    detail: { domain: domain?.name ?? null, trigger: input.trigger, outcome },
+  }).catch(() => undefined);
+  return outcome;
+}
+
+/**
+ * Refresh every canvas a write to `event.silo` made stale. The observer the provider registers.
+ * A domain with `memoryCanvas: false` gets no new canvas, and the app takes its own old canvas down.
+ * When no domain names the silo — the common case — the refresh costs no Slack call at all.
+ */
+export async function refreshMemoryCanvases(event: MemoryWriteEvent, deps: MemoryCanvasDeps): Promise<void> {
+  // Every domain naming the silo, the ones that turned their canvas OFF included: a write to such a
+  // domain's silo is the moment its old canvas would otherwise go stale with the new lines still
+  // missing — and stay up ungated. Those get the clear-only path below.
+  const domains = domainsNamingSilo(event.silo, getConfig().loadDomains());
+  if (domains.length === 0) return;
+  const auth = await deps.call("auth.test", {});
+  const teamId = auth?.ok === true && typeof auth.team_id === "string" ? auth.team_id : undefined;
+  const botUserId = auth?.ok === true && typeof auth.user_id === "string" ? auth.user_id : undefined;
+  if (!teamId) return;
+  const channels = await domainChannels(teamId, domains, deps);
+  if (channels.size === 0) return;
+  const nowIso = (deps.now?.() ?? new Date()).toISOString();
+  for (const domain of domains) {
+    const rooms = channels.get(domain.name);
+    if (!rooms || rooms.length === 0) continue;
+    const shows = domain.memoryCanvas !== false;
+    const markdown = shows ? memoryCanvasMarkdown(domain, await readDomainMemory(event.org, domain), nowIso) : "";
+    for (const room of rooms) {
+      // A throw on the clear-only path cannot rule out that the old canvas is still up, so it says so.
+      const outcome = await (shows ? publishChannelCanvas(room.channelId, markdown, botUserId, deps, teamId) : withdrawIfOurs(room.channelId, "disabled", botUserId, deps)).catch(
+        (): CanvasOutcome => (shows ? "failed" : "clear-failed"),
+      );
+      if (outcome !== "created" && outcome !== "updated") {
+        console.log(`[open-everywhere:slack-canvas] domain "${domain.name}" channel ${room.channelId}: ${outcome}`);
+      }
+      const [platform, workspace, surface] = room.surfaceKey.split("/");
+      await appendAudit({
+        org: event.org,
+        platform: platform!,
+        workspace: workspace!,
+        surface: surface!,
+        action: MEMORY_CANVAS_ACTION,
+        detail: { domain: domain.name, trigger: "memory-write", silo: event.silo, outcome, chars: markdown.length },
+      }).catch(() => undefined);
+    }
+  }
+}
+
+// One refresh per domain set at a time. A burst of writes (a session persisting three silos) runs
+// the refresh once more after the current one, never once per write.
+const running = new Map<string, { again: boolean; done: Promise<void> }>();
+
+/** Coalesce refreshes for one org and silo: a call during a run schedules exactly one more run. */
+export function coalescedRefresh(event: MemoryWriteEvent, deps: MemoryCanvasDeps): Promise<void> {
+  const key = `${event.org}\u0000${event.silo}`;
+  const current = running.get(key);
+  if (current) {
+    current.again = true;
+    return current.done;
+  }
+  const state: { again: boolean; done: Promise<void> } = { again: false, done: Promise.resolve() };
+  state.done = (async () => {
+    try {
+      do {
+        state.again = false;
+        await refreshMemoryCanvases(event, deps);
+      } while (state.again);
+    } finally {
+      running.delete(key);
+    }
+  })();
+  running.set(key, state);
+  return state.done;
+}

package/agent/channels/slack-offboarding.ts

@@ -0,0 +1,89 @@
+// SLACK'S HALF OF AUTOMATIC OFFBOARDING (OPE-2423) — a `user_change` event whose user is `deleted`
+// is a deactivation report, and this module hands it to core's gates and lever
+// (identity/offboarding.ts `offboardDeactivatedAccount`).
+//
+// WHAT THIS MODULE OWNS, AND WHAT IT DOES NOT. It owns reading the Slack envelope and the Slack
+// re-read. Every DECISION — the same-workspace gate, the tenant fence, the terminal revoke and its
+// audit row — is core's, so a second surface that reports deactivations gets the same gates.
+//
+// THE THREE SLACK FACTS, AND WHERE EACH COMES FROM:
+//   • the DELIVERING workspace — the envelope's `team_id`, which the front route has already
+//     authenticated with the signing-secret HMAC. Never the event body's `user.team_id`.
+//   • the ACCOUNT's workspace — the event body's `user.team_id`. A Slack-Connect partner's user
+//     arrives with the partner's workspace here, and core refuses it (gate 1).
+//   • the CONFIRMATION — a fresh `users.info` under this deployment's own bot token. The account
+//     must come back `deleted: true` AND in the delivering workspace. The event body's own `deleted`
+//     flag only decides whether to ASK; it is never the evidence.
+
+import { deploymentOrg, offboardDeactivatedAccount, type DeactivationConfirmation, type OffboardOutcome } from "@open-everywhere/core/agent/adapter-api.js";
+import type { SlackEventEnvelope } from "./slack-events.js";
+
+/** The facts one `user_change` envelope names. */
+export interface SlackUserDeactivation {
+  /** The envelope's `team_id` — the workspace that delivered the event. */
+  readonly deliveringTeamId: string;
+  readonly enterpriseId?: string;
+  readonly userId: string;
+  /** The account's own workspace (`user.team_id`), as the event body names it. */
+  readonly userTeamId: string;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+}
+
+/**
+ * PURE: the deactivation a `user_change` envelope reports, or undefined when it reports none. Only a
+ * `user` with `deleted: true` is a deactivation; every other profile edit (a new title, a status
+ * emoji) is undefined, and the front route acks it with no further work.
+ */
+export function parseSlackUserDeactivation(env: SlackEventEnvelope): SlackUserDeactivation | undefined {
+  const event = env.event;
+  if (!event || event.type !== "user_change") return undefined;
+  const user = event["user"] as Record<string, unknown> | undefined;
+  if (!user || user["deleted"] !== true) return undefined;
+  const userId = str(user["id"]);
+  const deliveringTeamId = str(env.team_id);
+  if (!userId || !deliveringTeamId) return undefined;
+  const enterpriseId = str(env.enterprise_id);
+  return { deliveringTeamId, userId, userTeamId: str(user["team_id"]) ?? "", ...(enterpriseId ? { enterpriseId } : {}) };
+}
+
+/** The `users.info` call, as the bundle's Web API seam answers it. */
+export type SlackUsersInfo = (userId: string) => Promise<Record<string, unknown> | undefined>;
+
+/**
+ * Gate 3, the Slack way: re-read the account under this deployment's own token. Confirmed only when
+ * Slack says the account is `deleted` AND in `teamId`. Every other answer is a refusal with a
+ * token-free reason, and `missing_scope` names the scope to grant.
+ */
+export async function confirmSlackDeactivation(userId: string, teamId: string, usersInfo: SlackUsersInfo): Promise<DeactivationConfirmation> {
+  const info = await usersInfo(userId);
+  if (info?.["ok"] !== true) {
+    const error = str(info?.["error"]) ?? "no response";
+    return {
+      deactivated: false,
+      reason: `Slack users.info refused (${error})${error === "missing_scope" ? " — grant the app the users:read bot scope" : ""}`,
+    };
+  }
+  const user = info["user"] as Record<string, unknown> | undefined;
+  if (user?.["deleted"] !== true) return { deactivated: false, reason: "Slack users.info says the account is active (a reactivation, or a report that was never true)" };
+  if (str(user["team_id"]) !== teamId) {
+    return { deactivated: false, reason: `Slack users.info places the account in workspace "${str(user["team_id"]) ?? "(none)"}", not "${teamId}"` };
+  }
+  return { deactivated: true };
+}
+
+/** Hand one deactivation to core. Never throws (core's own contract). */
+export async function routeSlackUserDeactivation(d: SlackUserDeactivation, deps: { readonly usersInfo: SlackUsersInfo; readonly org?: string }): Promise<OffboardOutcome> {
+  return await offboardDeactivatedAccount({
+    org: deps.org ?? deploymentOrg(),
+    platform: "slack",
+    deliveringTenant: d.deliveringTeamId,
+    ...(d.enterpriseId ? { deliveringEnterprise: d.enterpriseId } : {}),
+    tenant: d.userTeamId,
+    nativeId: d.userId,
+    source: "slack:user_change",
+    confirm: () => confirmSlackDeactivation(d.userId, d.deliveringTeamId, deps.usersInfo),
+  });
+}

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

@@ -55,6 +55,14 @@ export const slackWakeOriginCodec: WakeOriginCodec<SlackOrigin> = {
   // unequal on an axis that cannot differ. EMPTINESS IS ABSENCE, the third of the three reads this
   // file takes that way.
   placementRef: (origin) => (typeof origin.replyAnchorTs === "string" && origin.replyAnchorTs.length > 0 ? origin.replyAnchorTs : undefined),
+  // THE THREAD'S ROOT (OPE-2430): the parent message's ts. A threaded origin names it in `threadTs`;
+  // a top-level trigger that a seat was spawned for names it in `replyAnchorTs`, because the seat's
+  // thread hangs under that very message. A DM-family or routine origin names neither, so no done
+  // mark is placed there.
+  threadRootMessage: (origin) => {
+    const ts = typeof origin.threadTs === "string" && origin.threadTs.length > 0 ? origin.threadTs : typeof origin.replyAnchorTs === "string" && origin.replyAnchorTs.length > 0 ? origin.replyAnchorTs : undefined;
+    return ts === undefined ? undefined : { channelId: origin.channelId, messageId: ts };
+  },
   // A `dmOrigin` arm lived here (OPE-306) to mint a DM delegation anchor's reply origin from the
   // binding. OPE-368 deleted the anchor and the interface member with it — a Slack 1:1 or group DM
   // now diverts into its own first-class window (OPE-351 stages 2 + 4), so its origin is minted and

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;
+}