@open-everywhere/provider-slack 0.1.0

package/agent/channels/slack-commands.ts

@@ -0,0 +1,227 @@
+// The Slack SLASH-COMMAND ingestion surface for "/oe" — the zero-inference control-plane
+// escape hatch (backlog item 23): pure logic, instant code-rendered responses, NO model turn,
+// so it keeps answering regardless of spend caps, engagement state, or a model/gateway
+// outage. See agent/commands/core.ts for the full command grammar and rationale.
+//
+// MOUNTING CHOICE mirrors channels/webhooks.ts / channels/discord-gateway.ts: a plain
+// `defineChannel` with ONE brand-new POST route, not a front over slack.ts's existing route
+// (the slack-front.ts pattern). Slack's Slash Command Request URL is a SEPARATE, independently
+// configurable field from the Event Subscriptions URL slack-front.ts already fronts — unlike
+// Discord, which delivers everything (events, components, commands) to ONE fixed Interactions
+// Endpoint URL and therefore has to intercept "/oe" inside its existing front route
+// (channels/discord-front.ts). A brand-new public surface with no existing owner is exactly
+// the case webhooks.ts's own header argues for the plain-route mount over forwarding.
+//
+// Slack signs every slash-command POST the SAME way it signs Events API deliveries (`v0=`
+// HMAC-SHA256 of `v0:{timestamp}:{raw body}`, keyed by SLACK_SIGNING_SECRET, 5-minute skew) —
+// `verifySlackSignature` is REUSED verbatim from channels/slack-front.ts rather than
+// re-implemented. Fail-closed: no secret, a missing/malformed header, a stale timestamp, or a
+// mismatch all return false → 401.
+//
+// Response: Slack needs an ack within 3 seconds. Every branch here is a fast, code-only path
+// (parse + a couple of small store reads, or requestApproval's card post) — well inside that
+// budget — so the route always answers SYNCHRONOUSLY with `response_type: "ephemeral"` JSON;
+// only the invoker sees the text reply. `/oe budget raise|clear` ALSO post a SEPARATE, PUBLIC
+// approval card via requestApproval (the same card the model-driven set_spend_limit/
+// clear_spend_limit tools post) — the ephemeral response here is only the "card posted" ack.
+//
+// SPEND CAPS DELIBERATELY DO NOT GATE THIS ROUTE — see core.ts's header for why.
+//
+// THE TENANT FENCE DOES GATE IT (OPE-1633). The signature proves the POST came from Slack, never
+// that it came from a workspace this deployment serves, so an unadmitted workspace's `/oe` is
+// refused with an empty 200 and an audit row before any command runs. See the fence block in the
+// route below for what such a command reached before.
+
+import { defineChannel, POST } from "eve/channels";
+import { verifySlackSignature } from "./slack-front.js";
+import {
+  bindFrom,
+  runOeCommand,
+  parseSlackCommandText,
+  resolvePartition,
+  getOperationalStore,
+  admittedTenantsFromConfig,
+  unadmittedTenantLog,
+  UNADMITTED_TENANT_DROP_REASON,
+  type BindableContext,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { slackTenantAdmission } from "./slack-tenant-fence.js";
+
+function log(msg: string): void {
+  console.log(`[open-everywhere:slack-commands] ${msg}`);
+}
+
+/** The public URL Slack POSTs the "/oe" slash command to (the app's Slash Command Request URL). */
+export const SLACK_COMMANDS_ROUTE = "/eve/v1/slack/commands";
+
+/** One non-empty form field, or undefined — this is untrusted form-encoded wire data (Slack's
+ *  slash-command payload), so every field is probed rather than assumed present. */
+function formField(params: URLSearchParams, name: string): string | undefined {
+  const v = params.get(name);
+  return v && v.length > 0 ? v : undefined;
+}
+
+/** Build the BindableContext the identity seam (bindFrom/bindSlack) expects from Slack's
+ *  slash-command form fields. Slack's slash-command payload carries no `channel_type` /
+ *  `is_private` bit (unlike an app_mention/message event) — `bindSlack`'s existing fallbacks
+ *  already handle that (DM detection via the `channel_id`'s "D" prefix; visibility fails
+ *  closed to private), same posture as every other under-specified Slack event.
+ *
+ *  🔴 IT DOES CARRY THE ENTERPRISE GRID RUNG (OPE-1559). Slack sends `enterprise_id` as a form field
+ *  on a Grid, beside `team_id`, and it reaches `RawIdentity.trustEnterprise` → the declaration walk →
+ *  `binding.declaredTrust`. That is the OPERATOR-DECLARATION half — the half `roomVouchedInternalFrom`
+ *  reads — so a Grid declared once now answers here the same way it answers at every other door,
+ *  instead of resolving as though the line were absent.
+ *
+ *  🔴 STATE ITS REACH EXACTLY, because this door is narrower than the wake doors. For a CHANNEL
+ *  command it does NOT change `binding.trust`: this payload carries no `conversations.info` verdict,
+ *  so `slackTrust(undefined, undefined, "channel")` fails closed to `external`, and `bindFrom` takes
+ *  that raw verdict ahead of any vouch. So a channel `/oe` stays `trust: "external"` with the rung
+ *  and without it, and the budget scope `domainNameForScope` picks is unchanged. The rung reaches
+ *  `binding.trust` only on a DM-shaped `/oe` (a `D…` channel id), where the mapper leaves trust
+ *  undefined and the vouch is what answers. Spread conditionally, like every other door: a
+ *  single-workspace install stamps nothing. */
+export function bindableForSlashCommand(params: URLSearchParams): BindableContext {
+  const enterpriseId = formField(params, "enterprise_id");
+  return {
+    channel: { kind: "slack" },
+    session: {
+      auth: {
+        current: {
+          attributes: {
+            team_id: formField(params, "team_id") ?? "",
+            channel_id: formField(params, "channel_id") ?? "",
+            ...(enterpriseId ? { enterprise_id: enterpriseId } : {}),
+          },
+          principalId: formField(params, "user_id") ?? "",
+          principalType: "slack-user",
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Make a refused slash command OBSERVABLE, the same way `slack.ts`'s `auditWakeDropped` makes a
+ * refused wake observable: the webhook function's console output never reaches `vercel logs`, so
+ * one `surface.wake_dropped` row per refusal is the only durable signal. Never throws, never
+ * changes the decision.
+ *
+ * 🔴 IT RETURNS ITS PROMISE, AND THE ROUTE HANDS THAT PROMISE TO `waitUntil`. This route answers
+ * IMMEDIATELY — Slack needs an ack inside three seconds — so a fire-and-forget write races the
+ * serverless freeze that follows the response, and the row this file calls "the only durable
+ * signal" would sometimes never land. `channels/webhooks.ts` takes the same `waitUntil` from the
+ * same route args for the same reason.
+ *
+ * The action is `surface.wake_dropped` rather than a new one, because the operator reads ONE
+ * greppable action for "a delivery reached a door and ran nothing", and `door` says which door it
+ * was. This row's `door` is `slash-command`; no wake was scheduled here, and none would have been —
+ * the `/oe` route runs no model turn at all.
+ */
+async function auditCommandDropped(teamId: string | undefined, channelId: string | undefined, reason: string, enterpriseId?: string): Promise<void> {
+  try {
+    const p = resolvePartition({
+      channel: { kind: "slack" },
+      session: { auth: { current: { attributes: { team_id: teamId ?? "", channel_id: channelId ?? "" }, principalId: "", principalType: "slack-user" } } },
+    } as BindableContext);
+    await getOperationalStore().appendAudit({
+      ts: new Date().toISOString(),
+      org: p.org,
+      platform: p.platform,
+      workspace: p.workspace,
+      surface: p.surface,
+      action: "surface.wake_dropped",
+      detail: { reason, door: "slash-command", channel: channelId ?? null, team: teamId ?? null, enterprise: enterpriseId ?? null },
+    });
+  } catch {
+    /* observability only */
+  }
+}
+
+function ephemeralResponse(text: string): Response {
+  return new Response(JSON.stringify({ response_type: "ephemeral", text }), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export default defineChannel({
+  routes: [
+    // `attachSession` is eve's I/O-free cancel door — taken here purely so "/oe stop" (OPE-418)
+    // can cancel an in-flight turn WITHOUT minting a session or calling a model. That is what
+    // keeps stop free and working while the scope is over its spend cap.
+    POST(SLACK_COMMANDS_ROUTE, async (req, { attachSession, waitUntil }) => {
+      const rawBody = await req.text();
+      if (!verifySlackSignature(rawBody, req.headers, process.env.SLACK_SIGNING_SECRET)) {
+        return new Response("unauthorized", { status: 401 });
+      }
+
+      const params = new URLSearchParams(rawBody);
+      const teamId = formField(params, "team_id");
+
+      // 🔴 THE TENANT FENCE (OPE-309 phase 0c / OPE-1633), and it sits ABOVE everything this route
+      // does. Slack signs a slash command with the APP-LEVEL signing secret, which every workspace
+      // that installed the app shares — so the verification above proves the POST came from Slack,
+      // never that it came from a workspace this deployment serves. Before this check the `/oe` door
+      // carried no tenant fence at all, while the mention door, the four dispatching engagement
+      // routes and the channel-join door all did.
+      //
+      // The DM door carries the fence too (OPE-1644): `slack-front.ts`'s `scheduleDmWake` is the
+      // chokepoint for a `message.im`/`message.mpim`, a DM-shaped shortcut and the mpim mention
+      // divert, and it consults `slackFrontTenantFenceDeclined` above the seat resolve. That path is
+      // WIDER than this one — it mints a DM seat holding a window token, delegation and memory.
+      //
+      // WHAT AN UNADMITTED WORKSPACE GOT BEFORE. `/oe` runs no model turn, so the exposure is not a
+      // turn — it is the ALIASING the fence exists for. `bindFrom` keys the invoker as
+      // `slack/<user id>`, and on Slack that id is issued PER WORKSPACE: a foreign `U…` that
+      // collides with a home member's resolves that member's standing. `/oe budget` then reports
+      // this deployment's spend for the scope that principal picks, and `/oe budget raise|clear`
+      // posts a real approval card against it. Refusing here is the same decision the wake doors
+      // make, one plane earlier.
+      //
+      // IT SITS ABOVE THE `/oe`-ONLY CHECK BELOW for the reason the mention door sits above the
+      // unmapped-channel nudge: the copy below names our own misconfiguration, and a foreign
+      // workspace must not be handed it.
+      //
+      // THE ANSWER IS AN EMPTY 200 — no ephemeral text. `unadmittedTenantLog`'s rule is that the
+      // operator gets the signal and the originating room gets nothing: we cannot safely identify
+      // anybody there, and a foreign tenant learning it reached a live deployment is more than it
+      // needs to know. The status keeps Slack from retrying; the empty body is what we choose to
+      // send, and what Slack renders for it is Slack's business.
+      //
+      // The audit write rides `waitUntil`, not a bare `void` — the response goes back at once and
+      // the invocation can freeze behind it, which would lose the row this refusal's only durable
+      // signal is. See {@link auditCommandDropped}.
+      const enterpriseId = formField(params, "enterprise_id");
+      if (slackTenantAdmission(teamId, enterpriseId) === "unadmitted") {
+        console.log(unadmittedTenantLog("slack", teamId, admittedTenantsFromConfig("slack"), enterpriseId));
+        waitUntil(auditCommandDropped(teamId, formField(params, "channel_id"), UNADMITTED_TENANT_DROP_REASON, enterpriseId));
+        return new Response(null, { status: 200 });
+      }
+
+      const command = formField(params, "command");
+      if (command !== "/oe") {
+        // Defensive, not a security gate: this route is dedicated to "/oe" — the Slack app's
+        // Slash Command config should only ever point ONE command at it. Anything else is a
+        // misconfiguration (a second command aimed at the same URL); answer politely instead
+        // of a bare 404/500 so it's obvious in Slack what to fix.
+        log(`unexpected slash command "${command ?? "?"}" hit the /oe route — check the Slack app's Slash Command config`);
+        return ephemeralResponse('This endpoint only handles "/oe" — check your Slack app\'s Slash Command configuration.');
+      }
+
+      const cmd = parseSlackCommandText(formField(params, "text"));
+      const binding = bindFrom(bindableForSlashCommand(params));
+      try {
+        const reply = await runOeCommand(cmd, binding, { attachSession });
+        return ephemeralResponse(reply);
+      } catch (err) {
+        // runOeCommand's budget-raise/clear branches can throw a user-facing validation error
+        // (e.g. proposing from a DM with no explicit scope) — surface it verbatim. Never let a
+        // thrown error escape as a 500; Slack's slash-command UX for that is an ugly
+        // "operation_timeout"/dispatch_failed toast.
+        log(`"/oe" command failed softly: ${String(err)}`);
+        return ephemeralResponse(`Couldn't complete that: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }),
+  ],
+});

package/agent/channels/slack-context.ts

@@ -0,0 +1,185 @@
+// Component 1 of the Slack engagement model:
+// give the agent the SURROUNDING CONVERSATION when it's triggered, not just the bare
+// @mention. Without this the agent sees only the tagged message + a `<slack_context>`
+// identity block — it can't "understand what's happening in Slack" the way Claude Tag
+// does. This module assembles that context and hands it back as `context` strings, which
+// the Slack channel appends to session history as user messages before the delivery turn.
+//
+// Two shapes, chosen by where the mention landed (SlackMessage.threadTs vs .ts):
+//   • thread reply  (threadTs ≠ ts) → prior messages IN THAT THREAD via Eve's native
+//     `loadThreadContextMessages`, bounded `since: "last-agent-reply"`. That boundary is
+//     self-correcting: when the agent has never spoken in the thread it returns ALL prior
+//     messages (the "tagged 10 deep, give me 1–9" case); once the agent has replied it
+//     returns only what's new since (the "re-tagged at 15, give me 11–14" case) — so it
+//     never re-injects what a durable resumed session already holds. One call, both cases.
+//   • channel-root mention (threadTs = ts) → a bounded backscroll of the channel via
+//     `conversations.history` (the "fetch 50 on join" load Claude Tag does), so a fresh
+//     mention in a busy channel still arrives with recent context.
+//
+// UNTRUSTED BY PROVENANCE: every line here was written by arbitrary workspace members, so
+// the whole block is wrapped with wrapUntrusted (access/untrusted.ts) — the model must
+// treat it as DATA, not instructions. This is the surface use-case that boundary exists
+// for (Claude Tag wraps fetched Slack content the same way).
+//
+// Best-effort throughout: any Slack API failure yields [] (no context) rather than
+// failing the turn — context is an enrichment, never a precondition.
+//
+// REUSE: the wake path (slack-wake-backscroll.ts) attaches the SAME kind of backscroll to a
+// name-drop wake, but it can't use Eve's `SlackContext` handle (the wake fires from a raw
+// route, not a live session) — it hits the Slack Web API directly with the bot token. So the
+// message→line mapping (`linesFromMessages`) is exported here and the render+untrusted wrap
+// (`renderContext`) + the `ContextLine` shape come from the SHARED context-render.ts, keeping
+// BOTH Slack paths' — and the Discord fetcher's — attribution + untrusted framing byte-identical
+// instead of forking a second renderer. The Slack-only bit (the read-more hint's TOOL NAMES)
+// stays here and is fed into renderContext; a surface with no read tools passes no hint.
+
+import type { SlackContext } from "eve/channels/slack";
+import { loadThreadContextMessages } from "eve/channels/slack";
+import type { SlackMessage } from "eve/channels/slack";
+import { MAX_MESSAGES, renderContext, type ContextLine } from "@open-everywhere/core/agent/adapter-api.js";
+
+// Re-export the shared render + line shape so slack-wake-backscroll.ts (which imports them from
+// here) keeps compiling unchanged after the extraction, and any future Slack consumer has one
+// import site. The mapping (`linesFromMessages`) is defined below — it's Slack-message-shaped.
+export { renderContext, type ContextLine };
+
+// When the rendered slice fills MAX_MESSAGES exactly, there's very likely more history above
+// it (both fetchers below request MAX_MESSAGES-worth from Slack, so filling the cap usually
+// means older messages were left out) — tell the model this is a bounded slice, not the whole
+// conversation, and name the tools that can pull more. This is OUR instruction (trusted), so
+// renderContext appends it OUTSIDE the untrusted-wrapped block, never inside where channel
+// content lives. Passed into renderContext so the shared renderer stays platform-neutral (a surface
+// with no read tools passes no hint).
+//
+// It names `read_channel` / `read_thread` — since OPE-1145 no per-surface reader stands beside them
+// on any deployment, so the hint has nothing to branch on and names one fixed pair.
+//
+// 🔴 THE OPE-780 DEFECT CLASS IS NOT REACHABLE TODAY, AND NO TEST PROVES THIS FUNCTION'S SHAPE.
+// OPE-780 was a `const` hint that named the tools of a deployment the seat was not on. That needed a
+// CONDITIONAL toolset, and there is no longer one, so the old flip-the-flag-and-re-call test is gone
+// with the flag. It stays a function as a CONVENTION — if a future change makes the mounted reader
+// conditional again, a module-load `const` would reintroduce OPE-780 silently. Nothing enforces
+// that; a refactor to a `const` would be green today. Say so rather than imply coverage.
+export function readMoreHint(): string {
+  return (
+    "Note: the block above is the most recent messages only, capped for context size — there may " +
+    "be older history not shown. If you need it, fetch more with the read_channel or read_thread tool."
+  );
+}
+
+/**
+ * Map raw Slack message objects (from `conversations.history` / `conversations.replies` — raw
+ * Web-API JSON, probe defensively) into {@link ContextLine}s, dropping system/subtype noise and
+ * empty-text messages. `ids` is the bot's resolved (userId, botId): a message authored by either
+ * is labelled `agent` (conversations.history/replies don't flag our own posts, so we compare
+ * ids). Order is PRESERVED — the caller reverses to oldest-first as needed before rendering.
+ * Pure, so both the mention path and the wake path share ONE mapping (no duplicated attribution).
+ */
+export function linesFromMessages(
+  raw: ReadonlyArray<Record<string, unknown>>,
+  ids: { readonly userId?: string; readonly botId?: string },
+): ContextLine[] {
+  const lines: ContextLine[] = [];
+  for (const m of raw) {
+    // Skip system/subtype noise (joins, channel renames, pins, etc.) — keep plain posts.
+    if (typeof m.subtype === "string" && m.subtype.length > 0) continue;
+    const text = typeof m.text === "string" ? m.text : "";
+    if (!text) continue;
+    const user = typeof m.user === "string" ? m.user : undefined;
+    const botId = typeof m.bot_id === "string" ? m.bot_id : undefined;
+    const ts = (m.ts as string) ?? "";
+    const isMe = (ids.userId !== undefined && user === ids.userId) || (ids.botId !== undefined && botId === ids.botId);
+    if (isMe) lines.push({ senderType: "agent", ts, text });
+    else if (botId) lines.push({ senderType: "bot", senderId: botId, ts, text });
+    else if (user) lines.push({ senderType: "user", senderId: user, ts, text });
+    else lines.push({ senderType: "unknown", ts, text });
+  }
+  return lines;
+}
+
+// The bot's own (user_id, bot_id), resolved once via auth.test (cached). Lets the channel
+// backscroll label the agent's own prior posts as `sender_type=agent` — conversations.history
+// doesn't flag them, so we compare ids. Best-effort: an unresolved identity just means our own
+// posts read as `bot` (still attributed), never a crash.
+let botIdentityCache: Promise<{ userId?: string; botId?: string }> | undefined;
+
+async function botIdentity(ctx: SlackContext): Promise<{ userId?: string; botId?: string }> {
+  if (!botIdentityCache) {
+    botIdentityCache = (async () => {
+      try {
+        const res = await ctx.slack.request("auth.test", {});
+        if (res.ok) {
+          const r = res as unknown as { user_id?: string; bot_id?: string };
+          return { userId: r.user_id, botId: r.bot_id };
+        }
+      } catch {
+        /* fall through to empty */
+      }
+      return {};
+    })();
+  }
+  return botIdentityCache;
+}
+
+/** Reset the cached bot identity (tests only). */
+export function _resetBotIdentityCache(): void {
+  botIdentityCache = undefined;
+}
+
+// Prior messages in the triggering THREAD, bounded since the agent's last reply.
+async function threadContext(ctx: SlackContext, message: SlackMessage): Promise<string[]> {
+  try {
+    const msgs = await loadThreadContextMessages(
+      ctx.thread,
+      { ts: message.ts, threadTs: message.threadTs },
+      { since: "last-agent-reply" },
+    );
+    const lines: ContextLine[] = msgs.map((m) => {
+      // Eve's thread handle already flags the agent's own posts via `isMe`.
+      if (m.isMe) return { senderType: "agent" as const, ts: m.ts, text: m.markdown || m.text };
+      if (m.botId) return { senderType: "bot" as const, senderId: m.botId, ts: m.ts, text: m.markdown || m.text };
+      if (m.user) return { senderType: "user" as const, senderId: m.user, ts: m.ts, text: m.markdown || m.text };
+      return { senderType: "unknown" as const, ts: m.ts, text: m.markdown || m.text };
+    });
+    const entry = renderContext(lines, `slack thread ${message.channelId}/${message.threadTs}`, { readMoreHint: readMoreHint() });
+    return entry ? [entry] : [];
+  } catch {
+    return [];
+  }
+}
+
+// A bounded backscroll of the CHANNEL (top-level mention, no thread). Uses the raw Web API
+// since Eve's thread handle only covers replies. We read strictly older than the mention.
+async function channelBackscroll(ctx: SlackContext, message: SlackMessage): Promise<string[]> {
+  try {
+    const res = await ctx.slack.request("conversations.history", {
+      channel: message.channelId,
+      latest: message.ts,
+      inclusive: false,
+      limit: MAX_MESSAGES,
+    });
+    if (!res.ok || !Array.isArray((res as { messages?: unknown }).messages)) return [];
+    const raw = (res as unknown as { messages: Array<Record<string, unknown>> }).messages;
+    // conversations.history doesn't flag our own posts, so resolve the bot's ids and compare.
+    const { userId: meUser, botId: meBot } = await botIdentity(ctx);
+    const lines = linesFromMessages(raw, { userId: meUser, botId: meBot });
+    // conversations.history returns newest-first; renderContext re-orders to oldest-first.
+    lines.reverse();
+    const entry = renderContext(lines, `slack channel ${message.channelId}`, { readMoreHint: readMoreHint() });
+    return entry ? [entry] : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The surrounding-conversation context for an inbound Slack mention, as `context` strings
+ * for the channel's `SlackMentionResult`. Empty array = nothing to add (or a lookup failed —
+ * always non-fatal). Threaded mention → thread context; channel-root mention → backscroll.
+ */
+export async function loadConversationContext(ctx: SlackContext, message: SlackMessage): Promise<string[]> {
+  // threadTs === ts ⇒ top-level channel message; otherwise a reply inside a thread.
+  return message.threadTs && message.threadTs !== message.ts
+    ? threadContext(ctx, message)
+    : channelBackscroll(ctx, message);
+}