cortexdb-connectors 0.2.17__tar.gz → 0.2.18__tar.gz

{cortexdb_connectors-0.2.17 → cortexdb_connectors-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-connectors
-Version: 0.2.17
+Version: 0.2.18
 Summary: Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API.
 Author-email: CortexDB Team <team@cortexdb.ai>
 License-Expression: Apache-2.0

{cortexdb_connectors-0.2.17 → cortexdb_connectors-0.2.18}/cortexdb_connectors/__init__.py

@@ -8,7 +8,7 @@ poll loop; or `from cortexdb_connectors.slack import SlackConnector`
 to drive it programmatically.
 """
 
-__version__ = "0.2.17"
+__version__ = "0.2.18"
 
 from cortexdb_connectors.base import (
     Actor,

{cortexdb_connectors-0.2.17 → cortexdb_connectors-0.2.18}/cortexdb_connectors/base.py

@@ -114,7 +114,7 @@ class VisibilityLevel(str, Enum):
 @dataclass(frozen=True)
 class Source:
     system: str
-    connector_version: str = "0.2.17"
+    connector_version: str = "0.2.18"
 
 
 @dataclass(frozen=True)

{cortexdb_connectors-0.2.17 → cortexdb_connectors-0.2.18}/cortexdb_connectors/cli.py

@@ -53,7 +53,11 @@ CONNECTORS: dict[str, dict[str, Any]] = {
     "slack": {
         "import": "cortexdb_connectors.slack:SlackConnector",
         "secrets": [("slack_bot_token", "SLACK_BOT_TOKEN")],
-        "options": [("channels", "SLACK_CHANNELS", "list")],
+        "options": [
+            ("channels", "SLACK_CHANNELS", "list"),
+            ("ingest_files", "SLACK_INGEST_FILES", "bool"),
+            ("file_types", "SLACK_FILE_TYPES", "list"),
+        ],
     },
     "github": {
         "import": "cortexdb_connectors.github:GitHubConnector",

{cortexdb_connectors-0.2.17 → cortexdb_connectors-0.2.18}/cortexdb_connectors/slack/__init__.py

@@ -1,9 +1,18 @@
 """
 Slack connector for CortexDB.
 
-Ingests messages (including threaded replies) from Slack channels into
-CortexDB as Episodes.  Uses the ``slack_sdk`` WebClient to interact with
-the Slack API and respects Tier-3 rate limits (~50 requests/minute).
+Ingests messages (including threaded replies) and shared files from Slack
+channels into CortexDB as Episodes.  Uses the ``slack_sdk`` WebClient to
+interact with the Slack API and respects Tier-3 rate limits
+(~50 requests/minute).
+
+File shares ride the multimodal path: each ``msg["files"]`` entry becomes
+its own blob-carrying Episode (``Episode.blob`` → ``POST /v1/blobs`` →
+``content.kind="blob_ref"``) so the server's content processors
+(Tika/vision/ASR) extract and index the bytes — same as Jira attachments.
+Requires the ``files:read`` bot-token scope; without it Slack answers file
+downloads with an HTML login page, which is detected and logged loudly
+(metadata-only ingest, never silent).
 """
 
 from __future__ import annotations
@@ -12,12 +21,14 @@ import asyncio
 import hashlib
 import html
 import logging
+import os
 import re
 from datetime import datetime, timedelta, timezone
 from typing import Any
 
 from cortexdb_connectors.base import (
     Actor,
+    Attachment,
     ConnectorFetchError,
     CortexConnector,
     EntityRef,
@@ -56,6 +67,11 @@ _HAS_CONTENT_RE = re.compile(r"[^\W_]", re.UNICODE)
 # S9: bounded scan for old threads with new replies (see fetch_events).
 _THREAD_SCAN_PAGE_LIMIT = 5
 
+# F1: the server's `/v1/blobs` body cap — anything larger 413s. Files over
+# this ingest metadata-only (the filename line survives as text) instead of
+# crashing the sync or being silently dropped.
+_MAX_FILE_BYTES = 32 * 1024 * 1024
+
 
 def content_version(content: str) -> str:
     """Short stable digest of the ingested content — the mutable version
@@ -79,8 +95,20 @@ def message_idempotency_key(channel_id: str, ts: str, content: str) -> str:
     return f"slack:{channel_id}:{ts}:{content_version(content)}"
 
 
+def file_idempotency_key(channel_id: str, file_id: str, version: str) -> str:
+    """Versioned file key: ``slack:file:{channel}:{file_id}:{version}``.
+
+    Keyed on the Slack file id (stable across re-fetches of the same share)
+    plus an update marker, consistent with the versioned-key scheme (S1b):
+    a re-listed unchanged file replays cleanly server-side, while an edited
+    editable file (post/canvas) lands as a new version.
+    """
+    return f"slack:file:{channel_id}:{file_id}:{version}"
+
+
 class SlackConnector(CortexConnector):
-    """Connector that syncs Slack channel messages into CortexDB.
+    """Connector that syncs Slack channel messages and shared files into
+    CortexDB.
 
     Parameters
     ----------
@@ -89,12 +117,25 @@ class SlackConnector(CortexConnector):
     cortex_api_key:
         Bearer token for CortexDB authentication.
     slack_bot_token:
-        Slack Bot User OAuth Token (``xoxb-...``).
+        Slack Bot User OAuth Token (``xoxb-...``). Needs ``files:read``
+        for file-content ingestion (without it, files ingest
+        metadata-only and the sync logs the missing scope loudly).
     channels:
         Explicit list of channel IDs to sync.  If empty, the connector
         will auto-discover all channels the bot has been added to.
     scope:
         CortexDB scope path (hierarchical string, e.g. ``"user:default"``).
+    ingest_files:
+        Master switch for file-content ingestion (default on; env
+        ``SLACK_INGEST_FILES=0`` to disable). Off = pre-0.2.18 behavior,
+        as an explicit operator opt-out.
+    file_types:
+        Cost control: when non-empty, only files matching an entry ingest
+        their BYTES (everything else ingests metadata-only, so filenames
+        stay searchable at zero media-processing cost). Entries match the
+        full mimetype (``application/pdf``), the mime major type
+        (``image``, ``audio``), or the file extension (``pdf``). Env:
+        ``SLACK_FILE_TYPES`` (comma-separated). Empty = all types.
     """
 
     connector_name: str = "slack"
@@ -121,10 +162,23 @@ class SlackConnector(CortexConnector):
         slack_bot_token: str,
         channels: list[str] | None = None,
         scope: str = "user:default",
+        ingest_files: bool | None = None,
+        file_types: list[str] | None = None,
     ) -> None:
         super().__init__(cortex_url, cortex_api_key, scope)
         self.slack_bot_token = slack_bot_token
         self.channels = channels or []
+        # F1 cost controls; None = read the env so the webhook path (which
+        # builds this connector directly, not via the CLI) honors the same
+        # configuration.
+        if ingest_files is None:
+            env = os.environ.get("SLACK_INGEST_FILES", "").strip().lower()
+            ingest_files = env not in ("0", "false", "no", "off") if env else True
+        self.ingest_files = ingest_files
+        if file_types is None:
+            env_types = os.environ.get("SLACK_FILE_TYPES", "")
+            file_types = [t for t in (p.strip() for p in env_types.split(",")) if t]
+        self.file_types = list(file_types)
         self._user_cache: dict[str, dict[str, Any]] = {}
         self._user_cache_populated = False
         # R3: one conversations.info (+ conversations.members) per channel
@@ -132,6 +186,13 @@ class SlackConnector(CortexConnector):
         self._channel_info_cache: dict[str, dict[str, Any]] = {}
         # R5: per-channel failures recorded for the cycle (channel_id → error).
         self.last_channel_errors: dict[str, str] = {}
+        # F1: file RawEvents emitted this run — a thread_broadcast reply is
+        # listed by BOTH conversations.history and conversations.replies, and
+        # without dedup its files would be downloaded and uploaded twice.
+        self._emitted_file_ids: set[str] = set()
+        # F1: warn about a missing files:read scope once per run, not once
+        # per file.
+        self._files_scope_warned = False
 
     # -- CortexConnector interface -------------------------------------------
 
@@ -184,6 +245,8 @@ class SlackConnector(CortexConnector):
         run_started = datetime.now(timezone.utc)
         self._channel_info_cache.clear()  # roster/privacy may change between runs
         self.last_channel_errors = {}
+        self._emitted_file_ids.clear()
+        self._files_scope_warned = False
 
         for channel_id in channels:
             try:
@@ -290,6 +353,9 @@ class SlackConnector(CortexConnector):
                     permissions=dict(permissions),
                 )
                 events.append(raw)
+                events.extend(
+                    self._file_events(msg, channel_id, dict(permissions))
+                )
 
                 # Fetch thread replies if this message has a thread.
                 if msg.get("reply_count", 0) > 0:
@@ -327,14 +393,21 @@ class SlackConnector(CortexConnector):
         return events
 
     def normalize(self, raw: RawEvent) -> Episode | None:
-        """Convert a Slack message ``RawEvent`` into a CortexDB ``Episode``.
+        """Convert a Slack ``RawEvent`` into a CortexDB ``Episode``.
+
+        File RawEvents (``kind="file"``, emitted per ``msg["files"]`` entry
+        by ``fetch_events``) become blob-carrying Episodes on the multimodal
+        path. A file-only MESSAGE still returns None here — its content
+        rides the separate file episodes, so nothing is lost.
 
         Returns None (skip) for messages the first-cut content policy
-        excludes: join/leave noise, attachment/file-only messages with no
-        text, and emoji-only messages. Emoji reactions never become
-        content (they ride ``raw_payload`` only).
+        excludes: join/leave noise, messages with no text, and emoji-only
+        messages. Emoji reactions never become content (they ride
+        ``raw_payload`` only).
         """
         data = raw.data
+        if data.get("kind") == "file":
+            return self._normalize_file(raw)
         text = self._render_text(data)
         if text is None:
             return None
@@ -456,6 +529,233 @@ class SlackConnector(CortexConnector):
             )
         return Visibility(level=VisibilityLevel.ORGANIZATION)
 
