@open-everywhere/provider-slack 0.1.0

package/agent/channels/slack-read.ts

@@ -0,0 +1,248 @@
+// Component 3 of the Slack engagement model (slack-engagement-spec.md): domain-scoped
+// channel reads. "If a domain has 3 channels, the agent knows all 3 and can read them —
+// and NOTHING else." The Slack bot token is workspace-wide (it can read any channel the
+// bot is in), so the boundary is OURS to enforce at the tool layer — the same shape as the
+// connector hard-gate (access/connector-scope.ts): broad credential underneath, narrow
+// allowlist on top, FAIL CLOSED. The domain's channel list IS the allowlist.
+//
+// This module is the shared spine for the Slack read path (channels/channel-read.ts's SLACK
+// adapter, behind the generic read verbs): resolve the allowed channel ids for the session, assert a
+// requested channel is in them (or throw), and make the actual Slack Web API call. The call
+// goes through OE's `callSlackWebApi` (channels/slack-web-api.ts) — the ONE Slack Web API seam,
+// which carries the 429/`Retry-After` backoff — form-encoded with the same `SLACK_BOT_TOKEN` env
+// fallback the Slack channel itself uses.
+
+import { callSlackWebApi } from "./slack-web-api.js";
+import {
+  auditChannelReadRefusal,
+  bindFrom,
+  getConfig,
+  domainForChannel,
+  resolvePartition,
+  refutedReadAuthorIds,
+  ChannelScopeError,
+  markNotApplied,
+  type BindableContext,
+  type ReadScopeAuditDeps,
+  type RenderedLine,
+  type WakeReadAddress,
+  domainRoster,
+} from "@open-everywhere/core/agent/adapter-api.js";
+// The SAME per-author membership probe the wake leg uses (OPE-474) — see the adapter's own note on
+// why this is reused rather than re-derived. The direction is safe: slack-events.ts does not import
+// this module, so nothing here closes a cycle.
+import { slackAuthorIsMember, type SlackMemberProbe } from "./slack-events.js";
+
+// ChannelScopeError now LIVES in core (channels/channel-read.ts) — it predates the generic read
+// verbs and the platform-parameterised assertSurfaceAllowed throws the same class, so the ONE
+// class identity must sit on the core side of the boundary. Re-exported here so the bundle's own
+// callers/tests keep their import site.
+export { ChannelScopeError };
+
+// A fully-qualified surface key is `platform/workspace/surface`; for Slack the surface
+// segment IS the channel id. Returns null for non-Slack keys (defensive — domains can span
+// platforms in principle, and we only gate Slack here).
+function channelIdFromKey(key: string): string | null {
+  const parts = key.split("/");
+  if (parts.length !== 3 || parts[0] !== "slack") return null;
+  return parts[2] || null;
+}
+
+/**
+ * The Slack channel ids this session may read: every Slack channel in its explicit domain,
+ * PLUS its own current channel (always readable — it's where the agent was engaged). A DM,
+ * an unassigned channel, or a criteria pseudo-domain (org/public/dm — no channel list)
+ * yields just the current channel. Empty only when the surface isn't a Slack channel.
+ */
+export function allowedChannelIds(ctx: BindableContext): { ids: Set<string>; domain?: string } {
+  const p = resolvePartition(ctx);
+  const ids = new Set<string>();
+  const own = channelIdFromKey(p.surfaceKey);
+  if (own) ids.add(own); // the agent can always read its own channel
+  const domain = domainForChannel(p.surfaceKey, getConfig().loadDomains());
+  if (domain) {
+    for (const key of domainRoster(domain)) {
+      const id = channelIdFromKey(key);
+      if (id) ids.add(id);
+    }
+  }
+  return { ids, domain: domain?.name };
+}
+
+/**
+ * Assert a requested channel id is readable by this session — else AUDIT the refusal and throw
+ * (fail closed). The error names the domain so the model gets an actionable message, not a bare
+ * denial. The decision is unchanged from the silent version; only the row is new
+ * (core channels/read-scope-audit.ts).
+ */
+export async function assertChannelAllowed(ctx: BindableContext, channelId: string, deps?: ReadScopeAuditDeps): Promise<void> {
+  const { ids, domain } = allowedChannelIds(ctx);
+  if (ids.has(channelId)) return;
+  const p = resolvePartition(ctx);
+  await auditChannelReadRefusal(
+    ctx,
+    { platform: "slack", surfaceId: channelId, callerKey: p.surfaceKey, callerDomain: domain, domains: getConfig().loadDomains() },
+    deps,
+  );
+  const scope = domain ? `domain "${domain}"` : "this channel's (no multi-channel domain)";
+  throw new ChannelScopeError(
+    `channel "${channelId}" is not in ${scope} read scope. The agent may only read channels in its ` +
+      `memory domain (memory/config/domains.ts). Add the channel to the domain's \`channels\` to grant it.`,
+  );
+}
+
+interface SlackReadResponse {
+  readonly ok: boolean;
+  readonly error?: string;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Low-level POST to a (read-only) Slack Web API method with the bot token, via OE's
+ * `callSlackWebApi` (form-encoded — Slack's JSON support is partial: `conversations.replies`/
+ * `history` want form). Throws on a missing token or a non-ok Slack response so the tool
+ * surfaces a real error. The explicit env pre-check keeps the actionable "not set" message
+ * (the seam itself throws a terser "SLACK_BOT_TOKEN is required.").
+ */
+export async function callSlackRead(operation: string, params: Record<string, string | number | boolean>): Promise<SlackReadResponse> {
+  if (!process.env.SLACK_BOT_TOKEN) {
+    throw new Error("SLACK_BOT_TOKEN is not set — the Slack read tools need the bot token to call the Web API.");
+  }
+  // botToken omitted → the seam resolves it from SLACK_BOT_TOKEN (same fallback as before).
+  const json = (await callSlackWebApi({ botToken: undefined, operation, body: params })) as SlackReadResponse;
+  // DEFINITIVE (OPE-821): Slack answers HTTP 200 with `ok:false` when it READ the request and
+  // refused it, so the call had no effect. `react` is the caller that acts on this — a refused
+  // `reactions.add` proves no reaction landed. A throw from the seam (transport, or a non-2xx)
+  // never reaches this line and stays AMBIGUOUS, which is the honest answer for a call that got no
+  // reply. Marking it here rather than in `react` keeps ONE statement of what Slack's `ok:false`
+  // means, for every method that goes through this transport.
+  if (!json.ok) throw markNotApplied(new Error(`Slack ${operation} failed: ${json.error ?? "unknown error"}`));
+  return json;
+}
+
+/** One Slack message rendered to a compact, model-friendly line. */
+export interface RenderedMessage {
+  readonly author: string;
+  readonly ts: string;
+  readonly text: string;
+  /** The author's Slack USER id, for the OPE-474 non-member probe. Absent on a machine-authored or
+   *  unattributable line. It never reaches the model — the read verbs project author/ts/text only. */
+  readonly authorId?: string;
+  /** A machine author (`bot_id` present). Excluded from the probe: a bot is below a member but is
+   *  not a person outside the org — the same exclusion access/taint-signal.ts makes for `relay`. */
+  readonly bot?: boolean;
+}
+
+/**
+ * Normalize a raw Slack messages array (history/replies) to rendered lines, oldest-first.
+ *
+ * `author` IS UNCHANGED and stays the display string the model reads (`user`, else `bot_id`, else
+ * `(unknown)`) — every render golden depends on it. OPE-474 adds the two GRADING fields beside it
+ * rather than reinterpreting it: `author` is chosen for legibility and cannot be parsed back into an
+ * identity, which is exactly why the read leg had nothing to probe before.
+ *
+ * `bot_id` WINS over `user` for the machine classification, even on the messages that carry both (an
+ * app posting as a bot user). That direction is fail-OPEN — a machine is dropped from the probe and
+ * marks nothing — which is the posture the whole author leg takes.
+ */
+export function renderMessages(raw: unknown, opts: { oldestFirst?: boolean } = {}): RenderedMessage[] {
+  if (!Array.isArray(raw)) return [];
+  const out: RenderedMessage[] = [];
+  for (const m of raw as Array<Record<string, unknown>>) {
+    if (typeof m.subtype === "string" && m.subtype.length > 0) continue; // skip joins/edits/system
+    const text = typeof m.text === "string" ? m.text : "";
+    if (!text) continue;
+    const user = typeof m.user === "string" && m.user.length > 0 ? m.user : undefined;
+    const botId = typeof m.bot_id === "string" && m.bot_id.length > 0 ? m.bot_id : undefined;
+    out.push({
+      author: (m.user as string) ?? (m.bot_id as string) ?? "(unknown)",
+      ts: (m.ts as string) ?? "",
+      text,
+      ...(botId !== undefined ? { bot: true } : user !== undefined ? { authorId: user } : {}),
+    });
+  }
+  // conversations.history returns newest-first; replies returns oldest-first.
+  if (opts.oldestFirst === false) out.reverse();
+  return out;
+}
+
+// --- the SLACK read adapter (moved from core channels/channel-read.ts in OPE-114 stage 4) ---
+// Registered by registerSlackProvider() via registerReadAdapter — the generic read verbs
+// (read_channel / read_thread) resolve it by platform string; behaviour is byte-identical to the
+// in-core adapter (the EXACT calls the retired per-surface Slack read tools made).
+
+const SLACK_CHANNEL_DEFAULT_LIMIT = 50;
+const SLACK_THREAD_DEFAULT_LIMIT = 100;
+
+/** The Slack read transport — injectable for offline tests (defaults to the live callSlackRead). */
+export type SlackReadCall = typeof callSlackRead;
+
+// --- the OPE-474 non-member author leg ---------------------------------------------------------
+//
+// Slack is the one chat surface that can refute an author BY ITSELF: `users.info` reports
+// `is_restricted` / `is_ultra_restricted` / `is_stranger`, which slack-events.ts's
+// {@link slackAuthorIsMember} already folds into one TTL-cached boolean for the wake leg. The read
+// leg reuses THAT probe verbatim — a second implementation of "is this person a member?" is how a
+// wake and a read come to disagree about the same author.
+//
+// 🔴 THE COST IS BOUNDED BY PEOPLE, NOT BY MESSAGES (Tommy, 2026-08-14: no up-front member list).
+// `refutedReadAuthorIds` probes the page's DISTINCT authors, and the probe is TTL-cached across
+// calls, so a 200-message read of a busy channel is a handful of authors and mostly cache hits. An
+// up-front roster would instead size with the WORKSPACE and go stale between reads.
+//
+// THE THREE-WAY VERDICT IS KEPT THREE-WAY. `slackAuthorIsMember` answers `true` (member), `false`
+// (positively refuted) or `undefined` (lookup unavailable), and only `false` refutes. Collapsing
+// `undefined` into a refusal would mark every read on a deployment whose bot token cannot call
+// `users.info` — an always-on bit, arriving through this door.
+
+/** The Slack team id + the register's arming key for this session's own workspace. Both come from
+ *  the BINDING, never from inspecting an author id: the platform and the tenant are surface facts. */
+function slackReadTenant(ctx: BindableContext): { teamId: string; tenantKey: string } {
+  const p = resolvePartition(ctx);
+  return { teamId: p.workspace, tenantKey: p.workspaceKey };
+}
+
+/** Slack read via OE's callSlackWebApi — domain-allowlist-gated, rendered oldest-first. */
+export const slackReadAdapter = {
+  platform: "slack" as const,
+  /**
+   * OPE-929 — Slack's own spelling of "which room and which thread is this turn in".
+   *
+   * The CONTAINER is the channel the post-back target names. The THREAD ROOT is `threadTs`, which
+   * eve's Slack adapter falls back to the triggering message's own ts — so a bare channel mention
+   * carries one too, and reading "this thread" on such a turn reads the one-message thread the
+   * mention started, which is what a person means by it.
+   */
+  wakeAddress(ctx: BindableContext): WakeReadAddress | undefined {
+    const b = bindFrom(ctx);
+    const container = typeof b.target?.["channelId"] === "string" ? (b.target["channelId"] as string) : undefined;
+    if (!container) return undefined;
+    return { container, ...(b.threadTs ? { threadRoot: b.threadTs } : {}) };
+  },
+  async readChannel(ctx: BindableContext, channel: string, limit?: number, call: SlackReadCall = callSlackRead): Promise<readonly RenderedLine[]> {
+    await assertChannelAllowed(ctx, channel);
+    const res = await call("conversations.history", { channel, limit: limit ?? SLACK_CHANNEL_DEFAULT_LIMIT, inclusive: true });
+    return renderMessages(res.messages, { oldestFirst: false });
+  },
+  async readThread(ctx: BindableContext, channel: string, threadTs: string, limit?: number, call: SlackReadCall = callSlackRead): Promise<readonly RenderedLine[]> {
+    await assertChannelAllowed(ctx, channel);
+    const res = await call("conversations.replies", { channel, ts: threadTs, limit: limit ?? SLACK_THREAD_DEFAULT_LIMIT });
+    return renderMessages(res.messages, { oldestFirst: true });
+  },
+  /** OPE-474 / OPE-534. Both legs run: Slack's own `users.info` refutation, and the operator's
+   *  author-trust register (which most Slack deployments leave unarmed, so it costs nothing there).
+   *  It answers with the refuted AUTHOR IDS, because core reads the one answer twice — the turn mark
+   *  and the `withhold` body replacement. `probe` is injected ONLY so a test can drive the grading
+   *  without a live Slack — every live call defaults. */
+  async refutedAuthorIds(ctx: BindableContext, lines: readonly RenderedLine[], probe: SlackMemberProbe = slackAuthorIsMember): Promise<readonly string[]> {
+    const { teamId, tenantKey } = slackReadTenant(ctx);
+    return await refutedReadAuthorIds(lines, tenantKey, {
+      surfaceRefuted: async (authorId) => {
+        const member = await probe(authorId, teamId);
+        return member === undefined ? undefined : !member; // undefined stays "cannot check"
+      },
+      // No `memberships` leg: Slack has no group-rung key a message carries, so an armed register
+      // matches this surface on principal keys alone (`slack/<team>/<user>`).
+    });
+  },
+};

package/agent/channels/slack-route-hold.ts

@@ -0,0 +1,107 @@
+// THE ROUTE HOLD (OPE-1648) — "keep this best-effort write alive until it lands".
+//
+// WHAT IT CLOSES. Every Slack door answers its 200 IMMEDIATELY: Slack retries a delivery it does
+// not see acked inside three seconds, and eve's own dispatcher returns the response and then
+// finishes the turn in the route's `waitUntil`. On Vercel the serverless invocation can freeze the
+// moment nothing is holding it, so a `void`-ed audit write races that freeze and the row never
+// lands. Those rows are not decoration: `slack.ts`'s `auditWakeDropped` header states that the
+// webhook function's console output never reaches `vercel logs`, so the row is the ONLY durable
+// signal that a wake was refused.
+//
+// 🔴 A LATE `waitUntil` CALL IS NOT A HOLD, WHICH IS WHY THIS FILE EXISTS AT ALL. eve collects the
+// route's background tasks in an array and, the moment the handler resolves, hands the platform
+// `Promise.allSettled(tasks)` (`internal/nitro/routes/channel-dispatch.js`, `flushBackgroundTasks`).
+// `allSettled` reads that array ONCE, synchronously — so a promise pushed after the handler returned
+// is in a list nobody is awaiting, and calling `waitUntil` from a wake route that runs after the 200
+// buys exactly nothing. Almost every write this module holds is in that position.
+//
+// SO THE HOLD RIDES THE WORK THE ROUTE ALREADY REGISTERED. Every one of these writes happens inside
+// a promise the front route handed to `waitUntil` while it was still running — eve's own turn
+// dispatch on the native forward, a FIFO wake, a name-drop. `slack-front.ts` wraps each of those in
+// {@link routeHoldQuiesced} before passing it on, so the promise the platform waits on settles only
+// after the delivery's tracked writes have. Nothing extra is registered: a delivery that queues no
+// background work (a 401, a dropped sibling event) hands the platform nothing, exactly as before.
+//
+// WHY AsyncLocalStorage AND NOT A PARAMETER. The writers do not hold the route args: the mention
+// door's row is written inside eve's `onAppMention` hook, several frames below a hand-off that
+// discards them, and the engagement doors' rows are written from route functions that take deps.
+// Threading a serverless-runtime concern through every wake route's signature to reach them would
+// put it in the type of each one. The front route stows it once instead, for the extent of ONE
+// delivery. One process serves many Slack deliveries at once, and a module global would mix
+// delivery A's writes into delivery B's hold. Same primitive and same reasoning as
+// slack-identity.ts's forwarded-envelope carrier, which is proven to survive the hand-off into eve's
+// handler (slack-enterprise-rung-test.ts §2).
+//
+// 🔴 IT NEVER CHANGES A DECISION, AND IT NEVER THROWS. A hold is observability plumbing: every
+// tracked write already swallows its own failures, and the quiesced promise settles rather than
+// rejects, so a broken sink can never turn a drop into a turn.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** What one delivery is still waiting on. */
+interface RouteHold {
+  /** Work registered since the last drain round. Swapped out wholesale each round. */
+  pending: Promise<unknown>[];
+}
+
+/**
+ * How many drain rounds one quiesce gets. Each round awaits everything registered so far, so a round
+ * only follows work that another round's work started. Ten is far past any real chain (a wake queues
+ * one audit write, which queues nothing) and it bounds a writer that re-registers itself forever —
+ * which would otherwise hold the invocation open until the platform killed it.
+ */
+const MAX_DRAIN_ROUNDS = 10;
+
+const routeHold = new AsyncLocalStorage<RouteHold>();
+
+/**
+ * Run `fn` as ONE delivery, so the writes below it can be tracked.
+ *
+ * ONE caller: `slack-front.ts`'s public route handler, wrapping its whole body. Do not wrap anything
+ * else; the value means "the delivery in flight right now", and a second writer would make that
+ * false.
+ */
+export function withSlackRouteHold<T>(fn: () => T): T {
+  return routeHold.run({ pending: [] }, fn);
+}
+
+/**
+ * Track a best-effort write on the delivery in flight, and hand it back so a caller that can also
+ * await it may.
+ *
+ * `work` MUST already swallow its own failures — every caller here is an audit write whose contract
+ * is "never throws, never changes the decision". Nothing is caught for it: swallowing a rejection
+ * here would let a genuinely broken writer look held.
+ *
+ * Outside a delivery (a unit test calling a door directly, a future non-route caller) there is
+ * nothing to track and the work comes straight back — so `await holdRouteWork(...)` is correct in
+ * both worlds and a caller never has to ask which one it is in.
+ */
+export function holdRouteWork<T>(work: Promise<T>): Promise<T> {
+  routeHold.getStore()?.pending.push(work);
+  return work;
+}
+
+/**
+ * The promise to hand the platform in place of `work`: it settles when `work` has settled AND every
+ * write {@link holdRouteWork} tracked has settled too.
+ *
+ * 🔴 CALL IT SYNCHRONOUSLY, INSIDE THE DELIVERY — it reads the delivery's tracked set at call time
+ * and closes over it, so a call from outside one silently degrades to "just `work`". `slack-front.ts`
+ * calls it from the `waitUntil` it hands down, which is exactly that position.
+ *
+ * It never rejects: a rejected `work` is the caller's own business (eve already logs its background
+ * task failures), and a hold that rejected would turn an observability write into a route error.
+ */
+export function routeHoldQuiesced(work: Promise<unknown>): Promise<void> {
+  const hold = routeHold.getStore();
+  return (async () => {
+    await Promise.allSettled([work]);
+    if (!hold) return;
+    for (let round = 0; round < MAX_DRAIN_ROUNDS && hold.pending.length > 0; round++) {
+      const batch = hold.pending;
+      hold.pending = [];
+      await Promise.allSettled(batch);
+    }
+  })();
+}