@open-everywhere/provider-slack 0.6.0 → 0.8.0

package/agent/access/slack-attachment-fetch.ts

@@ -42,6 +42,7 @@ import {
   type EgressRefusalCause,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import { slackBotToken } from "../setup/credentials.js";
+import type { AuditDetail } from "@open-everywhere/core/agent/adapter-api.js";
 
 // THE CREDENTIAL'S IDENTITY, FOR THE AUDIT ROW (OPE-1547) — the ref NAME, never the value. This is
 // the one host-side seam that attaches a credential, so before this ticket it was the one place
@@ -140,7 +141,7 @@ export async function fetchSlackAttachment(ctx: BindableContext, ref: TrustedSla
   // referenced here; the row carries the ref name only, which is the identity an operator looks up.
   // `route` is the dispatch route — it was called `via` until OPE-1547, the same field name the
   // SANDBOX plane used for the stamping connection.
-  const row = (outcome: "allowed" | "failed", extra: Record<string, unknown> = {}): Record<string, unknown> => ({
+  const row = (outcome: "allowed" | "failed", extra: AuditDetail = {}): AuditDetail => ({
     ...hostCallAuditFields({
       host: safe.url.hostname,
       verb: ATTACHMENT_VERB,

package/agent/app-manifest.ts

@@ -150,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> | optout [on | off] | help",
+            usage_hint: "stop | status | budget [raise <usd> | clear] | rate <n> | optout [on | off] | watch [more | less | none] | cover [on | off] | suggest [on | off] | help",
             should_escape: false,
           },
         ],
@@ -243,6 +243,17 @@ 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",
+            // canvases.sections.lookup — find a memory canvas made before the `memory_canvas` row
+            // existed, by the marker line it carries (OPE-2587, core channels/slack-canvas-list.ts
+            // `memoryCanvasAmong`). Without it such a canvas held only as a channel tab is not found:
+            // its refresh and take-down record `failed` and `clear-failed`, and nothing is overwritten.
+            "canvases:read",
+            // slackLists.items.list / .create / .update — the agent's own List writes (OPE-2521,
+            // core tools/update_list.ts): it reads a List's rows to match one by name, then adds or
+            // changes rows on a person's approval. `canvases:write` above also covers the agent's own
+            // canvas writes (canvases.create, canvases.edit; core tools/write_canvas.ts).
+            "lists:read",
+            "lists: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",
@@ -271,6 +282,8 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
           //   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)
+          //   agent_session_stopped → chat:write (Slack's native Stop button on an agent session,
+          //     OPE-2519; Slack shows the button only to an app subscribed to it)
           // scripts/slack-app-manifest-test.ts derives the handled set from the code and fails if
           // this list drops one (OPE-2223).
           bot_events: [
@@ -286,6 +299,7 @@ export function slackAppManifestTemplate(opts: SlackAppManifestOptions = {}): st
             "channel_shared",
             "user_change",
             "app_context_changed",
+            "agent_session_stopped",
           ],
         },
         // The INTERACTIVITY Request URL — the SAME public route Event Subscriptions uses. Every

package/agent/channels/slack-agent-session.ts

@@ -0,0 +1,249 @@
+// THE SLACK AGENT SESSION (OPE-2519) — Slack's native Stop, the session title, and the "needs you" state.
+//
+// Slack's agent experience shows each conversation with the app as an AGENT SESSION, keyed by the
+// channel and the thread root (docs.slack.dev/ai/agent-sessions, re-read 2026-10-14). A session has a
+// lifecycle status (`processing`, `active`, `suspended`, `closed`) and a title. This file owns the three
+// things OE does with it:
+//
+//   • STOP. While a session is `processing`, Slack shows a Stop button, but only to an app that
+//     subscribes to `agent_session_stopped`. A press arrives as that event. It takes the SAME cancel
+//     path as the ✋ reaction and `/oe stop` (`cancelAnchoredTurn`): no session is minted, no model is
+//     called, nothing is spent. Slack does not move the status itself, so the route sets `active`.
+//   • TITLE. A top-level message the person sends in their DM with the app opens a new conversation,
+//     and gets a short title from the words the person TYPED (`authoredText`). The lines of a
+//     forwarded or quoted message are another conversation's words, so they never title it. The host
+//     derives the title in code: no model writes it. Slack applies a `title` only when the call
+//     CREATES the session, so a title the person typed over ours is never overwritten. A thread reply,
+//     a shortcut and a group DM get no title.
+//   • STATE. Core's turn-anchor hook sets the session `processing` when a turn starts, and at the park
+//     `suspended` when the turn reported through `update_status` that it waits on a person
+//     (`needs_input` or `blocked`), else `active` (channels/surface-session-state.ts). This file
+//     registers the Slack setter: it names the session from the delivery's auth attributes. The
+//     person's next message sets `processing`, then parks `active` unless it reports again that it
+//     waits on the person. A job's result wake names no session, so its turn sets no state.
+//   • A FORWARDED JOB's WAIT (OPE-2536). A job the DM seat forwards to the work session can end waiting
+//     on the person: it asked a question in the room (`ask_room`), or it needs their own sign-in. The
+//     work session has no `update_status`, so the host sets the session `suspended` at the job's
+//     settlement (core channels/work-surface-wait.ts). This file registers the PIN for that: the
+//     session's id and the three attributes that name it again, kept on the job.
+//
+// WHICH SESSIONS. Only the person's 1:1 DM with the app (the Messages tab and the side panel), where
+// Slack lists the person's agent sessions. The DM door stamps the session's thread root on the wake's
+// auth (`agent_session_ts`): a top-level message opens its own session, keyed by its own `ts`, and a
+// thread reply belongs to its thread's session. A channel thread gets no state from OE.
+//
+// Every call here is best-effort. A workspace without Slack's agent features answers an error, which
+// is logged and changes nothing else.
+
+import {
+  cancelAnchoredTurn,
+  resolvePartition,
+  turnAnchorKey,
+  turnChannelKey,
+  type AttachSessionForCancel,
+  type CancelResult,
+  type SurfaceSessionPinner,
+  type SurfaceSessionSetter,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { bindableForSlackIds, slackForm, type SlackEventEnvelope } from "./slack-events.js";
+
+/** Slack's event for a press of the session's Stop button. */
+export const AGENT_SESSION_STOPPED_EVENT = "agent_session_stopped";
+
+/** The longest title OE sets. Slack accepts 200 characters; a session list shows far fewer. */
+export const SLACK_SESSION_TITLE_MAX = 60;
+
+/** The session states OE sets. */
+export type SlackSessionStatus = "processing" | "active" | "suspended";
+
+/** The auth attribute the DM door stamps with the session's thread root (slack-front.ts `scheduleDmWake`). */
+const AGENT_SESSION_TS_ATTRIBUTE = "agent_session_ts";
+
+/** The form-call seam: `slackForm` in production, a recorder in the tests. */
+export type SlackFormCall = (method: string, body: string) => Promise<Record<string, unknown> | undefined>;
+
+// --- the title ------------------------------------------------------------------------------------
+
+/** Slack's three escaped characters, decoded. */
+function decodeSlackEntities(text: string): string {
+  return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+/**
+ * The session title for a conversation that opens with `text`, or undefined when nothing readable is
+ * left. Pure. It keeps the first non-empty line, renders a link as its label, a channel as `#name`, and
+ * drops a member or group mention (no raw id reaches the title). It strips `*`, `~` and backticks, and
+ * keeps `_`, so an identifier such as `oe_config` stays intact. A long line is cut at a word and ends
+ * with `…`.
+ */
+export function slackSessionTitle(text: string | undefined): string | undefined {
+  if (typeof text !== "string") return undefined;
+  const rendered = text
+    // A member mention, with or without a label: dropped.
+    .replace(/<@[A-Z0-9]+(?:\|[^>]*)?>/g, " ")
+    // A channel mention: its name when Slack sent one, else dropped.
+    .replace(/<#[A-Z0-9]+\|([^>]+)>/g, "#$1")
+    .replace(/<#[A-Z0-9]+>/g, " ")
+    // A special or group mention (`<!here>`, `<!subteam^S1|@team>`): dropped.
+    .replace(/<![^>]*>/g, " ")
+    // A link: its label, else the address.
+    .replace(/<[^>|]+\|([^>]+)>/g, "$1")
+    .replace(/<([^>]+)>/g, "$1");
+  const line = decodeSlackEntities(rendered)
+    .split(/\r?\n/)
+    .map((l) => l.replace(/[*~`]+/g, "").replace(/\s+/g, " ").trim())
+    .find((l) => l.length > 0);
+  if (line === undefined) return undefined;
+  if (line.length <= SLACK_SESSION_TITLE_MAX) return line;
+  const head = line.slice(0, SLACK_SESSION_TITLE_MAX - 1);
+  const cut = head.lastIndexOf(" ");
+  return `${(cut >= SLACK_SESSION_TITLE_MAX / 2 ? head.slice(0, cut) : head).trimEnd()}…`;
+}
+
+// --- the status call -------------------------------------------------------------------------------
+
+/** One `agents.sessions.setStatus` call. */
+export interface SlackSessionStatusCall {
+  readonly channelId: string;
+  /** The session's thread root. */
+  readonly threadTs: string;
+  readonly status: SlackSessionStatus;
+  /** Applied only when this call creates the session. */
+  readonly title?: string;
+}
+
+/** The form body of {@link SlackSessionStatusCall}. Pure. */
+export function slackSessionStatusForm(call: SlackSessionStatusCall): string {
+  const body = new URLSearchParams({ channel_id: call.channelId, thread_ts: call.threadTs, status: call.status });
+  if (call.title !== undefined && call.title.length > 0) body.set("title", call.title);
+  return body.toString();
+}
+
+/** Set a session's status (and, on creation, its title). True when Slack answered `ok`. Never throws. */
+export async function setSlackSessionStatus(call: SlackSessionStatusCall, form: SlackFormCall = slackForm): Promise<boolean> {
+  try {
+    const res = await form("agents.sessions.setStatus", slackSessionStatusForm(call));
+    if (res?.ok === true) return true;
+    console.warn(`[open-everywhere:slack-session] agents.sessions.setStatus ${call.status} was not applied (${call.channelId}/${call.threadTs}): ${String(res?.error ?? "no answer")}`);
+    return false;
+  } catch (err) {
+    console.warn(`[open-everywhere:slack-session] agents.sessions.setStatus ${call.status} failed (${call.channelId}/${call.threadTs}): ${String(err)}`);
+    return false;
+  }
+}
+
+/**
+ * The session a delivery's auth attributes name, or undefined for none. Only a delivery the DM door
+ * stamped (`agent_session_ts`) names one: a shortcut, a group DM and every channel carry no stamp, so
+ * they never set a session's state, even on a threaded message. Pure.
+ */
+export function slackAgentSessionOf(attributes: Readonly<Record<string, unknown>>): { readonly channelId: string; readonly threadTs: string } | undefined {
+  if (attributes.channel_type !== "im") return undefined;
+  const channelId = attributes.channel_id;
+  const stamped = attributes[AGENT_SESSION_TS_ATTRIBUTE];
+  if (typeof channelId !== "string" || channelId.length === 0 || typeof stamped !== "string" || stamped.length === 0) return undefined;
+  return { channelId, threadTs: stamped };
+}
+
+/**
+ * The Slack pinner (OPE-2536): the session a delivery names, as the setter's own id and the three
+ * attributes that name it again. A forwarded job keeps this, so its settlement can set the session
+ * `suspended` long after the delivery's auth is gone. Ids only, never text. Pure.
+ */
+export const slackSurfaceSessionPin: SurfaceSessionPinner = (attributes) => {
+  const session = slackAgentSessionOf(attributes);
+  if (!session) return undefined;
+  return {
+    id: `${session.channelId}:${session.threadTs}`,
+    attributes: { channel_id: session.channelId, channel_type: "im", [AGENT_SESSION_TS_ATTRIBUTE]: session.threadTs },
+  };
+};
+
+/** The Slack setter core's turn-anchor hook calls (registered in register.ts). */
+export function slackSurfaceSessionSetter(form: SlackFormCall = slackForm): SurfaceSessionSetter {
+  return async (attributes, status) => {
+    const session = slackAgentSessionOf(attributes);
+    if (!session) return undefined;
+    await setSlackSessionStatus({ ...session, status }, form);
+    return `${session.channelId}:${session.threadTs}`;
+  };
+}
+
+// --- the Stop button -------------------------------------------------------------------------------
+
+/** One press of the Stop button, as the route reads it. */
+export interface ParsedSessionStop {
+  readonly channelId: string;
+  /** The session's thread root. */
+  readonly threadTs: string;
+  /** Who pressed Stop. */
+  readonly userId: string;
+  /** From the `event_callback` envelope: Slack does not put it in the event. */
+  readonly teamId?: string;
+  readonly eventTs?: string;
+}
+
+/** Parse an `agent_session_stopped` envelope, or null for anything else. Pure. */
+export function parseAgentSessionStopped(envelope: SlackEventEnvelope): ParsedSessionStop | null {
+  if (envelope?.type !== "event_callback") return null;
+  const e = envelope.event as Record<string, unknown> | undefined;
+  if (!e || e.type !== AGENT_SESSION_STOPPED_EVENT) return null;
+  const channelId = typeof e.channel === "string" ? e.channel : "";
+  const threadTs = typeof e.thread_ts === "string" ? e.thread_ts : "";
+  const userId = typeof e.user === "string" ? e.user : "";
+  if (!channelId || !threadTs || !userId) return null;
+  const teamId = typeof envelope.team_id === "string" && envelope.team_id.length > 0 ? envelope.team_id : undefined;
+  return {
+    channelId,
+    threadTs,
+    userId,
+    ...(teamId ? { teamId } : {}),
+    ...(typeof e.event_ts === "string" ? { eventTs: e.event_ts } : {}),
+  };
+}
+
+/** A 1:1 DM channel id. Only there does the stop fall back to the channel's newest turn. */
+function isDmChannel(channelId: string): boolean {
+  return channelId.startsWith("D");
+}
+
+/** What the Stop route needs. */
+export interface SessionStopDeps {
+  /** eve's I/O-free cancel door, the same one the ✋ arm uses. */
+  readonly attachSession: AttachSessionForCancel;
+  /** The cancel path. Absent means the live `cancelAnchoredTurn`. */
+  readonly cancel?: typeof cancelAnchoredTurn;
+  /** The status call. Absent means the live {@link setSlackSessionStatus}. */
+  readonly setStatus?: (call: SlackSessionStatusCall) => Promise<boolean>;
+}
+
+/**
+ * Stop the turn a Stop press names, then set the session `active`.
+ *
+ * The turn is found by the session's thread first (the key the ✋ arm uses for a thread root). In the
+ * person's 1:1 DM it falls back to the DM's newest turn, because a top-level DM message keys its turn by
+ * the channel alone. In a shared channel it does not fall back: there the newest turn can belong to
+ * another thread, and cancelling nothing beats cancelling a guess. The status is set whatever the
+ * cancel answers, because a session left `processing` keeps its spinner for an hour. Never throws.
+ */
+export async function routeAgentSessionStop(ev: ParsedSessionStop, deps: SessionStopDeps): Promise<CancelResult> {
+  const p = resolvePartition(bindableForSlackIds({ teamId: ev.teamId, channelId: ev.channelId, userId: ev.userId }));
+  const anchorKey = turnAnchorKey("slack", ev.channelId, ev.threadTs);
+  const channelKey = isDmChannel(ev.channelId) ? turnChannelKey("slack", ev.channelId) : undefined;
+  let result: CancelResult;
+  try {
+    result = await (deps.cancel ?? cancelAnchoredTurn)({
+      org: p.org,
+      platform: "slack",
+      workspace: p.workspace,
+      requestedBy: ev.userId,
+      via: "stop-button",
+      query: { ...(anchorKey ? { anchorKey } : {}), ...(channelKey ? { channelKey } : {}) },
+      attachSession: deps.attachSession,
+    });
+  } catch (err) {
+    result = { outcome: "error", message: `stop failed: ${String(err)}` };
+  }
+  await (deps.setStatus ?? setSlackSessionStatus)({ channelId: ev.channelId, threadTs: ev.threadTs, status: "active" }).catch(() => false);
+  return result;
+}

package/agent/channels/slack-attachments.ts

@@ -33,6 +33,7 @@ import {
   registerAttachmentResolver,
   AttachmentOversizeError,
   type SlackAttachmentRow,
+  type BindableContext,
 } from "@open-everywhere/core/agent/adapter-api.js";
 import { fetchSlackAttachment } from "../access/slack-attachment-fetch.js";
 
@@ -135,6 +136,24 @@ export async function resolveSlackAttachmentDurable(fileId: string, org?: string
   }
 }
 
+/**
+ * The size-guarded byte pull over a TRUSTED `url_private`: the bot-token, host-pinned fetch, then the Content-Length
+ * pre-check (rejects with {@link AttachmentOversizeError} phase "declared" BEFORE the body is read), then the post-read
+ * cap (phase "actual"). Two callers: the guarded resolver below, and the voice-clip loader (slack-voice-clips.ts),
+ * which reads a clip off the event that woke the agent. Both pass an event-supplied URL, never a model string.
+ */
+export async function pullSlackAttachmentBytes(ctx: BindableContext, ref: { readonly urlPrivate: string; readonly id?: string }, maxBytes: number): Promise<Uint8Array> {
+  const res = await fetchSlackAttachment(ctx, ref);
+  if (!res.ok) throw new Error(`fetching the upload failed (HTTP ${res.status})`);
+  // Content-Length pre-check off the declared length — reject before reading the body.
+  const declared = Number.parseInt(res.headers.get("content-length") ?? "", 10);
+  if (Number.isFinite(declared) && declared > maxBytes) throw new AttachmentOversizeError(declared, "declared", maxBytes);
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  // Post-read cap — a chunked response can exceed the (possibly-absent) Content-Length.
+  if (bytes.byteLength > maxBytes) throw new AttachmentOversizeError(bytes.byteLength, "actual", maxBytes);
+  return bytes;
+}
+
 /**
  * Register Slack as an attachment-plane resolver (channels/attachments.ts) — the neutral seam
  * describe_image consults so its contract carries no per-platform union arm. The resolver wraps the
@@ -169,17 +188,7 @@ export function registerSlackAttachmentResolver(): void {
         ref: `slack-file:${attachmentId}`,
         mimeType: rec.mimeType,
         name: rec.name,
-        async pull({ maxBytes }) {
-          const res = await fetchSlackAttachment(ctx, { urlPrivate: rec.urlPrivate, id: attachmentId });
-          if (!res.ok) throw new Error(`fetching the upload failed (HTTP ${res.status})`);
-          // Content-Length pre-check off the declared length — reject before reading the body.
-          const declared = Number.parseInt(res.headers.get("content-length") ?? "", 10);
-          if (Number.isFinite(declared) && declared > maxBytes) throw new AttachmentOversizeError(declared, "declared", maxBytes);
-          const bytes = new Uint8Array(await res.arrayBuffer());
-          // Post-read cap — a chunked response can exceed the (possibly-absent) Content-Length.
-          if (bytes.byteLength > maxBytes) throw new AttachmentOversizeError(bytes.byteLength, "actual", maxBytes);
-          return bytes;
-        },
+        pull: ({ maxBytes }) => pullSlackAttachmentBytes(ctx, { urlPrivate: rec.urlPrivate, id: attachmentId }, maxBytes),
       };
     },
   });

package/agent/channels/slack-bot-ask.ts

@@ -0,0 +1,101 @@
+// SLACK'S ARM OF CHIEF-OF-STAFF DELEGATION (OPE-2426) — the probe that proves an ask to another bot, and
+// the facts the front route hands core for an inbound bot message. Core holds the policy
+// (core/agent/channels/bot-ask.ts); this file only reads Slack.
+//
+// THE PROBE reads three facts with the BOT token, never a model string:
+//   1. the ask message itself (`conversations.replies` on its ts). The bot token reads it only when this
+//      app is in the channel, and the app must be in the channel to receive the other bot's reply at all.
+//      So an unreadable message is a refusal that says "invite the agent";
+//   2. its author is the person who asks, and its own text @mentions the named bot;
+//   3. the named account is a bot (`users.info` `is_bot`), and not this app itself (`auth.test`). An
+//      unknown own identity refuses: it cannot prove "not this app".
+// Any failed call refuses (`unreadable`). The probe never throws.
+
+import type { BotAskProbe, BotAskProbeAnswer, BotReplyFacts } from "@open-everywhere/core/agent/adapter-api.js";
+import { encodeSlackForm } from "./slack-web-api.js";
+import type { ParsedMessageEvent } from "./slack-events.js";
+
+/** The Slack calls the probe makes (injectable for the unit test). */
+export interface SlackBotAskDeps {
+  /** One Web API call with the bot token; resolves the parsed body, or undefined on a transport failure. */
+  readonly call: (method: string, body: Record<string, string>) => Promise<Record<string, unknown> | undefined>;
+  /** This app's own bot user id and bot id (`auth.test`), best-effort. */
+  readonly self: () => Promise<{ readonly userId?: string; readonly botId?: string }>;
+}
+
+type SlackMessage = { readonly ts?: unknown; readonly thread_ts?: unknown; readonly user?: unknown; readonly text?: unknown };
+
+/** Does the text @mention this user id (`<@U123>` or `<@U123|name>`)? PURE. */
+export function mentionsUser(text: string, userId: string): boolean {
+  return text.includes(`<@${userId}>`) || text.includes(`<@${userId}|`);
+}
+
+/** Build Slack's probe. */
+export function slackBotAskProbe(deps: SlackBotAskDeps): BotAskProbe {
+  return async (q): Promise<BotAskProbeAnswer> => {
+    try {
+      const [platform, teamId] = q.workspaceKey.split("/");
+      if (platform !== "slack" || !teamId) return { ok: false, reason: "unreadable" };
+      const replies = await deps.call("conversations.replies", { channel: q.channel, ts: q.messageTs, limit: "1", inclusive: "true" });
+      const messages = replies?.ok === true && Array.isArray(replies.messages) ? (replies.messages as SlackMessage[]) : [];
+      const msg = messages.find((m) => m.ts === q.messageTs);
+      if (!msg) return { ok: false, reason: "unreadable" };
+      if (msg.user !== q.personId) return { ok: false, reason: "not-yours" };
+      const text = typeof msg.text === "string" ? msg.text : "";
+      if (!mentionsUser(text, q.bot)) return { ok: false, reason: "bot-not-named" };
+      const self = await deps.self().catch(() => ({}) as { userId?: string; botId?: string });
+      // FAIL-CLOSED: without this app's own user id, a mention of this app cannot be told from another bot's.
+      if (self.userId === undefined) return { ok: false, reason: "unreadable" };
+      if (self.userId === q.bot) return { ok: false, reason: "self" };
+      const info = await deps.call("users.info", { user: q.bot });
+      const user = info?.ok === true && info.user && typeof info.user === "object" ? (info.user as Record<string, unknown>) : undefined;
+      if (!user) return { ok: false, reason: "unreadable" };
+      if (user.is_bot !== true) return { ok: false, reason: "not-a-bot" };
+      const profile = user.profile && typeof user.profile === "object" ? (user.profile as Record<string, unknown>) : {};
+      const botId = typeof profile.bot_id === "string" && profile.bot_id.length > 0 ? profile.bot_id : undefined;
+      if (botId !== undefined && self.botId !== undefined && botId === self.botId) return { ok: false, reason: "self" };
+      const label = [user.real_name, profile.display_name, user.name].find((v) => typeof v === "string" && v.trim().length > 0) as string | undefined;
+      return {
+        ok: true,
+        threadTs: typeof msg.thread_ts === "string" && msg.thread_ts.length > 0 ? msg.thread_ts : q.messageTs,
+        botUserId: q.bot,
+        ...(botId === undefined ? {} : { botId }),
+        ...(label === undefined ? {} : { botLabel: label }),
+        askText: text,
+      };
+    } catch {
+      return { ok: false, reason: "unreadable" };
+    }
+  };
+}
+
+/** The live deps: `slackForm` with the bot token, and the front route's cached `auth.test`. */
+export function liveSlackBotAskDeps(
+  form: (method: string, body: string) => Promise<Record<string, unknown> | undefined>,
+  self: () => Promise<{ readonly userId?: string; readonly botId?: string }>,
+): SlackBotAskDeps {
+  return { call: (method, body) => form(method, encodeSlackForm(body)), self };
+}
+
+/** Is this parsed message a candidate for the asked-thread exception at all? A cheap, pure pre-filter, so a
+ *  human message never pays a store read. PURE. */
+export function botReplyCandidate(ev: ParsedMessageEvent): boolean {
+  return (Boolean(ev.botId) || ev.subtype === "bot_message") && ev.threadTs !== undefined && ev.threadTs !== ev.ts;
+}
+
+/** Core's facts for one parsed Slack message. PURE. */
+export function slackBotReplyFacts(ev: ParsedMessageEvent, org: string, self: { readonly userId?: string; readonly botId?: string }): BotReplyFacts {
+  return {
+    org,
+    platform: "slack",
+    workspace: ev.teamId,
+    channel: ev.channelId,
+    threadTs: ev.threadTs,
+    messageTs: ev.ts,
+    authorUserId: ev.userId,
+    authorBotId: ev.botId,
+    subtype: ev.subtype,
+    ...(self.userId === undefined ? {} : { selfUserId: self.userId }),
+    ...(self.botId === undefined ? {} : { selfBotId: self.botId }),
+  };
+}