+    # -- file ingestion (F1) -------------------------------------------------
+
+    def _file_events(
+        self,
+        msg: dict[str, Any],
+        channel_id: str,
+        permissions: dict[str, Any],
+    ) -> list[RawEvent]:
+        """One ``kind="file"`` RawEvent per file shared on *msg*.
+
+        Bytes are downloaded here, mirroring Jira: fetch downloads,
+        ``normalize`` wraps them in ``Episode.blob``, ``ingest_episode``
+        uploads to ``/v1/blobs``. Oversize files, external shares with no
+        downloadable URL, and failed downloads degrade to metadata-only
+        events — loudly logged, never silently dropped, never sync-fatal.
+        """
+        if not self.ingest_files:
+            return []
+        events: list[RawEvent] = []
+        ts = str(msg.get("ts", ""))
+        for f in msg.get("files") or []:
+            file_id = f.get("id")
+            if not file_id:
+                continue
+            if f.get("mode") == "tombstone" or f.get("file_access") not in (
+                None,
+                "visible",
+            ):
+                # Deleted or access-revoked at the source — nothing to fetch.
+                continue
+            external_id = f"{channel_id}:{ts}:file:{file_id}"
+            if external_id in self._emitted_file_ids:
+                continue
+            self._emitted_file_ids.add(external_id)
+
+            name = f.get("name") or f.get("title") or file_id
+            mime = f.get("mimetype") or "application/octet-stream"
+            size = int(f.get("size") or 0)
+            url = f.get("url_private_download") or f.get("url_private")
+            data_bytes: bytes | None = None
+            if not url:
+                logger.warning(
+                    "slack file has no downloadable URL (external share?): "
+                    "channel=%s file=%s — filename recorded, bytes NOT "
+                    "ingested",
+                    channel_id,
+                    name,
+                )
+            elif self.file_types and not self._file_type_allowed(mime, name):
+                logger.info(
+                    "slack file filtered by file-type policy "
+                    "(SLACK_FILE_TYPES=%s): channel=%s file=%s mime=%s — "
+                    "metadata-only",
+                    ",".join(self.file_types),
+                    channel_id,
+                    name,
+                    mime,
+                )
+            elif size > _MAX_FILE_BYTES:
+                logger.error(
+                    "slack file SKIPPED (too large): channel=%s file=%s "
+                    "size=%d limit=%d — filename recorded, bytes NOT ingested",
+                    channel_id,
+                    name,
+                    size,
+                    _MAX_FILE_BYTES,
+                )
+            else:
+                data_bytes = self._download_file(url, name, mime)
+
+            events.append(
+                RawEvent(
+                    source="slack",
+                    external_id=external_id,
+                    timestamp=datetime.fromtimestamp(
+                        float(ts or "0"), tz=timezone.utc
+                    ),
+                    data={
+                        "kind": "file",
+                        "file_id": file_id,
+                        "name": name,
+                        "title": f.get("title") or "",
+                        "mimetype": mime,
+                        "size": size,
+                        "user": f.get("user") or msg.get("user") or "",
+                        "version": str(
+                            f.get("updated")
+                            or f.get("timestamp")
+                            or f.get("created")
+                            or ""
+                        ),
+                        "permalink": f.get("permalink") or "",
+                        "message_ts": ts,
+                        "thread_ts": msg.get("thread_ts") or "",
+                        "_channel_id": channel_id,
+                        "bytes": data_bytes,
+                    },
+                    permissions=permissions,
+                )
+            )
+        return events
+
+    def _file_type_allowed(self, mime: str, name: str) -> bool:
+        """Does *mime*/*name* match the ``file_types`` allowlist?
+
+        An entry matches the full mimetype (``application/pdf``), the mime
+        major type (``image``), or the file extension (``pdf``).
+        """
+        allowed = {t.lower().lstrip(".") for t in self.file_types}
+        mime = mime.lower()
+        ext = name.rsplit(".", 1)[-1].lower() if "." in name else ""
+        return (
+            mime in allowed
+            or mime.split("/", 1)[0] in allowed
+            or (bool(ext) and ext in allowed)
+        )
+
+    def _download_file(self, url: str, name: str, mime: str) -> bytes | None:
+        """GET a Slack file's bytes with the bot token; None on any failure.
+
+        A token without the ``files:read`` scope gets a 200 HTML login page
+        instead of the bytes — detected via content-type (unless the file
+        itself is HTML) so an auth page is never ingested as content.
+        """
+        import httpx
+
+        try:
+            resp = httpx.get(
+                url,
+                headers={"Authorization": f"Bearer {self.slack_bot_token}"},
+                follow_redirects=True,
+                timeout=120.0,
+            )
+            resp.raise_for_status()
+        except Exception as exc:  # noqa: BLE001
+            logger.error(
+                "slack file download FAILED: file=%s: %s — filename recorded, "
+                "bytes NOT ingested",
+                name,
+                exc,
+            )
+            return None
+        ctype = (resp.headers.get("content-type") or "").lower()
+        if "text/html" in ctype and "html" not in mime.lower():
+            if not self._files_scope_warned:
+                self._files_scope_warned = True
+                logger.error(
+                    "slack file download returned an HTML page instead of "
+                    "bytes — the bot token is likely missing the files:read "
+                    "scope. File content will NOT be ingested until it is "
+                    "granted (file=%s).",
+                    name,
+                )
+            return None
+        return resp.content
+
+    def _normalize_file(self, raw: RawEvent) -> Episode:
+        """File RawEvent → blob-carrying Episode (``content.kind="blob_ref"``).
+
+        Without bytes (oversize / no-URL / download failure) the episode
+        degrades to its text line so the filename is never lost — same
+        contract as Jira attachments.
+        """
+        data = raw.data
+        channel_id = data.get("_channel_id", "")
+        file_id = data.get("file_id", "")
+        name = data.get("name", "file")
+        mime = data.get("mimetype", "application/octet-stream")
+        size = int(data.get("size", 0) or 0)
+        user_id = data.get("user") or "unknown"
+        sharer = self._display_name(user_id)
+        title = data.get("title") or ""
+        message_ts = data.get("message_ts", "")
+        thread_ts = data.get("thread_ts") or None
+
+        content = (
+            f"[Slack file] {name} ({mime}, {size} bytes) shared by {sharer} "
+            f"in {data.get('_channel_name', channel_id)}"
+        )
+        if title and title != name:
+            content += f": {title}"
+
+        entities = [
+            EntityRef(
+                entity_type="channel",
+                entity_id=channel_id,
+                display_name=data.get("_channel_name", channel_id),
+            )
+        ]
+        if data.get("user"):
+            entities.append(
+                EntityRef(
+                    entity_type="user", entity_id=user_id, display_name=sharer
+                )
+            )
+
+        return Episode(
+            actor=self._make_actor(user_id),
+            source=_SOURCE,
+            episode_type=EpisodeType.DOCUMENT,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload={k: v for k, v in data.items() if k != "bytes"},
+            scope=self.scope,
+            namespace="slack",
+            entities=entities,
+            tags=["slack", "file"],
+            metadata={
+                "file_id": file_id,
+                "size_bytes": size,
+            },
+            thread_id=f"{channel_id}:{thread_ts}" if thread_ts else None,
+            # The carrying message, so recall can hop file → conversation.
+            parent_id=f"{channel_id}:{message_ts}" if message_ts else None,
+            idempotency_key=file_idempotency_key(
+                channel_id, file_id, str(data.get("version", ""))
+            ),
+            blob=Attachment(
+                filename=name,
+                mime_type=mime,
+                size_bytes=size,
+                data=data.get("bytes"),
+                source_url=data.get("permalink") or None,
+                attachment_id=file_id,
+            ),
+        )
+
     # -- helpers -------------------------------------------------------------
 
     def _discover_channels(self, client: Any) -> list[str]:
