@opengeni/api-router 0.30.1 → 1.0.0

package/src/integrations/slack-bot.ts

@@ -1,12 +1,17 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
 import {
   OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
   OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
   OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
+  OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE,
   evaluateOpenGeniSlackBotScopes,
+  hasOpenGeniSlackFileUploadScope,
+  hasOpenGeniSlackBotSearchScopes,
+  hasOpenGeniSlackReactionScope,
   type AccessGrant,
   type ConnectionMetadata,
+  type OpenGeniSlackBotDisplayName,
   type OpenGeniSlackBotConnectionMetadata,
 } from "@opengeni/contracts";
 import {
@@ -18,14 +23,20 @@ import {
 } from "@opengeni/core";
 import {
   buildConnectionTokenResolver,
+  buildSlackApiRateLimiter,
   claimSlackBotDeleteOperation,
   claimSlackBotPostOperation,
   claimSlackBotUpdateOperation,
   completeSlackBotDeleteOperation,
   completeSlackBotPostOperation,
   completeSlackBotUpdateOperation,
+  getScheduledTask,
   getSession,
+  getSlackBotPostOperation,
   listConnectionsMetadata,
+  prepareScheduledSlackBotMessage,
+  readScheduledSlackBotMessage,
+  ScheduledSlackBotMessageRefusedError,
   markSlackBotDeleteOperationProviderStarted,
   markSlackBotPostOperationProviderStarted,
   recordAuditEvent,
@@ -41,11 +52,14 @@ import {
   type FetchLike,
 } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
+import sharp from "sharp";
 
 const SLACK_API_BASE = "https://slack.com/api/";
 const SLACK_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
 const SLACK_FILE_RESPONSE_MAX_BYTES = 4 * 1024 * 1024;
 export const SLACK_REACTION_IMAGE_MAX_BYTES = 4 * 1024 * 1024;
+// Base64 plus MCP metadata must stay below the runtime's 1 MiB model-result cap.
+export const SLACK_MCP_IMAGE_MAX_BYTES = 640 * 1024;
 const SLACK_FILE_CONTENT_PAGE_CHARS = 50_000;
 const SLACK_TIMEOUT_MS = 10_000;
 const MAX_CHANNEL_PAGE = 200;
@@ -64,6 +78,12 @@ const MAX_REACTION_CONTEXT_CHECKPOINT_FILE_LABEL_CHARS = 1_500;
 const MAX_REACTION_CONTEXT_CHECKPOINT_FILES = 16;
 const SLACK_REACTION_CONTEXT_CHECKPOINT_VERSION = 1;
 const MAX_USER_PAGE = 200;
+/** Slack caps `assistant.search.context` at 20 results per request. */
+const MAX_SEARCH_PAGE = 20;
+/** Bounded projection cap for one search result's content excerpt. */
+const MAX_SEARCH_CONTENT_CHARS = 2_000;
+/** Matches the MCP input schema's cap; Slack signals its own via query_too_long. */
+const MAX_SEARCH_QUERY_CHARS = 500;
 const MAX_FILE_PAGE = 200;
 const MAX_FILE_CURSOR_LENGTH = 1_024;
 const SLACK_FILE_CURSOR_VERSION = "files-v1";
@@ -106,6 +126,11 @@ export type DownloadedSlackReactionImage = Readonly<{
   bytes: Uint8Array;
 }>;
 
+export type ExchangedOpenGeniSlackAuthorization = Readonly<{
+  accessToken: string;
+  appId: string;
+}>;
+
 export async function exchangeOpenGeniSlackAuthorizationCode(
   input: {
     code: string;
@@ -114,7 +139,7 @@ export async function exchangeOpenGeniSlackAuthorizationCode(
     redirectUri: string;
   },
   fetchImpl: FetchLike = fetch,
-): Promise<string> {
+): Promise<ExchangedOpenGeniSlackAuthorization> {
   const body = new URLSearchParams({
     code: input.code,
     client_id: input.clientId,
@@ -158,7 +183,13 @@ export async function exchangeOpenGeniSlackAuthorizationCode(
       message: "Slack installation did not return a bot token",
     });
   }
-  return accessToken;
+  const appId = slackString(record.app_id);
+  if (!appId) {
+    throw new HTTPException(502, {
+      message: "Slack installation did not return an app identity",
+    });
+  }
+  return { accessToken, appId };
 }
 
 export type SlackBotReceipt = {
@@ -188,16 +219,59 @@ export type SlackMessageBlock =
         style?: "primary" | "danger";
       }>;
     }
+  | {
+      type: "context";
+      block_id?: string;
+      elements: Array<{ type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean }>;
+    }
+  | { type: "divider" };
+
+export type SlackHomeBlock =
+  | {
+      type: "header";
+      block_id?: string;
+      text: { type: "plain_text"; text: string; emoji?: boolean };
+    }
+  | {
+      type: "section";
+      block_id?: string;
+      text: { type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean };
+      accessory?: {
+        type: "button";
+        action_id: string;
+        text: { type: "plain_text"; text: string; emoji?: boolean };
+        url: string;
+      };
+    }
+  | {
+      type: "context";
+      block_id?: string;
+      elements: Array<{ type: "mrkdwn" | "plain_text"; text: string; emoji?: boolean }>;
+    }
+  | {
+      type: "actions";
+      block_id: string;
+      elements: Array<{
+        type: "button";
+        action_id: string;
+        text: { type: "plain_text"; text: string; emoji?: boolean };
+        url: string;
+        style?: "primary" | "danger";
+      }>;
+    }
   | { type: "divider" };
 
 type SlackBotOperation =
   | "channels.list"
+  | "search.context"
   | "channel_history.read"
   | "thread_replies.read"
   | "users.list"
   | "files.list"
   | "file.info"
   | "file.content.read"
+  | "file.upload"
+  | "home.publish"
   | "message.post"
   | "message.update"
   | "message.delete";
@@ -210,6 +284,9 @@ type SlackBotContext = {
   scheduledTaskId?: string | null;
 };
 
+type SlackCallAuthority = Readonly<{ operation: SlackBotOperation }>;
+type SlackProviderAuthorization = () => Promise<boolean | void>;
+
 export type SlackReactionContextCheckpointBinding = {
   inboxId: string;
   accountId: string;
@@ -259,6 +336,95 @@ export class SlackBotProviderError extends Error {
   }
 }
 
+export function slackHistoryRateLimited(error: unknown): error is SlackBotProviderError {
+  return (
+    error instanceof SlackBotProviderError &&
+    (error.code === "http_429" || error.code === "rate_limited" || error.code === "ratelimited")
+  );
+}
+
+/**
+ * The post or update ledger already binds this operation id to different
+ * request bytes. Raised from the durable claim, before any Slack write, so a
+ * caller that knows an earlier release wrote other bytes for the same operation
+ * may retry once with those bytes.
+ */
+export class SlackBotOperationConflictError extends Error {
+  constructor(kind: "post" | "update" | "delete") {
+    super(`operationId is already bound to a different Slack ${kind} request`);
+    this.name = "SlackBotOperationConflictError";
+  }
+}
+
+/** Only Slack's one-time HTTPS upload endpoint may receive retained bytes. */
+export function slackFileUploadUrl(value: string): URL {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new SlackBotProviderError("invalid_upload_url");
+  }
+  if (
+    value.length > 4096 ||
+    url.protocol !== "https:" ||
+    url.hostname !== "files.slack.com" ||
+    url.port !== "" ||
+    url.username ||
+    url.password ||
+    url.hash ||
+    !url.pathname.startsWith("/upload/v1/")
+  ) {
+    throw new SlackBotProviderError("invalid_upload_url");
+  }
+  return url;
+}
+
+/** A channel listing alone is not proof of delivery to the requested thread. */
+export function slackFileSharedToThread(
+  value: unknown,
+  input: { fileId: string; channelId: string; threadTimestamp: string; botUserId: string },
+): boolean {
+  const file = slackRecord(value);
+  if (file?.id !== input.fileId || file.user !== input.botUserId) return false;
+  const shares = slackRecord(file.shares);
+  return ["public", "private"].some((kind) => {
+    const entries = slackRecord(shares?.[kind])?.[input.channelId];
+    return (
+      Array.isArray(entries) &&
+      entries.some((entry) => slackRecord(entry)?.thread_ts === input.threadTimestamp)
+    );
+  });
+}
+
+export async function authorizeSlackSharedImageRead(
+  channel: {
+    isArchived: boolean;
+    isShared: boolean;
+    isExternallyShared: boolean;
+    isOrgShared: boolean;
+    isPendingExternallyShared: boolean;
+    isMpim: boolean;
+  },
+  authorizeSharedRead: (() => Promise<void>) | undefined,
+): Promise<void> {
+  if (channel.isArchived) {
+    throw new SlackBotProviderError("is_archived");
+  }
+  if (
+    !channel.isShared &&
+    !channel.isExternallyShared &&
+    !channel.isOrgShared &&
+    !channel.isPendingExternallyShared &&
+    !channel.isMpim
+  ) {
+    throw new SlackBotProviderError("slack_connect_unsupported");
+  }
+  if (!authorizeSharedRead) {
+    throw new SlackBotProviderError("slack_connect_unsupported");
+  }
+  await authorizeSharedRead();
+}
+
 const SLACK_CREDENTIAL_REJECTION_CODES = new Set([
   "account_inactive",
   "invalid_auth",
@@ -285,12 +451,16 @@ export class SlackBotCredentialVerificationError extends HTTPException {
 
 /**
  * Validates a write-only xoxb credential before it can enter encrypted storage.
- * Slack does not expose the app's display_information name to this scope set;
- * users.info provides the authoritative installed bot display name, while the
- * documented manifest fixes the app name itself to the same exact value.
+ * The OAuth exchange's app_id is the immutable app authority. Slack bot profile
+ * names are mutable presentation data and may lag manifest/App Home changes, so
+ * they must not decide whether a credential belongs to this installation.
  */
 export async function verifyOpenGeniSlackBotCredential(
   token: string,
+  expected: Readonly<{
+    appId: string;
+    displayName: OpenGeniSlackBotDisplayName;
+  }>,
   fetchImpl: FetchLike = fetch,
   now: Date = new Date(),
 ): Promise<VerifiedOpenGeniSlackBot> {
@@ -314,11 +484,11 @@ export async function verifyOpenGeniSlackBotCredential(
     );
   }
   const profile = slackRecord(user.profile);
-  const displayName = slackString(profile?.display_name) || slackString(profile?.real_name);
-  if (displayName !== "OpenGeni") {
+  const installedAppId = slackString(profile?.api_app_id);
+  if (installedAppId !== expected.appId) {
     throw new SlackBotCredentialVerificationError(
       "identity_mismatch",
-      'Slack bot display name must be exactly "OpenGeni"',
+      "Slack credential does not belong to the authorized Slack app",
     );
   }
 
@@ -331,7 +501,7 @@ export async function verifyOpenGeniSlackBotCredential(
       slackTeamName,
       botUserId,
       botId,
-      botDisplayName: "OpenGeni",
+      botDisplayName: expected.displayName,
       verifiedAt: now.toISOString(),
     },
   };
@@ -355,17 +525,17 @@ export async function resolveSlackBotConnectionForTool(input: {
   }
   const boundConnectionId = scheduledSlackBotConnectionId(session?.metadata);
   if (boundConnectionId && (!session || !isTrustedScheduledSlackBotSession(session))) {
-    throw new Error("OpenGeni Slack bot routing metadata is not scheduler-authorized");
+    throw new Error("Opengeni Slack bot routing metadata is not scheduler-authorized");
   }
   if (
     boundConnectionId &&
     input.requestedConnectionId &&
     input.requestedConnectionId !== boundConnectionId
   ) {
-    throw new Error("this scheduled session is bound to a different OpenGeni Slack bot connection");
+    throw new Error("this scheduled session is bound to a different Opengeni Slack bot connection");
   }
   if (!boundConnectionId && !input.grant.permissions.includes("connections:read")) {
-    throw new Error("connections:read is required to select an OpenGeni Slack bot connection");
+    throw new Error("connections:read is required to select an Opengeni Slack bot connection");
   }
   let connectionId = boundConnectionId ?? input.requestedConnectionId;
   if (!connectionId) {
@@ -375,7 +545,7 @@ export async function resolveSlackBotConnectionForTool(input: {
       (connection) => connection.status === "active" && isOpenGeniSlackBotConnection(connection),
     );
     if (activeConnections.length === 0) {
-      throw new Error("no active OpenGeni Slack bot connection is installed in this workspace");
+      throw new Error("no active Opengeni Slack bot connection is installed in this workspace");
     }
     if (activeConnections.length > 1) {
       const principals = new Set(
@@ -386,7 +556,7 @@ export async function resolveSlackBotConnectionForTool(input: {
       );
       if (principals.size > 1) {
         throw new Error(
-          "connectionId is required because this workspace has multiple active OpenGeni Slack bot connections",
+          "connectionId is required because this workspace has multiple active Opengeni Slack bot connections",
         );
       }
     }
@@ -399,7 +569,7 @@ export async function resolveSlackBotConnectionForTool(input: {
   );
   const metadata = openGeniSlackBotMetadata(connection.metadata);
   if (!metadata) {
-    throw new Error("OpenGeni Slack bot connection metadata is invalid");
+    throw new Error("Opengeni Slack bot connection metadata is invalid");
   }
   return {
     connection,
@@ -417,8 +587,209 @@ export async function resolveSlackBotConnectionForTool(input: {
   };
 }
 
+/**
+ * The one destination a scheduled run may post to as the OpenGeni bot: the
+ * channel a person chose on the task, through the bot connection frozen on the
+ * run's session. The agent never supplies a channel. Every call re-reads the
+ * task, so a person clearing or changing the channel takes effect at once.
+ */
+export async function resolveScheduledSlackBotPostTarget(input: {
+  db: Database;
+  grant: AccessGrant;
+  sessionId: string | null;
+}): Promise<
+  Awaited<ReturnType<typeof resolveSlackBotConnectionForTool>> & {
+    scheduledTaskId: string;
+    channelId: string;
+  }
+> {
+  const refuse = (reason: string): never => {
+    throw new Error(`Posting to the task's Slack channel is unavailable: ${reason}`);
+  };
+  if (!input.sessionId) refuse("this is not a scheduled task run");
+  const session = await getSession(input.db, input.grant.workspaceId, input.sessionId!);
+  if (!session || !isTrustedScheduledSlackBotSession(session)) {
+    refuse("this is not a scheduled task run with an Opengeni Slack bot");
+  }
+  const connectionId = scheduledSlackBotConnectionId(session!.metadata)!;
+  const scheduledTaskId = String(session!.metadata.scheduledTaskId);
+  const task = await getScheduledTask(input.db, input.grant.workspaceId, scheduledTaskId);
+  if (!task) refuse("the scheduled task was deleted");
+  if (task!.runMode === "existing_session") refuse("the task continues an existing chat");
+  if (task!.agentConfig.slackBotConnectionId !== connectionId) {
+    refuse("the task no longer uses this Opengeni Slack bot");
+  }
+  const channelId = task!.agentConfig.slackBotChannelId;
+  if (!channelId) refuse("no one has chosen a Slack channel for this task");
+  const resolved = await resolveSlackBotConnectionForTool({
+    db: input.db,
+    grant: input.grant,
+    sessionId: input.sessionId,
+    requestedConnectionId: connectionId,
+  });
+  return { ...resolved, scheduledTaskId, channelId: channelId! };
+}
+
+/**
+ * Save one message for the task's channel without sending it. The returned id
+ * is server-owned and becomes the Slack post operation id, so retrying the
+ * send can never post the same message twice.
+ */
+export async function prepareScheduledSlackBotPost(input: {
+  db: Database;
+  grant: AccessGrant;
+  sessionId: string | null;
+  text: string;
+  threadTimestamp?: string | undefined;
+}) {
+  const target = await resolveScheduledSlackBotPostTarget(input);
+  const message = await prepareScheduledSlackBotMessage(input.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.grant.workspaceId,
+    sessionId: input.sessionId!,
+    scheduledTaskId: target.scheduledTaskId,
+    connectionId: target.connection.id,
+    connectionVersion: target.connection.version,
+    channelId: target.channelId,
+    threadTimestamp: input.threadTimestamp ?? null,
+    text: input.text,
+  }).catch((error: unknown) => {
+    if (error instanceof ScheduledSlackBotMessageRefusedError) {
+      throw new Error(`Posting to the task's Slack channel is unavailable: ${error.message}`);
+    }
+    throw error;
+  });
+  return {
+    messageId: message.id,
+    identity: "workspace_bot" as const,
+    channelId: message.channelId,
+    threadTimestamp: message.threadTimestamp,
+    text: message.text,
+    sent: false,
+  };
+}
+
+/**
+ * Send a message this run prepared, exactly as saved. The destination must
+ * still be the task's channel and the bot connection unchanged; otherwise the
+ * send is refused rather than redirected.
+ */
+export async function sendScheduledSlackBotPost(input: {
+  db: Database;
+  settings: Settings;
+  grant: AccessGrant;
+  sessionId: string | null;
+  messageId: string;
+  slackFetch?: typeof fetch;
+  authorizeProviderRequest?: SlackProviderAuthorization;
+}) {
+  const target = await resolveScheduledSlackBotPostTarget(input);
+  const message = await readScheduledSlackBotMessage(input.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.grant.workspaceId,
+    sessionId: input.sessionId!,
+    id: input.messageId,
+  });
+  if (!message) {
+    throw new Error("This prepared Slack message does not exist in this chat");
+  }
+  const channelChanged =
+    message.channelId !== target.channelId || message.scheduledTaskId !== target.scheduledTaskId;
+  const botChanged =
+    message.connectionId !== target.connection.id ||
+    message.connectionVersion !== target.connection.version;
+  const client = createOpenGeniSlackBotClient(
+    {
+      db: input.db,
+      settings: input.settings,
+      ...(input.slackFetch ? { slackFetch: input.slackFetch } : {}),
+      ...(input.authorizeProviderRequest
+        ? { authorizeProviderRequest: input.authorizeProviderRequest }
+        : {}),
+    },
+    target,
+  );
+  const post = () =>
+    client.postMessage({
+      operationId: message.id,
+      channelId: message.channelId,
+      ...(message.threadTimestamp ? { threadTimestamp: message.threadTimestamp } : {}),
+      text: message.text,
+      requireActiveNonSharedChannel: true,
+    });
+  if (!channelChanged && !botChanged) return await post();
+  // The destination moved after this message was prepared, so it is never sent
+  // now. Say truthfully whether an earlier send already reached Slack, so the
+  // agent does not post the same content again believing nothing was sent.
+  const earlier = await getSlackBotPostOperation(
+    input.db,
+    input.grant.workspaceId,
+    message.connectionId,
+    message.id,
+  );
+  if (earlier?.status === "completed" && message.connectionId === target.connection.id) {
+    // Replays the recorded result from the post ledger; no Slack call is made.
+    return await post();
+  }
+  const reason = channelChanged
+    ? "The task's Slack channel changed after this message was prepared"
+    : "The Opengeni Slack bot changed after this message was prepared";
+  if (earlier?.status === "completed") {
+    throw new Error(`${reason}. It had already been posted, so it was not sent again.`);
+  }
+  if (earlier && earlier.status !== "pending") {
+    throw new Error(
+      `${reason}. An earlier send was interrupted, so it may already have been posted to the previous channel; it was not sent again.`,
+    );
+  }
+  throw new Error(`${reason}, so it was not sent. Prepare a new message for the current channel.`);
+}
+
+/**
+ * Check, with the bot's token, that a person's chosen task channel is one the
+ * bot is a member of, active, and not shared with another organization.
+ */
+export async function verifyScheduledTaskSlackChannel(
+  deps: { db: Database; settings: Settings; slackFetch?: typeof fetch },
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    channelId: string;
+  },
+): Promise<void> {
+  const client = await createOpenGeniSlackBotInteractionClient(deps, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    connectionId: input.connectionId,
+    subjectId: input.subjectId,
+  });
+  let channel: Awaited<ReturnType<OpenGeniSlackBotClient["verifyChannelAccess"]>>;
+  try {
+    channel = await client.verifyChannelAccess(input.channelId);
+  } catch (error) {
+    throw new HTTPException(422, {
+      message: `The Opengeni bot cannot post in that Slack channel. Invite it to the channel first. (${safeFailureCode(error)})`,
+    });
+  }
+  if (
+    channel.isDirectMessage ||
+    channel.isArchived ||
+    channel.isShared ||
+    channel.isExternallyShared ||
+    channel.isOrgShared
+  ) {
+    throw new HTTPException(422, {
+      message:
+        "Scheduled posts need an active Slack channel that is not shared with another organization",
+    });
+  }
+}
+
 export class OpenGeniSlackBotClient {
   private readonly resolveCredential: ReturnType<typeof buildConnectionTokenResolver>;
+  private readonly rateLimit: ReturnType<typeof buildSlackApiRateLimiter>;
 
   constructor(
     private readonly db: Database,
@@ -427,8 +798,20 @@ export class OpenGeniSlackBotClient {
     private readonly metadata: OpenGeniSlackBotConnectionMetadata,
     private readonly context: SlackBotContext,
     private readonly fetchImpl: FetchLike = fetch,
+    private readonly authorizeProviderRequest?: SlackProviderAuthorization,
   ) {
     this.resolveCredential = buildConnectionTokenResolver(db, settings);
+    this.rateLimit = buildSlackApiRateLimiter(db, settings);
+  }
+
+  private historyPageLimit(approvedLimit: number): number {
+    return this.settings.slackAccessMode === "full" ? approvedLimit : 15;
+  }
+
+  private postReconciliationPageLimit(): number {
+    // Ambiguous writes stay unknown when the one bounded pilot page cannot
+    // prove the provider identity. Never crawl or resend an unknown message.
+    return this.settings.slackAccessMode === "full" ? MAX_SLACK_POST_RECONCILIATION_PAGES : 1;
   }
 
   async listChannels(input: { limit?: number; cursor?: string } = {}) {
@@ -453,6 +836,159 @@ export class OpenGeniSlackBotClient {
     return await this.requireMemberChannel(headers, channelId);
   }
 
+  /** Server-only upload preparation; the temporary URL never enters a tool result. */
+  async allocateFileUpload(input: {
+    channelId: string;
+    privateRecipientSlackUserId?: string;
+    filename: string;
+    sizeBytes: number;
+  }) {
+    this.requireFileUploadScope();
+    return this.withAudit("file.upload", async (authority) => {
+      await this.requireActiveNonSharedMemberChannel(
+        authority,
+        input.channelId,
+        input.privateRecipientSlackUserId,
+      );
+      const payload = await this.call(authority, "files.getUploadURLExternal", {
+        filename: input.filename,
+        length: String(input.sizeBytes),
+      });
+      const fileId = slackString(payload.file_id);
+      const uploadUrl = slackString(payload.upload_url);
+      if (!fileId || !/^F[A-Z0-9]{1,63}$/.test(fileId) || !uploadUrl) {
+        throw new SlackBotProviderError("invalid_upload_response");
+      }
+      return { fileId, uploadUrl: slackFileUploadUrl(uploadUrl) };
+    });
+  }
+
+  async transferFileUpload(input: {
+    channelId: string;
+    privateRecipientSlackUserId?: string;
+    uploadUrl: URL;
+    bytes: Uint8Array;
+  }) {
+    this.requireFileUploadScope();
+    const uploadUrl = slackFileUploadUrl(input.uploadUrl.toString());
+    return this.withAudit("file.upload", async (authority) => {
+      await this.requireActiveNonSharedMemberChannel(
+        authority,
+        input.channelId,
+        input.privateRecipientSlackUserId,
+      );
+      // Reauthorize this exact destination and live attempt immediately before
+      // I/O, but do NOT forward the bot token to Slack's temporary upload URL.
+      await this.headersForDestination("file.upload", uploadUrl.toString());
+      let response: Response;
+      try {
+        response = await this.fetchImpl(uploadUrl, {
+          method: "POST",
+          headers: { "content-type": "application/octet-stream" },
+          body: Buffer.from(input.bytes),
+          redirect: "error",
+          signal: AbortSignal.timeout(30_000),
+        });
+      } catch {
+        throw new SlackBotProviderError("upload_transport_error");
+      }
+      await response.body?.cancel().catch(() => undefined);
+      if (!response.ok) {
+        throw new SlackBotProviderError(
+          `upload_http_${response.status}`,
+          slackRetryAfterMs(response),
+        );
+      }
+      return { uploaded: true };
+    });
+  }
+
+  async completeFileUpload(input: {
+    channelId: string;
+    privateRecipientSlackUserId?: string;
+    threadTimestamp: string;
+    fileId: string;
+    title: string;
+  }) {
+    this.requireFileUploadScope();
+    return this.withAudit("file.upload", async (authority) => {
+      await this.requireActiveNonSharedMemberChannel(
+        authority,
+        input.channelId,
+        input.privateRecipientSlackUserId,
+      );
+      const payload = await this.call(authority, "files.completeUploadExternal", {
+        files: JSON.stringify([{ id: input.fileId, title: input.title }]),
+        channel_id: input.channelId,
+        thread_ts: input.threadTimestamp,
+      });
+      if (
+        !Array.isArray(payload.files) ||
+        !payload.files.some((file) => slackRecord(file)?.id === input.fileId)
+      ) {
+        throw new SlackBotProviderError("invalid_upload_completion_response");
+      }
+      return { fileId: input.fileId };
+    });
+  }
+
+  async reconcileFileUpload(input: {
+    channelId: string;
+    privateRecipientSlackUserId?: string;
+    threadTimestamp: string;
+    fileId: string;
+  }) {
+    this.requireFileUploadScope();
+    return this.withAudit("file.upload", async (authority) => {
+      await this.requireActiveNonSharedMemberChannel(
+        authority,
+        input.channelId,
+        input.privateRecipientSlackUserId,
+      );
+      let payload: SlackPayload;
+      try {
+        payload = await this.call(authority, "files.info", { file: input.fileId });
+      } catch (error) {
+        if (error instanceof SlackBotProviderError && error.code === "file_not_found")
+          return { shared: false };
+        throw error;
+      }
+      return {
+        shared: slackFileSharedToThread(payload.file, {
+          ...input,
+          botUserId: this.metadata.botUserId,
+        }),
+      };
+    });
+  }
+
+  private requireFileUploadScope() {
+    if (!hasOpenGeniSlackFileUploadScope(this.connection.grantedScopes)) {
+      throw new SlackBotProviderError("slack_bot_file_upload_scope_missing");
+    }
+  }
+
+  /**
+   * Replace one Slack user's private App Home view. `views.publish` is a
+   * naturally convergent replace operation: Slack event retries may safely
+   * repeat the exact bounded view without creating duplicate provider state.
+   */
+  async publishHomeView(input: { userId: string; blocks: SlackHomeBlock[]; hash?: string | null }) {
+    const userId = requiredSlackString(input.userId, "user_id");
+    const blocks = validateSlackHomeBlocks(input.blocks);
+    const hash = input.hash ? requiredSlackString(input.hash, "hash") : null;
+    return await this.withAudit("home.publish", async (headers) => {
+      const payload = await this.call(headers, "views.publish", {
+        user_id: userId,
+        view: JSON.stringify({ type: "home", blocks }),
+        ...(hash ? { hash } : {}),
+      });
+      return {
+        viewId: requiredSlackString(slackRecord(payload.view)?.id, "view.id"),
+      };
+    });
+  }
+
   async slackTaskPolicyFacts(channelId: string, userId: string) {
     return await this.withAudit("channel_history.read", async (headers) => {
       const conversation = await this.requireMemberChannel(headers, channelId);
@@ -485,7 +1021,13 @@ export class OpenGeniSlackBotClient {
       await input.authorizeRead?.();
       const payload = await this.call(headers, "conversations.history", {
         channel: input.channelId,
-        limit: String(boundedInt(input.limit, MAX_HISTORY_PAGE, 50)),
+        limit: String(
+          boundedInt(
+            input.limit,
+            this.historyPageLimit(MAX_HISTORY_PAGE),
+            this.historyPageLimit(50),
+          ),
+        ),
         ...(input.cursor ? { cursor: input.cursor } : {}),
         ...(input.latest ? { latest: input.latest } : {}),
         ...(input.latest && input.inclusive ? { inclusive: "true" } : {}),
@@ -514,7 +1056,13 @@ export class OpenGeniSlackBotClient {
       const payload = await this.call(headers, "conversations.replies", {
         channel: input.channelId,
         ts: input.threadTimestamp,
-        limit: String(boundedInt(input.limit, MAX_THREAD_PAGE, 50)),
+        limit: String(
+          boundedInt(
+            input.limit,
+            this.historyPageLimit(MAX_THREAD_PAGE),
+            this.historyPageLimit(50),
+          ),
+        ),
         ...(input.cursor ? { cursor: input.cursor } : {}),
         ...(input.oldest ? { oldest: input.oldest } : {}),
         ...(input.latest ? { latest: input.latest } : {}),
@@ -534,7 +1082,6 @@ export class OpenGeniSlackBotClient {
     messageTimestamp: string;
     checkpoint: unknown | null;
     checkpointBinding: SlackReactionContextCheckpointBinding;
-    saveCheckpoint: (checkpoint: SlackReactionContextCheckpoint) => Promise<void>;
   }) {
     return await this.withAudit("thread_replies.read", async (headers) => {
       const checkpointKey = environmentsEncryptionKeyBytes(this.settings);
@@ -547,84 +1094,61 @@ export class OpenGeniSlackBotClient {
         input.channelId,
         input.messageTimestamp,
       );
-      const restored = input.checkpoint
-        ? parseSlackReactionContextCheckpoint(
-            input.checkpoint,
-            input.checkpointBinding,
-            checkpointKey,
-          )
-        : null;
+      // Validate historical inbox checkpoints, but never use retained context as
+      // current provider truth or continue the old full-thread scan.
+      if (input.checkpoint) {
+        parseSlackReactionContextCheckpoint(
+          input.checkpoint,
+          input.checkpointBinding,
+          checkpointKey,
+        );
+      }
       const info = await this.requireMemberChannel(headers, input.channelId);
       if (info.isShared || info.isExternallyShared || info.isOrgShared) {
         throw new SlackBotProviderError("slack_connect_unsupported");
       }
-      const messages: ReturnType<typeof projectMessage>[] = restored
-        ? restored.state.messages.map(projectSlackReactionCheckpointMessage)
-        : [];
-      const seenMessageTimestamps = new Set(restored?.state.seenMessageTimestamps ?? []);
-      const seenCursors = new Set(restored?.state.seenCursors ?? []);
-      let cursor: string | null = restored?.state.nextCursor ?? null;
-      let nextCursor: string | null = cursor;
-      let threadTimestamp: string | null = restored?.state.threadTimestamp ?? null;
-      let reactedMessage: ReturnType<typeof projectMessage> | null = null;
-      const checkpointCreatedAtMs = restored?.state.createdAtMs ?? Date.now();
-      const firstPage = restored?.state.pageCount ?? 0;
-
-      for (let page = firstPage; page < MAX_REACTION_CONTEXT_PAGES; page += 1) {
+      if (!hasOpenGeniSlackReactionScope(this.connection.grantedScopes)) {
+        throw new SlackBotProviderError("slack_bot_reaction_scope_missing");
+      }
+      // This method is used only for a validated reaction summon. reactions.get
+      // supplies that exact reacted message even when it is far into a thread;
+      // it is not an alternate transport for arbitrary conversation history.
+      const reacted = await this.call(headers, "reactions.get", {
+        channel: input.channelId,
+        timestamp: input.messageTimestamp,
+        full: "true",
+      });
+      if (reacted.type !== "message" || reacted.channel !== input.channelId) {
+        throw new SlackBotProviderError("message_not_found");
+      }
+      const reactedMessage = projectMessage(reacted.message);
+      if (reactedMessage.timestamp !== input.messageTimestamp) {
+        throw new SlackBotProviderError("message_not_found");
+      }
+      const threadTimestamp = reactedMessage.threadTimestamp || reactedMessage.timestamp;
+      let messages = [reactedMessage];
+      let nextCursor: string | null = null;
+      let contextUnavailable = false;
+      try {
         const payload = await this.call(headers, "conversations.replies", {
           channel: input.channelId,
-          // Slack accepts either the parent timestamp or a message timestamp from
-          // inside the thread and returns the containing thread.
-          ts: input.messageTimestamp,
+          ts: threadTimestamp,
+          latest: reactedMessage.timestamp,
+          inclusive: "true",
           limit: String(MAX_REACTION_CONTEXT_MESSAGES),
-          ...(cursor ? { cursor } : {}),
         });
         const pageMessages = slackArray(payload.messages)
           .map(projectMessage)
           .filter((message) => message.timestamp.length > 0);
-        const first = pageMessages[0];
-        threadTimestamp ??= first?.threadTimestamp || first?.timestamp || null;
-        for (const message of pageMessages) {
-          if (seenMessageTimestamps.has(message.timestamp)) continue;
-          seenMessageTimestamps.add(message.timestamp);
-          messages.push(message);
-        }
-        reactedMessage =
-          reactedMessage ??
-          pageMessages.find((message) => message.timestamp === input.messageTimestamp) ??
-          null;
+        // Fresh exact message content wins over any duplicate context entry.
+        messages = [
+          ...pageMessages.filter((message) => message.timestamp !== reactedMessage.timestamp),
+          reactedMessage,
+        ];
         nextCursor = responseCursor(payload);
-        if (reactedMessage || !nextCursor) break;
-        if (seenCursors.has(nextCursor)) {
-          throw new SlackBotProviderError("reaction_pagination_invalid");
-        }
-        seenCursors.add(nextCursor);
-        const pageCount = page + 1;
-        if (pageCount >= MAX_REACTION_CONTEXT_PAGES) {
-          throw new SlackBotProviderError("reaction_pagination_exhausted");
-        }
-        const retainedMessages = selectSlackReactionCheckpointMessages(messages);
-        messages.splice(0, messages.length, ...retainedMessages);
-        await input.saveCheckpoint(
-          createSlackReactionContextCheckpoint(
-            input.checkpointBinding,
-            {
-              createdAtMs: checkpointCreatedAtMs,
-              pageCount,
-              nextCursor,
-              seenCursors: [...seenCursors],
-              seenMessageTimestamps: [...seenMessageTimestamps],
-              threadTimestamp,
-              messages: retainedMessages.map(slackReactionCheckpointMessage),
-            },
-            checkpointKey,
-          ),
-        );
-        cursor = nextCursor;
-      }
-
-      if (!reactedMessage || !threadTimestamp) {
-        throw new SlackBotProviderError("message_not_found");
+      } catch (error) {
+        if (!slackHistoryRateLimited(error)) throw error;
+        contextUnavailable = true;
       }
       const boundedMessages = selectSlackReactionContextMessages(
         messages,
@@ -635,7 +1159,9 @@ export class OpenGeniSlackBotClient {
         threadTimestamp,
         reactedMessage,
         messages: boundedMessages,
-        truncated: nextCursor !== null || seenMessageTimestamps.size > boundedMessages.length,
+        truncated:
+          contextUnavailable || nextCursor !== null || messages.length > boundedMessages.length,
+        ...(contextUnavailable ? { contextUnavailable: true } : {}),
       };
     });
   }
@@ -649,11 +1175,18 @@ export class OpenGeniSlackBotClient {
   async prepareReactionImageDownloads(input: {
     channelId: string;
     files: readonly { id: string; name: string; title: string }[];
+    authorizeSharedRead?: () => Promise<void>;
   }): Promise<PreparedSlackReactionImage[]> {
     const result = await this.withAudit("file.content.read", async (headers) => {
-      await this.requireActiveNonSharedMemberChannel(headers, input.channelId);
+      if (input.authorizeSharedRead) {
+        const channel = await this.requireMemberChannel(headers, input.channelId);
+        await authorizeSlackSharedImageRead(channel, input.authorizeSharedRead);
+      } else {
+        await this.requireActiveNonSharedMemberChannel(headers, input.channelId);
+      }
       const prepared: PreparedSlackReactionImage[] = [];
       for (const candidate of input.files) {
+        await input.authorizeSharedRead?.();
         const payload = await this.call(headers, "files.info", { file: candidate.id });
         const fileRecord = slackRecord(payload.file);
         const file = projectFile(fileRecord);
@@ -688,6 +1221,7 @@ export class OpenGeniSlackBotClient {
   /** Download and fully validate one previously authorized Slack image. */
   async downloadReactionImage(
     input: PreparedSlackReactionImage,
+    authorizeSharedRead?: () => Promise<void>,
   ): Promise<DownloadedSlackReactionImage> {
     return await this.withAudit("file.content.read", async () => {
       if (!SLACK_REACTION_IMAGE_MIME_TYPES.has(input.declaredMimeType)) {
@@ -700,7 +1234,11 @@ export class OpenGeniSlackBotClient {
       ) {
         throw new SlackBotProviderError("invalid_file_size");
       }
-      const response = await this.fetchPrivateFile(input.downloadUrl, "file.content.read");
+      const response = await this.fetchPrivateFile(
+        input.downloadUrl,
+        "file.content.read",
+        authorizeSharedRead,
+      );
       const responseContentType = normalizedContentType(response.headers.get("content-type"));
       if (!SLACK_REACTION_IMAGE_MIME_TYPES.has(responseContentType)) {
         await response.body?.cancel().catch(() => undefined);
@@ -748,6 +1286,79 @@ export class OpenGeniSlackBotClient {
     });
   }
 
+  /**
+   * Public search in a trusted Slack interaction through Real-time Search
+   * (`assistant.search.context`) under the bot identity. Unlisted deployments
+   * cannot use this API; approved deployments also need Slack's action token.
+   *
+   * The bot never carries private-search authority: `channel_types` is pinned
+   * to `public_channel` server-side regardless of caller input, so private
+   * channels, DMs, and MPIMs remain reachable only through a member's personal
+   * hosted-MCP grant. An install predating the search scopes fails closed with
+   * a reinstall hint instead of leaking Slack's `missing_scope` error.
+   */
+  async searchContext(input: {
+    query: string;
+    /** Server-owned Slack interaction token, never an agent tool argument. */
+    actionToken?: string;
+    contentTypes?: readonly ("messages" | "files" | "channels")[];
+    includeBots?: boolean;
+    /** UNIX seconds bounds on message timestamps. */
+    before?: number;
+    after?: number;
+    sort?: "score" | "timestamp";
+    sortDir?: "asc" | "desc";
+    cursor?: string;
+    limit?: number;
+  }) {
+    const query = typeof input.query === "string" ? input.query.trim() : "";
+    if (!query || query.length > MAX_SEARCH_QUERY_CHARS) {
+      throw new SlackBotProviderError("invalid_query");
+    }
+    const contentTypes = input.contentTypes?.length
+      ? [...new Set(input.contentTypes)]
+      : ["messages"];
+    return await this.withAudit("search.context", async (headers) => {
+      if (this.settings.slackAccessMode !== "full") {
+        throw new SlackBotProviderError("slack_bot_search_unavailable");
+      }
+      if (!input.actionToken) {
+        throw new SlackBotProviderError("slack_bot_search_action_required");
+      }
+      // Inside the audit boundary so a fail-closed denial on a legacy install
+      // leaves the same `failed` evidence as a provider rejection.
+      if (!hasOpenGeniSlackBotSearchScopes(this.connection.grantedScopes)) {
+        throw new SlackBotProviderError("slack_bot_search_scopes_missing");
+      }
+      const payload = await this.call(headers, "assistant.search.context", {
+        query,
+        action_token: input.actionToken,
+        channel_types: "public_channel",
+        content_types: contentTypes.join(","),
+        ...(input.includeBots ? { include_bots: "true" } : {}),
+        ...(input.before !== undefined ? { before: String(Math.trunc(input.before)) } : {}),
+        ...(input.after !== undefined ? { after: String(Math.trunc(input.after)) } : {}),
+        ...(input.sort ? { sort: input.sort } : {}),
+        ...(input.sortDir ? { sort_dir: input.sortDir } : {}),
+        ...(input.cursor ? { cursor: input.cursor } : {}),
+        limit: String(boundedInt(input.limit, MAX_SEARCH_PAGE, MAX_SEARCH_PAGE)),
+      });
+      const results = slackRecord(payload.results);
+      return {
+        messages: slackArray(results?.messages)
+          .map(projectSearchMessage)
+          .filter((message): message is NonNullable<typeof message> => message !== null),
+        files: slackArray(results?.files)
+          .map(projectSearchFile)
+          .filter((file): file is NonNullable<typeof file> => file !== null),
+        channels: slackArray(results?.channels)
+          .map(projectSearchChannel)
+          .filter((channel): channel is NonNullable<typeof channel> => channel !== null),
+        nextCursor: responseCursor(payload),
+      };
+    });
+  }
+
   async listFiles(input: { channelId: string; limit?: number; cursor?: string }) {
     return await this.withAudit("files.list", async (headers) => {
       const requestedPage = this.fileListPage(input);
@@ -797,6 +1408,35 @@ export class OpenGeniSlackBotClient {
         "file.content.read",
         input,
       );
+      if (SLACK_REACTION_IMAGE_MIME_TYPES.has(normalizedContentType(file.mimetype))) {
+        if (input.offset !== undefined && input.offset !== 0) {
+          throw new SlackBotProviderError("invalid_file_offset");
+        }
+        // A context file is read only on explicit request. Keep the same
+        // non-shared channel boundary and byte validation as invocation images.
+        await this.requireActiveNonSharedMemberChannel(headers, input.channelId);
+        if (!fileIsSharedToChannel(fileRecord, input.channelId)) {
+          throw new SlackBotProviderError("file_not_shared_to_channel");
+        }
+        if (file.size !== null && (file.size < 1 || file.size > SLACK_REACTION_IMAGE_MAX_BYTES)) {
+          throw new SlackBotProviderError("invalid_file_size");
+        }
+        if (file.size !== null && file.size > SLACK_MCP_IMAGE_MAX_BYTES) {
+          throw new SlackBotProviderError("image_result_too_large");
+        }
+        const image = await this.downloadReactionImage({
+          fileId: file.id,
+          filename: file.name || file.title || file.id,
+          declaredMimeType: normalizedContentType(file.mimetype),
+          declaredSizeBytes: file.size,
+          downloadUrl: privateSlackFileUrl(fileRecord),
+        });
+        if (image.bytes.byteLength > SLACK_MCP_IMAGE_MAX_BYTES) {
+          throw new SlackBotProviderError("image_result_too_large");
+        }
+        await validateSlackMcpImage(image.bytes);
+        return { channel: info, file, image };
+      }
       const embeddedTranscript = embeddedHuddleTranscription(fileRecord, parentFileRecord);
       const { contentType, content } =
         embeddedTranscript ?? (await this.readPrivateFileText(fileRecord, "file.content.read"));
@@ -857,6 +1497,7 @@ export class OpenGeniSlackBotClient {
       const targetKind = input.userId ? "user" : "channel";
       const targetId = input.userId ?? input.channelId!;
       const blocks = validateSlackMessageBlocks(input.blocks);
+      const wireBlocks = slackMessageWireBlocks(blocks);
       const requestDigest = this.postRequestDigest({
         operationId: input.operationId,
         targetKind,
@@ -877,10 +1518,10 @@ export class OpenGeniSlackBotClient {
         claimLeaseMs: SLACK_POST_CLAIM_LEASE_MS,
       });
       if (claim.kind === "connection_not_found") {
-        throw new Error("OpenGeni Slack bot connection no longer exists");
+        throw new Error("Opengeni Slack bot connection no longer exists");
       }
       if (claim.kind === "conflict") {
-        throw new Error("operationId is already bound to a different Slack post request");
+        throw new SlackBotOperationConflictError("post");
       }
       if (claim.kind === "in_progress") {
         throw new Error("Slack post operation is already in progress; retry the same operationId");
@@ -938,7 +1579,7 @@ export class OpenGeniSlackBotClient {
       const posted = await this.call(headers, "chat.postMessage", {
         channel: channelId,
         text: input.text,
-        ...(blocks ? { blocks: JSON.stringify(blocks) } : {}),
+        ...(wireBlocks ? { blocks: JSON.stringify(wireBlocks) } : {}),
         client_msg_id: input.operationId,
         unfurl_links: "false",
         unfurl_media: "false",
@@ -1003,6 +1644,7 @@ export class OpenGeniSlackBotClient {
     let providerCallStarted = false;
     const blocks = validateSlackMessageBlocks(input.blocks);
     try {
+      const wireBlocks = slackMessageWireBlocks(blocks);
       const headers = await this.headersFor(operation);
       await this.requireMemberChannel(headers, input.channelId);
       const requestDigest = this.updateRequestDigest({ ...input, ...(blocks ? { blocks } : {}) });
@@ -1018,10 +1660,10 @@ export class OpenGeniSlackBotClient {
         claimLeaseMs: SLACK_UPDATE_CLAIM_LEASE_MS,
       });
       if (claim.kind === "connection_not_found") {
-        throw new Error("OpenGeni Slack bot connection no longer exists");
+        throw new Error("Opengeni Slack bot connection no longer exists");
       }
       if (claim.kind === "conflict") {
-        throw new Error("operationId is already bound to a different Slack update request");
+        throw new SlackBotOperationConflictError("update");
       }
       if (claim.kind === "in_progress") {
         throw new Error(
@@ -1041,7 +1683,7 @@ export class OpenGeniSlackBotClient {
         channel: input.channelId,
         ts: input.timestamp,
         text: input.text,
-        ...(blocks ? { blocks: JSON.stringify(blocks) } : {}),
+        ...(wireBlocks ? { blocks: JSON.stringify(wireBlocks) } : {}),
       });
       const slackChannelId = requiredSlackString(updated.channel, "channel");
       const slackMessageTimestamp = requiredSlackString(updated.ts, "ts");
@@ -1112,10 +1754,10 @@ export class OpenGeniSlackBotClient {
         claimLeaseMs: SLACK_DELETE_CLAIM_LEASE_MS,
       });
       if (claim.kind === "connection_not_found") {
-        throw new Error("OpenGeni Slack bot connection no longer exists");
+        throw new Error("Opengeni Slack bot connection no longer exists");
       }
       if (claim.kind === "conflict") {
-        throw new Error("operationId is already bound to a different Slack delete request");
+        throw new SlackBotOperationConflictError("delete");
       }
       if (claim.kind === "in_progress") {
         throw new Error(
@@ -1211,10 +1853,7 @@ export class OpenGeniSlackBotClient {
   }
 
   private async slackMessageExists(channelId: string, timestamp: string): Promise<boolean> {
-    const headers = await this.headersForDestination(
-      "message.delete",
-      `${SLACK_API_BASE}chat.getPermalink`,
-    );
+    const headers = await this.headersFor("message.delete");
     try {
       await this.call(headers, "chat.getPermalink", {
         channel: channelId,
@@ -1236,15 +1875,17 @@ export class OpenGeniSlackBotClient {
     text: string;
   }): Promise<{ timestamp: string }> {
     const method = input.threadTimestamp ? "conversations.replies" : "conversations.history";
-    const headers = await this.headersForDestination("message.post", `${SLACK_API_BASE}${method}`);
+    const headers = await this.headersFor("message.post");
     const seenCursors = new Set<string>();
     let cursor: string | null = null;
     let matchedTimestamp: string | null = null;
     let exhausted = false;
-    for (let page = 0; page < MAX_SLACK_POST_RECONCILIATION_PAGES; page += 1) {
+    for (let page = 0; page < this.postReconciliationPageLimit(); page += 1) {
       const payload = await this.call(headers, method, {
         channel: input.channelId,
-        limit: String(input.threadTimestamp ? MAX_THREAD_PAGE : MAX_HISTORY_PAGE),
+        limit: String(
+          this.historyPageLimit(input.threadTimestamp ? MAX_THREAD_PAGE : MAX_HISTORY_PAGE),
+        ),
         ...(input.threadTimestamp ? { ts: input.threadTimestamp } : {}),
         ...(cursor ? { cursor } : {}),
       });
@@ -1284,7 +1925,7 @@ export class OpenGeniSlackBotClient {
     return { timestamp: matchedTimestamp };
   }
 
-  private async requireMemberChannel(headers: Record<string, string>, channelId: string) {
+  private async requireMemberChannel(headers: SlackCallAuthority, channelId: string) {
     const payload = await this.call(headers, "conversations.info", {
       channel: channelId,
     });
@@ -1299,8 +1940,9 @@ export class OpenGeniSlackBotClient {
   }
 
   private async requireActiveNonSharedMemberChannel(
-    headers: Record<string, string>,
+    headers: SlackCallAuthority,
     channelId: string,
+    privateRecipientSlackUserId?: string,
   ) {
     const projected = await this.requireMemberChannel(headers, channelId);
     if (projected.isArchived) {
@@ -1309,11 +1951,14 @@ export class OpenGeniSlackBotClient {
     if (projected.isShared || projected.isExternallyShared || projected.isOrgShared) {
       throw new SlackBotProviderError("slack_connect_unsupported");
     }
+    if (privateRecipientSlackUserId) {
+      assertSlackPrivateTaskRecipient(projected, privateRecipientSlackUserId);
+    }
     return projected;
   }
 
   private async requireFileForChannel(
-    headers: Record<string, string>,
+    headers: SlackCallAuthority,
     operation: "file.info" | "file.content.read",
     input: { channelId: string; fileId: string; parentFileId?: string },
   ) {
@@ -1390,13 +2035,32 @@ export class OpenGeniSlackBotClient {
   }
 
   private async call(
-    headers: Record<string, string>,
+    authority: SlackCallAuthority,
     method: string,
     params: Record<string, string>,
   ): Promise<SlackPayload> {
+    let providerRequestStarted = false;
     try {
+      const destination = `${SLACK_API_BASE}${method}`;
+      // Refused or stale authority cannot consume another installation's quota.
+      await this.headersForDestination(authority.operation, destination, "preflight");
+      const retryAfterSeconds = await this.rateLimit(this.metadata.slackTeamId, method);
+      if (retryAfterSeconds > 0) {
+        throw new SlackBotProviderError("rate_limited", retryAfterSeconds * 1_000);
+      }
+      // Quota reservation is an await: recheck live authority after it, as the
+      // final await before each physical provider request.
+      const headers = await this.headersForDestination(authority.operation, destination);
+      providerRequestStarted = true;
       return (await slackApiFetchWithHeaders(this.fetchImpl, method, headers, params)).payload;
     } catch (error) {
+      if (providerRequestStarted && slackHistoryRateLimited(error)) {
+        await this.rateLimit(
+          this.metadata.slackTeamId,
+          method,
+          Math.max(1, Math.ceil((error.retryAfterMs ?? 60_000) / 1_000)),
+        );
+      }
       if (slackCredentialRejected(error)) {
         await setConnectionStatus(this.db, this.context.workspaceId, "needs_reauth", error.code, {
           id: this.connection.id,
@@ -1410,11 +2074,10 @@ export class OpenGeniSlackBotClient {
 
   private async withAudit<T extends Record<string, unknown>>(
     operation: SlackBotOperation,
-    run: (headers: Record<string, string>) => Promise<T>,
+    run: (authority: SlackCallAuthority) => Promise<T>,
   ): Promise<T & { receipt: SlackBotReceipt }> {
     try {
-      const headers = await this.headersFor(operation);
-      const result = await run(headers);
+      const result = await run(await this.headersFor(operation));
       await this.recordAudit(operation, "succeeded");
       return { ...result, receipt: this.receipt(operation) };
     } catch (error) {
@@ -1423,16 +2086,14 @@ export class OpenGeniSlackBotClient {
     }
   }
 
-  private async headersFor(operation: SlackBotOperation): Promise<Record<string, string>> {
-    return await this.headersForDestination(
-      operation,
-      `${SLACK_API_BASE}${slackMethodForOperation(operation)}`,
-    );
+  private async headersFor(operation: SlackBotOperation): Promise<SlackCallAuthority> {
+    return Object.freeze({ operation });
   }
 
   private async headersForDestination(
     operation: SlackBotOperation,
     destinationUrl: string,
+    credentialResolutionMode: "execution" | "preflight" = "execution",
   ): Promise<Record<string, string>> {
     const result = await this.resolveCredential({
       workspaceId: this.context.workspaceId,
@@ -1442,13 +2103,49 @@ export class OpenGeniSlackBotClient {
         connectionId: this.connection.id,
         providerDomain: "slack.com",
         kind: "app_install",
-        scopes: [...OPENGENI_SLACK_BOT_REQUIRED_SCOPES],
+        scopes: [
+          ...OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
+          ...(operation === "file.upload" ? [OPENGENI_SLACK_FILE_UPLOAD_REQUIRED_SCOPE] : []),
+        ],
         subjectScope: "workspace",
       },
       destinationUrl,
+      credentialResolutionMode,
     });
     if (result.status !== "ok" || result.connectionId !== this.connection.id) {
-      throw new Error("OpenGeni Slack bot connection needs to be reinstalled");
+      throw new Error("Opengeni Slack bot connection needs to be reinstalled");
+    }
+    const current = await requireOpenGeniSlackBotConnection(
+      this.db,
+      this.context.workspaceId,
+      this.connection.id,
+    );
+    const currentMetadata = openGeniSlackBotMetadata(current.metadata);
+    if (operation === "file.upload" && !hasOpenGeniSlackFileUploadScope(current.grantedScopes)) {
+      throw new SlackBotProviderError("slack_bot_file_upload_scope_missing");
+    }
+    if (
+      current.accountId !== this.context.accountId ||
+      current.version !== this.connection.version ||
+      result.connectionVersion !== this.connection.version ||
+      !currentMetadata ||
+      currentMetadata.slackTeamId !== this.metadata.slackTeamId ||
+      currentMetadata.botId !== this.metadata.botId ||
+      currentMetadata.botUserId !== this.metadata.botUserId
+    ) {
+      throw new Error("Opengeni Slack bot connection authority changed");
+    }
+    // The adapter callback is a fallible preflight. The canonical credential
+    // callback must remain the final await before the physical fetch.
+    if (this.authorizeProviderRequest && (await this.authorizeProviderRequest()) === false) {
+      throw new Error("Opengeni Slack bot provider request is no longer authorized");
+    }
+    if (
+      credentialResolutionMode === "execution" &&
+      result.authorizeProviderRequest &&
+      !(await result.authorizeProviderRequest())
+    ) {
+      throw new Error("Opengeni Slack bot provider request is no longer authorized");
     }
     return result.headers;
   }
@@ -1456,8 +2153,9 @@ export class OpenGeniSlackBotClient {
   private async fetchPrivateFile(
     url: URL,
     operation: "file.info" | "file.content.read",
+    authorizeBeforeFetch?: () => Promise<void>,
   ): Promise<Response> {
-    const response = await this.fetchPrivateFileOnce(url, operation);
+    const response = await this.fetchPrivateFileOnce(url, operation, authorizeBeforeFetch);
     if (response.status < 300 || response.status >= 400) {
       return response;
     }
@@ -1478,18 +2176,20 @@ export class OpenGeniSlackBotClient {
     } catch {
       throw new SlackBotProviderError("invalid_file_redirect");
     }
-    return await this.fetchPrivateFileOnce(redirected, operation);
+    return await this.fetchPrivateFileOnce(redirected, operation, authorizeBeforeFetch);
   }
 
   private async fetchPrivateFileOnce(
     url: URL,
     operation: "file.info" | "file.content.read",
+    authorizeBeforeFetch?: () => Promise<void>,
   ): Promise<Response> {
     try {
       assertPrivateSlackFileUrl(url);
     } catch {
       throw new SlackBotProviderError("invalid_file_url");
     }
+    await authorizeBeforeFetch?.();
     const headers = await this.headersForDestination(operation, url.toString());
     let response: Response;
     try {
@@ -1497,7 +2197,8 @@ export class OpenGeniSlackBotClient {
         method: "GET",
         headers: {
           ...headers,
-          accept: "text/*, application/json, application/xml, application/xhtml+xml",
+          accept:
+            "image/png, image/jpeg, image/webp, text/*, application/json, application/xml, application/xhtml+xml",
         },
         redirect: "manual",
         signal: AbortSignal.timeout(SLACK_TIMEOUT_MS),
@@ -1700,8 +2401,22 @@ export class OpenGeniSlackBotClient {
   }
 }
 
+/** Full decode guards the model image block against header-only or corrupt files. */
+export async function validateSlackMcpImage(bytes: Uint8Array): Promise<void> {
+  try {
+    await sharp(bytes, { limitInputPixels: 16_000_000, failOn: "error" }).stats();
+  } catch {
+    throw new SlackBotProviderError("invalid_file_content");
+  }
+}
+
 export function createOpenGeniSlackBotClient(
-  deps: { db: Database; settings: Settings; slackFetch?: typeof fetch },
+  deps: {
+    db: Database;
+    settings: Settings;
+    slackFetch?: typeof fetch;
+    authorizeProviderRequest?: SlackProviderAuthorization;
+  },
   resolved: Awaited<ReturnType<typeof resolveSlackBotConnectionForTool>>,
 ): OpenGeniSlackBotClient {
   return new OpenGeniSlackBotClient(
@@ -1711,11 +2426,17 @@ export function createOpenGeniSlackBotClient(
     resolved.metadata,
     resolved.context,
     deps.slackFetch,
+    deps.authorizeProviderRequest,
   );
 }
 
 export async function createOpenGeniSlackBotInteractionClient(
-  deps: { db: Database; settings: Settings; slackFetch?: typeof fetch },
+  deps: {
+    db: Database;
+    settings: Settings;
+    slackFetch?: typeof fetch;
+    authorizeProviderRequest?: SlackProviderAuthorization;
+  },
   input: {
     accountId: string;
     workspaceId: string;
@@ -1730,10 +2451,10 @@ export async function createOpenGeniSlackBotInteractionClient(
     input.connectionId,
   );
   if (connection.accountId !== input.accountId) {
-    throw new Error("OpenGeni Slack bot connection tenant mismatch");
+    throw new Error("Opengeni Slack bot connection tenant mismatch");
   }
   const metadata = openGeniSlackBotMetadata(connection.metadata);
-  if (!metadata) throw new Error("OpenGeni Slack bot connection metadata is invalid");
+  if (!metadata) throw new Error("Opengeni Slack bot connection metadata is invalid");
   return new OpenGeniSlackBotClient(
     deps.db,
     deps.settings,
@@ -1747,6 +2468,7 @@ export async function createOpenGeniSlackBotInteractionClient(
       scheduledTaskId: null,
     },
     deps.slackFetch,
+    deps.authorizeProviderRequest,
   );
 }
 
@@ -1770,7 +2492,7 @@ async function slackApiFetchWithHeaders(
   credentialHeaders: Record<string, string>,
   params: Record<string, string>,
 ): Promise<{ response: Response; payload: SlackPayload }> {
-  if (!/^[a-z]+\.[a-z]+$/i.test(method)) {
+  if (!/^[a-z]+(?:\.[a-z]+){1,2}$/i.test(method)) {
     throw new Error("invalid Slack API method");
   }
   const url = new URL(method, SLACK_API_BASE);
@@ -1785,6 +2507,7 @@ async function slackApiFetchWithHeaders(
         "content-type": "application/x-www-form-urlencoded",
       },
       body,
+      redirect: "error",
       signal: AbortSignal.timeout(SLACK_TIMEOUT_MS),
     });
   } catch {
@@ -1829,7 +2552,7 @@ function assertOpenGeniSlackBotScopes(grantedScopes: string[]): void {
     ];
     throw new SlackBotCredentialVerificationError(
       "scope_mismatch",
-      `Slack bot scopes do not satisfy the OpenGeni manifest (${facts.join("; ")})`,
+      `Slack bot scopes do not satisfy the Opengeni manifest (${facts.join("; ")})`,
     );
   }
 }
@@ -1862,6 +2585,7 @@ function projectChannel(value: unknown) {
     isMember: channel.is_member === true,
     isDirectMessage: channel.is_im === true,
     isMpim: channel.is_mpim === true,
+    userId: nullableBoundedSlackString(channel.user, 128),
     isArchived: channel.is_archived === true,
     isShared: channel.is_shared === true,
     isExternallyShared: channel.is_ext_shared === true,
@@ -1879,6 +2603,16 @@ function projectChannel(value: unknown) {
   };
 }
 
+/** A private route needs live provider proof of the exact linked requester's bot IM. */
+export function assertSlackPrivateTaskRecipient(
+  channel: { isDirectMessage: boolean; isMpim: boolean; userId: string | null },
+  slackUserId: string,
+): void {
+  if (!channel.isDirectMessage || channel.isMpim || channel.userId !== slackUserId) {
+    throw new SlackBotProviderError("private_task_recipient_changed");
+  }
+}
+
 function projectSlackTaskPolicyUser(value: unknown, installationTeamId: string) {
   const user = slackRecord(value);
   const id = slackString(user?.id);
@@ -1952,39 +2686,6 @@ function assertSlackReactionCheckpointBinding(
   }
 }
 
-function createSlackReactionContextCheckpoint(
-  binding: SlackReactionContextCheckpointBinding,
-  state: SlackReactionContextCheckpointUnsigned["state"],
-  key: Uint8Array,
-): SlackReactionContextCheckpoint {
-  const unsigned: SlackReactionContextCheckpointUnsigned = {
-    version: SLACK_REACTION_CONTEXT_CHECKPOINT_VERSION,
-    binding: { ...binding },
-    state: {
-      createdAtMs: state.createdAtMs,
-      pageCount: state.pageCount,
-      nextCursor: state.nextCursor,
-      seenCursors: [...state.seenCursors],
-      seenMessageTimestamps: [...state.seenMessageTimestamps],
-      threadTimestamp: state.threadTimestamp,
-      messages: state.messages.map((message) => ({
-        ...message,
-        files: message.files.map((file) => ({ ...file })),
-      })),
-    },
-  };
-  const checkpoint: SlackReactionContextCheckpoint = {
-    ...unsigned,
-    signature: slackReactionContextCheckpointSignature(unsigned, key),
-  };
-  if (
-    Buffer.byteLength(JSON.stringify(checkpoint), "utf8") > MAX_REACTION_CONTEXT_CHECKPOINT_BYTES
-  ) {
-    throw new SlackBotProviderError("reaction_checkpoint_too_large");
-  }
-  return checkpoint;
-}
-
 function parseSlackReactionContextCheckpoint(
   value: unknown,
   expectedBinding: SlackReactionContextCheckpointBinding,
@@ -2203,64 +2904,6 @@ function parseSlackReactionCheckpointMessage(value: unknown): SlackReactionCheck
   };
 }
 
-function slackReactionCheckpointMessage(
-  message: ReturnType<typeof projectMessage>,
-): SlackReactionCheckpointMessage {
-  const files: SlackReactionCheckpointMessage["files"] = [];
-  let fileLabelChars = 0;
-  for (const file of message.files) {
-    const label = file.title || file.name || file.id;
-    if (!label) continue;
-    const addedChars = label.length + (files.length > 0 ? 2 : 0);
-    if (
-      files.length >= MAX_REACTION_CONTEXT_CHECKPOINT_FILES ||
-      fileLabelChars + addedChars > MAX_REACTION_CONTEXT_CHECKPOINT_FILE_LABEL_CHARS
-    ) {
-      break;
-    }
-    files.push({ id: file.id, label });
-    fileLabelChars += addedChars;
-  }
-  return {
-    timestamp: message.timestamp,
-    userId: message.userId,
-    botId: message.botId,
-    threadTimestamp: message.threadTimestamp,
-    text: message.text,
-    files,
-  };
-}
-
-function projectSlackReactionCheckpointMessage(
-  message: SlackReactionCheckpointMessage,
-): ReturnType<typeof projectMessage> {
-  return {
-    timestamp: message.timestamp,
-    userId: message.userId,
-    botId: message.botId,
-    threadTimestamp: message.threadTimestamp,
-    text: message.text,
-    files: message.files.map((file) => ({
-      id: file.id,
-      name: "",
-      title: file.label,
-      mimetype: "",
-      filetype: "",
-      mode: "",
-      size: null,
-      originatingHuddleId: "",
-      huddleTranscriptFileId: "",
-    })),
-  };
-}
-
-function selectSlackReactionCheckpointMessages(
-  messages: ReturnType<typeof projectMessage>[],
-): ReturnType<typeof projectMessage>[] {
-  if (messages.length <= MAX_REACTION_CONTEXT_MESSAGES) return [...messages];
-  return [messages[0]!, ...messages.slice(-(MAX_REACTION_CONTEXT_MESSAGES - 1))];
-}
-
 function hasExactSlackCheckpointKeys(value: Record<string, unknown>, expected: string[]): boolean {
   return Object.keys(value).sort().join(",") === [...expected].sort().join(",");
 }
@@ -2576,6 +3219,74 @@ function embeddedSlackFileIds(content: string): Set<string> {
   );
 }
 
+/**
+ * Bounded projections of `assistant.search.context` results. Content excerpts
+ * are capped, Slack's rich `blocks` and context messages are deliberately
+ * dropped, and permalinks are kept only when they are https URLs.
+ */
+function projectSearchMessage(value: unknown) {
+  const message = slackRecord(value);
+  const channelId = slackString(message?.channel_id);
+  const ts = slackString(message?.message_ts);
+  if (!message || !channelId || !ts) return null;
+  return {
+    channelId,
+    channelName: boundedSlackString(message.channel_name, 256),
+    ts,
+    authorUserId: boundedSlackString(message.author_user_id, 64),
+    authorName: boundedSlackString(message.author_name, 256),
+    isAuthorBot: message.is_author_bot === true,
+    content: boundedSlackString(message.content, MAX_SEARCH_CONTENT_CHARS),
+    permalink: safeSlackPermalink(message.permalink),
+  };
+}
+
+function projectSearchFile(value: unknown) {
+  const file = slackRecord(value);
+  const id = slackString(file?.file_id);
+  if (!file || !id) return null;
+  return {
+    id,
+    title: boundedSlackString(file.title, 512),
+    filetype: boundedSlackString(file.file_type, 128),
+    authorUserId: boundedSlackString(file.author_user_id, 64),
+    authorName: boundedSlackString(file.author_name, 256),
+    dateCreated: slackUnixSeconds(file.date_created),
+    dateUpdated: slackUnixSeconds(file.date_updated),
+    content: boundedSlackString(file.content, MAX_SEARCH_CONTENT_CHARS),
+    permalink: safeSlackPermalink(file.permalink),
+  };
+}
+
+function projectSearchChannel(value: unknown) {
+  const channel = slackRecord(value);
+  const name = slackString(channel?.name);
+  if (!channel || !name) return null;
+  return {
+    name: boundedSlackString(name, 256),
+    topic: boundedSlackString(channel.topic, 512),
+    purpose: boundedSlackString(channel.purpose, 512),
+    creatorUserId: boundedSlackString(channel.creator_user_id, 64),
+    dateCreated: slackUnixSeconds(channel.date_created),
+    permalink: safeSlackPermalink(channel.permalink),
+  };
+}
+
+function slackUnixSeconds(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function safeSlackPermalink(value: unknown): string | null {
+  // An over-long URL is dropped, never truncated into a still-parseable one.
+  const raw = typeof value === "string" && value.length <= 1_024 ? value : "";
+  if (!raw) return null;
+  try {
+    return new URL(raw).protocol === "https:" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 function projectUser(value: unknown) {
   const user = slackRecord(value);
   const id = slackString(user?.id);
@@ -2701,28 +3412,31 @@ export function nextSlackFilesListPage(
   return nextPage;
 }
 
-function slackMethodForOperation(operation: SlackBotOperation): string {
-  switch (operation) {
-    case "channels.list":
-      return "conversations.list";
-    case "channel_history.read":
-      return "conversations.history";
-    case "thread_replies.read":
-      return "conversations.replies";
-    case "users.list":
-      return "users.list";
-    case "files.list":
-      return "files.list";
-    case "file.info":
-    case "file.content.read":
-      return "files.info";
-    case "message.post":
-      return "chat.postMessage";
-    case "message.update":
-      return "chat.update";
-    case "message.delete":
-      return "chat.delete";
-  }
+/**
+ * Slack action IDs are unique within a block. Keep the logical card untouched
+ * for the durable request digest, and partition repeated actions only on the
+ * provider wire. In particular, a legacy invalid_blocks receipt can retry with
+ * its original operation ID and digest; completed/uncertain posts keep their
+ * existing replay/reconciliation path. Values and action IDs remain exact.
+ */
+export function slackMessageWireBlocks(
+  blocks: SlackMessageBlock[] | undefined,
+): SlackMessageBlock[] | undefined {
+  if (!blocks) return undefined;
+  const wire = blocks.flatMap((block, index): SlackMessageBlock[] => {
+    if (
+      block.type !== "actions" ||
+      new Set(block.elements.map((e) => e.action_id)).size === block.elements.length
+    )
+      return [block];
+    const id = createHash("sha256").update(`${index}:${block.block_id}`).digest("hex").slice(0, 24);
+    return block.elements.map((element, position) => ({
+      type: "actions",
+      block_id: `opengeni_wire_${id}_${position}`,
+      elements: [element],
+    }));
+  });
+  return validateSlackMessageBlocks(wire);
 }
 
 function validateSlackMessageBlocks(
@@ -2738,6 +3452,16 @@ function validateSlackMessageBlocks(
   return blocks;
 }
 
+function validateSlackHomeBlocks(blocks: SlackHomeBlock[]): SlackHomeBlock[] {
+  if (blocks.length < 1 || blocks.length > 100) {
+    throw new RangeError("Slack App Home blocks exceed the supported count");
+  }
+  if (Buffer.byteLength(JSON.stringify(blocks), "utf8") > 48 * 1024) {
+    throw new RangeError("Slack App Home blocks exceed the supported byte size");
+  }
+  return blocks;
+}
+
 function boundedInt(value: number | undefined, max: number, fallback: number): number {
   return typeof value === "number" && Number.isInteger(value) && value > 0
     ? Math.min(value, max)