@@ -590,6 +890,10 @@ class SlackConnector(CortexConnector):
                 # Skip the parent message itself (already captured).
                 if msg.get("ts") == thread_ts and not msg.get("parent_user_id"):
                     continue
+                reply_permissions = {
+                    "is_private": channel_info.get("is_private", False),
+                    "channel_members": channel_info.get("members", []),
+                }
                 raw = RawEvent(
                     source="slack",
                     external_id=f"{channel_id}:{msg.get('ts', '')}",
@@ -597,12 +901,12 @@ class SlackConnector(CortexConnector):
                         float(msg.get("ts", "0")), tz=timezone.utc
                     ),
                     data={**msg, "_channel_id": channel_id},
-                    permissions={
-                        "is_private": channel_info.get("is_private", False),
-                        "channel_members": channel_info.get("members", []),
-                    },
+                    permissions=reply_permissions,
                 )
                 events.append(raw)
+                events.extend(
+                    self._file_events(msg, channel_id, dict(reply_permissions))
+                )
 
             next_cursor = resp.get("response_metadata", {}).get("next_cursor")
             if not next_cursor:

{cortexdb_connectors-0.2.17 → cortexdb_connectors-0.2.18}/cortexdb_connectors/webhooks.py

@@ -119,6 +119,8 @@ class SlackWebhookHandler:
     - Respond to Slack URL verification challenges.
     - Verify request authenticity using the Slack signing secret.
     - Normalize incoming event_callback events into CortexDB Episodes.
+    - Ingest shared files through the multimodal blob path (F1), reusing
+      the poll connector's pipeline for key/content parity.
     - Forward episodes to the CortexDB ingestion API.
     """
 
@@ -231,14 +233,19 @@ class SlackWebhookHandler:
             return JSONResponse({"ok": True})
 
         try:
-            episode = self.normalize(payload, event)
+            episode: Episode | None = self.normalize(payload, event)
+            files, file_msg = self._slack_files(event, event_type)
             # The server rejects empty-text envelopes (422, permanent) --
-            # attachment/file-only messages must be acked-and-skipped, not
-            # forwarded. Slack retries non-2xx deliveries, so failing here
-            # would also cause redelivery storms.
-            if not episode.content.strip():
-                logger.debug("skipping text-less Slack event %s", event_type)
-                return JSONResponse({"ok": True, "skipped": "empty-text"})
+            # the text episode of a text-less message must be skipped, not
+            # forwarded (Slack retries non-2xx deliveries, so failing here
+            # would also cause redelivery storms). F1: a file-only message
+            # is no longer a full skip — its content rides the file
+            # episodes ingested below.
+            if episode is not None and not episode.content.strip():
+                if not files:
+                    logger.debug("skipping text-less Slack event %s", event_type)
+                    return JSONResponse({"ok": True, "skipped": "empty-text"})
+                episode = None
         except Exception:
             # normalize is deterministic — a failure here would fail the
             # redelivery identically, so retrying can't help. Ack and log
@@ -250,35 +257,86 @@ class SlackWebhookHandler:
             )
             return JSONResponse({"ok": True, "skipped": "normalize-failed"})
 
-        # T3: ack now, ingest in the background.
-        task = asyncio.create_task(self._ingest_background(episode, event_type))
+        # T3: ack now, ingest (text episode + any shared files) in the
+        # background — file downloads especially must stay off the 3 s ack
+        # path.
+        task = asyncio.create_task(
+            self._ingest_background(
+                episode,
+                event_type,
+                file_msg=file_msg,
+                channel_id=event.get("channel", ""),
+            )
+        )
         self._pending_ingests.add(task)
         task.add_done_callback(self._pending_ingests.discard)
         return JSONResponse({"ok": True, "queued": True})
 
+    @staticmethod
+    def _slack_files(
+        event: dict[str, Any], event_type: str
+    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        """F1: the files on a message-family event + a container-message
+        dict shaped for ``SlackConnector._file_events`` (poll parity).
+
+        For ``message_changed`` the files ride the nested ``event.message``
+        (same place the edited text lives, S1a).
+        """
+        if event_type not in ("message", "message_changed"):
+            return [], {}
+        msg = event.get("message", {}) if event_type == "message_changed" else event
+        files = [f for f in (msg.get("files") or []) if isinstance(f, dict)]
+        if not files:
+            return [], {}
+        container = {
+            "ts": msg.get("ts") or event.get("ts") or event.get("event_ts", "0"),
+            "user": msg.get("user") or event.get("user", ""),
+            "thread_ts": msg.get("thread_ts") or event.get("thread_ts"),
+            "files": files,
+        }
+        return files, container
+
     # Delays between background ingest attempts (T3). Bounded: after the
     # last attempt the failure is logged loudly — the delivery was already
     # acked, so the poll connector is the recovery path.
     _INGEST_RETRY_DELAYS = (1.0, 5.0, 25.0)
     _VIS_CACHE_TTL_SECS = 900.0
 
-    async def _ingest_background(self, episode: Episode, event_type: str) -> None:
+    async def _ingest_background(
+        self,
+        episode: Episode | None,
+        event_type: str,
+        file_msg: dict[str, Any] | None = None,
+        channel_id: str = "",
+    ) -> None:
+        if episode is not None and episode.entities:
+            channel_id = channel_id or episode.entities[0].entity_id
         # N3: resolve channel privacy → visibility OFF the ack path (it may
         # call the Slack API). Failures keep the episode's default.
+        vis = None
         try:
             vis = await asyncio.to_thread(
-                self._resolve_channel_visibility,
-                episode.entities[0].entity_id if episode.entities else "",
+                self._resolve_channel_visibility, channel_id
             )
-            if vis is not None:
-                episode.visibility = vis
         except Exception:  # noqa: BLE001
             logger.exception("slack webhook: visibility resolution failed")
 
+        if episode is not None:
+            if vis is not None:
+                episode.visibility = vis
+            await self._ingest_with_retries(
+                lambda: self._ingest(episode), event_type, episode.idempotency_key
+            )
+        if file_msg:
+            await self._ingest_files_background(file_msg, channel_id, vis, event_type)
+
+    async def _ingest_with_retries(
+        self, attempt_fn: Any, event_type: str, idempotency_key: str | None
+    ) -> None:
         last_error: BaseException | None = None
         for attempt in range(len(self._INGEST_RETRY_DELAYS) + 1):
             try:
-                await self._ingest(episode)
+                await attempt_fn()
                 return
             except httpx.HTTPStatusError as exc:
                 if exc.response is not None and exc.response.status_code == 409:
@@ -299,10 +357,69 @@ class SlackWebhookHandler:
             "running",
             len(self._INGEST_RETRY_DELAYS) + 1,
             event_type,
-            episode.idempotency_key,
+            idempotency_key,
             last_error,
         )
 
+    async def _ingest_files_background(
+        self,
+        file_msg: dict[str, Any],
+        channel_id: str,
+        vis: Any,
+        event_type: str,
+    ) -> None:
+        """F1: download + ingest a delivery's shared files off the ack path.
+
+        Reuses the poll connector's file pipeline (download →
+        ``Episode.blob`` → ``/v1/blobs`` → ``blob_ref``) with a fresh
+        per-delivery ``SlackConnector``, so webhook and poll produce
+        identical episodes under identical versioned keys — whichever path
+        lands first, the other replays. Needs ``SLACK_BOT_TOKEN`` for the
+        downloads; without it the files are left to the poll connector,
+        loudly.
+        """
+        token = os.environ.get("SLACK_BOT_TOKEN", "")
+        if not token:
+            if not getattr(self, "_files_token_warned", False):
+                self._files_token_warned = True
+                logger.error(
+                    "slack webhook: file(s) shared but SLACK_BOT_TOKEN is not "
+                    "set — file content cannot be downloaded on the webhook "
+                    "path; the poll connector will pick them up if running"
+                )
+            return
+        from cortexdb_connectors.slack import SlackConnector
+
+        conn = SlackConnector(
+            self.cortexdb_url, self.cortexdb_api_key, token, scope=self.scope
+        )
+        conn.actor = self.actor
+        conn.scope_template = self.scope or self.actor
+        try:
+            raws = await asyncio.to_thread(
+                conn._file_events, file_msg, channel_id, {}
+            )
+        except Exception:  # noqa: BLE001
+            logger.exception("slack webhook: file download failed")
+            return
+        for raw in raws:
+            try:
+                ep = conn.normalize(raw)
+            except Exception:  # noqa: BLE001
+                logger.exception(
+                    "slack webhook: file normalize failed for %s", raw.external_id
+                )
+                continue
+            if ep is None:
+                continue
+            if vis is not None:
+                ep.visibility = vis
+            await self._ingest_with_retries(
+                lambda ep=ep: conn.ingest_episode(ep),
+                f"{event_type}:file",
+                ep.idempotency_key,
+            )
+
     def _resolve_channel_visibility(self, channel_id: str):
         """N3: derive visibility from real channel privacy (poll parity).