microsoft-agents-hosting-slack 1.1.0.dev8__py3-none-any.whl

microsoft_agents/hosting/slack/__init__.py

@@ -0,0 +1,26 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .slack_agent_extension import SlackAgentExtension
+from .slack_helpers import (
+    create_conversation_id,
+    slack_bot_id_from_conversation_id,
+    slack_channel_id_from_conversation_id,
+    slack_decode,
+    slack_encode,
+    slack_team_id_from_conversation_id,
+    slack_thread_ts_from_conversation_id,
+)
+
+__all__ = [
+    "SlackAgentExtension",
+    "create_conversation_id",
+    "slack_bot_id_from_conversation_id",
+    "slack_channel_id_from_conversation_id",
+    "slack_decode",
+    "slack_encode",
+    "slack_team_id_from_conversation_id",
+    "slack_thread_ts_from_conversation_id",
+]

microsoft_agents/hosting/slack/_path_navigator.py

@@ -0,0 +1,108 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+
+def _parse_path(path: str) -> Optional[list[int | str]]:
+    """Tokenize a dot/bracket path into a list of segments.
+
+    Supports ``a.b.c``, ``a[0].b``, ``a[1][2]``. Integer brackets become ``int``
+    segments; everything else becomes a string segment. Returns ``None`` for
+    malformed bracket nesting.
+    """
+    if not path:
+        return []
+
+    segments: list[Any] = []
+    i = 0
+    start = 0
+
+    def emit() -> None:
+        nonlocal start
+        if start < i:
+            segments.append(path[start:i])
+        start = i + 1
+
+    while i < len(path):
+        ch = path[i]
+        if ch == ".":
+            emit()
+        elif ch == "[":
+            emit()
+            nesting = 1
+            i += 1
+            inner_start = i
+            while i < len(path):
+                c = path[i]
+                if c == "[":
+                    nesting += 1
+                elif c == "]":
+                    nesting -= 1
+                    if nesting == 0:
+                        break
+                i += 1
+            if nesting != 0:
+                return None
+            inner = path[inner_start:i]
+            if inner.isdigit() or (inner.startswith("-") and inner[1:].isdigit()):
+                segments.append(int(inner))
+            else:
+                segments.append(inner)
+            start = i + 1
+        i += 1
+
+    emit()
+    return segments
+
+
+def _resolve_segment(current: Any, segment: Any) -> Tuple[bool, Any]:
+    """Resolve one path segment against the current node.
+
+    Returns ``(found, value)``. ``found`` is False when the segment cannot be
+    resolved (missing key, out-of-range index, primitive node).
+    """
+    if current is None:
+        return False, None
+
+    if isinstance(segment, int):
+        if isinstance(current, (list, tuple)):
+            if -len(current) <= segment < len(current):
+                return True, current[segment]
+            return False, None
+        return False, None
+
+    # string segment → dict key (case-sensitive fast path, case-insensitive fallback)
+    if isinstance(current, dict):
+        if segment in current:
+            return True, current[segment]
+        lower = segment.lower()
+        for key, value in current.items():
+            if isinstance(key, str) and key.lower() == lower:
+                return True, value
+        return False, None
+
+    return False, None
+
+
+def try_get_path_value(data: Any, path: str) -> Tuple[bool, Any]:
+    """Walk ``path`` against ``data``. Returns ``(found, value)``."""
+    if data is None:
+        return False, None
+    if not path:
+        return True, data
+
+    segments = _parse_path(path)
+    if segments is None:
+        return False, None
+
+    current: Any = data
+    for segment in segments:
+        found, current = _resolve_segment(current, segment)
+        if not found:
+            return False, None
+    return True, current

microsoft_agents/hosting/slack/api/__init__.py

@@ -0,0 +1,42 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .action_payload import ActionPayload
+from .chunks import (
+    BlocksChunk,
+    Chunk,
+    MarkdownTextChunk,
+    SlackTaskStatus,
+    Source,
+    TaskDisplayMode,
+    TaskUpdateChunk,
+)
+from .event_content import EventContent
+from .event_envelope import EventEnvelope
+from .slack_api import SLACK_API_BASE, SlackApi
+from .slack_channel_data import SlackChannelData
+from .slack_model import SlackModel
+from .slack_response import SlackResponse, SlackResponseException
+from .slack_stream import SlackStream
+
+__all__ = [
+    "ActionPayload",
+    "BlocksChunk",
+    "Chunk",
+    "EventContent",
+    "EventEnvelope",
+    "MarkdownTextChunk",
+    "SLACK_API_BASE",
+    "SlackApi",
+    "SlackChannelData",
+    "SlackModel",
+    "SlackResponse",
+    "SlackResponseException",
+    "SlackStream",
+    "SlackTaskStatus",
+    "Source",
+    "TaskDisplayMode",
+    "TaskUpdateChunk",
+]

microsoft_agents/hosting/slack/api/action_payload.py

@@ -0,0 +1,26 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict
+
+from .slack_model import SlackModel
+
+
+class ActionPayload(SlackModel):
+    """
+    Interactive Message / Block Kit action payload from Slack. Sent when a user
+    clicks a button or interacts with a block element.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: Optional[str] = None
+    channel: Optional[Any] = None
+    message: Optional[Any] = None
+    actions: Optional[Any] = None

microsoft_agents/hosting/slack/api/chunks.py

@@ -0,0 +1,77 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+
+Streaming chunk shapes for Slack ``chat.appendStream`` / ``chat.stopStream``.
+See https://docs.slack.dev/reference/methods/chat.appendStream
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SlackTaskStatus:
+    """Status values accepted by :class:`TaskUpdateChunk`."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETE = "complete"
+    ERROR = "error"
+
+
+class TaskDisplayMode:
+    """Values accepted by ``chat.startStream``'s ``task_display_mode``."""
+
+    PLAN = "plan"
+    TIMELINE = "timeline"
+
+
+class Source(BaseModel):
+    """Citation/source attached to a :class:`TaskUpdateChunk`."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = "url"
+    url: str = ""
+    text: str = ""
+
+
+class MarkdownTextChunk(BaseModel):
+    """Append a chunk of markdown-formatted text to a Slack stream."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = Field(default="markdown_text", frozen=True)
+    text: str = ""
+
+
+class BlocksChunk(BaseModel):
+    """Append a chunk of Block Kit blocks to a Slack stream."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = Field(default="blocks", frozen=True)
+    blocks: list[Any] = Field(default_factory=list)
+
+
+class TaskUpdateChunk(BaseModel):
+    """Append a task-status update chunk to a Slack stream."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: str = Field(default="task_update", frozen=True)
+    id: str
+    title: str
+    status: str = SlackTaskStatus.IN_PROGRESS
+    details: Optional[str] = None
+    output: Optional[str] = None
+    sources: Optional[list[Source]] = None
+
+
+# Type alias for any chunk variant.
+Chunk = (
+    BaseModel  # all chunk classes are BaseModel subclasses with a `type` discriminator
+)

microsoft_agents/hosting/slack/api/event_content.py

@@ -0,0 +1,45 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import ConfigDict
+
+from .slack_model import SlackModel
+
+
+class EventContent(SlackModel):
+    """
+    The inner ``event`` object from a Slack Events API callback payload.
+
+    Slack calls this the "event content". Because event payloads vary so widely
+    by ``type``, every unmodelled field is preserved via Pydantic's
+    ``extra="allow"`` and is reachable through :meth:`SlackModel.get` using the
+    same snake_case names shown in the Slack docs.
+
+    See https://docs.slack.dev/reference/events
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    # ── Common event fields (https://docs.slack.dev/apis/events-api/#event-type-structure)
+    type: Optional[str] = None
+    event_ts: Optional[str] = None
+    user: Optional[str] = None
+    ts: Optional[str] = None
+    subtype: Optional[str] = None
+    channel: Optional[str] = None
+    channel_type: Optional[str] = None
+    team: Optional[str] = None
+
+    # ── message event fields ──
+    text: Optional[str] = None
+    client_msg_id: Optional[str] = None
+
+    # ── reaction_added / reaction_removed event fields ──
+    reaction: Optional[str] = None
+    item_user: Optional[str] = None

microsoft_agents/hosting/slack/api/event_envelope.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict, Field
+
+from .event_content import EventContent
+from .slack_model import SlackModel
+
+
+class EventEnvelope(SlackModel):
+    """
+    Outer envelope for a Slack Events API callback. Contains workspace, application,
+    and authorization context, plus the inner event payload (``event_content``).
+
+    See https://docs.slack.dev/apis/events-api/#callback-field.
+
+    Path navigation supports both the Slack JSON prefix ``event.`` and the Python
+    property prefix ``event_content.`` interchangeably::
+
+        envelope = SlackChannelData.from_activity(turn_context.activity).envelope
+        workspace_id = envelope.get("team_id")
+        channel      = envelope.get("event.channel")
+        block_type   = envelope.get("event.blocks[0].type")
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    token: Optional[str] = None
+    team_id: Optional[str] = None
+    context_team_id: Optional[str] = None
+    context_enterprise_id: Optional[str] = None
+    api_app_id: Optional[str] = None
+
+    # Python name `event_content` ↔ JSON field `event`
+    event_content: Optional[EventContent] = Field(default=None, alias="event")
+
+    type: Optional[str] = None
+    event_id: Optional[str] = None
+    event_time: Optional[int] = None
+    authorizations: Optional[Any] = None
+    is_ext_shared_channel: Optional[bool] = None
+    event_context: Optional[str] = None
+
+    def _normalize_path(self, path: str) -> str:
+        """Map the C# property alias ``event_content`` to JSON field ``event``."""
+        if path.lower() == "event_content":
+            return "event"
+        if path.lower().startswith("event_content."):
+            return "event" + path[len("event_content") :]
+        return path

microsoft_agents/hosting/slack/api/slack_api.py

@@ -0,0 +1,120 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from aiohttp import ClientSession, ClientTimeout
+from pydantic import BaseModel
+
+from .slack_response import SlackResponse, SlackResponseException
+
+SLACK_API_BASE = "https://slack.com/api"
+
+
+def _serialize_options(options: Any) -> str:
+    """Serialize the ``options`` argument to a JSON string suitable for Slack.
+
+    - ``None`` becomes ``"{}"``.
+    - A pre-built JSON string is returned as-is.
+    - A Pydantic model is dumped with ``exclude_none=True`` to match Slack's
+      tolerance of omitted fields and the C# implementation's null-stripping.
+    - Anything else is passed through :func:`json.dumps`, after recursively
+      removing ``None`` values from dicts/lists.
+    """
+    if options is None:
+        return "{}"
+    if isinstance(options, str):
+        return options
+    if isinstance(options, BaseModel):
+        return options.model_dump_json(by_alias=True, exclude_none=True)
+    return json.dumps(_strip_nones(options), ensure_ascii=False)
+
+
+def _strip_nones(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: _strip_nones(v) for k, v in value.items() if v is not None}
+    if isinstance(value, list):
+        return [_strip_nones(v) for v in value if v is not None]
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return value
+
+
+class SlackApi:
+    """
+    Async HTTP client for the Slack Web API.
+
+    Mirrors the C# ``SlackApi``: every call is a ``POST`` to
+    ``https://slack.com/api/{method}`` with a JSON body and an optional bearer
+    token. The response body is parsed into a :class:`SlackResponse`; a
+    :class:`SlackResponseException` is raised on a non-2xx HTTP status or when
+    Slack returns ``ok=false``.
+    """
+
+    def __init__(
+        self,
+        session: Optional[ClientSession] = None,
+        *,
+        base_url: str = SLACK_API_BASE,
+        request_timeout: float = 30.0,
+    ) -> None:
+        self._session = session
+        self._owns_session = session is None
+        self._base_url = base_url
+        self._timeout = ClientTimeout(total=request_timeout)
+
+    async def call(
+        self,
+        method: str,
+        options: Any = None,
+        token: str = "",
+    ) -> SlackResponse:
+        """Invoke a Slack Web API method.
+
+        :param method: The API method name (e.g. ``"chat.postMessage"``).
+        :param options: Request payload. May be ``None``, a JSON string, a
+            ``dict`` / ``list``, or a Pydantic model.
+        :param token: Bearer token. Sent as ``Authorization: Bearer {token}``
+            when non-empty.
+        :returns: The parsed :class:`SlackResponse`.
+        :raises ValueError: if ``method`` is empty or whitespace.
+        :raises SlackResponseException: on HTTP error or ``ok=false``.
+        """
+        if not method or not method.strip():
+            raise ValueError("method must be a non-empty string")
+
+        body = _serialize_options(options)
+        url = f"{self._base_url}/{method}"
+        headers = {"Content-Type": "application/json"}
+        if token and token.strip():
+            headers["Authorization"] = f"Bearer {token}"
+
+        session = self._session or ClientSession()
+        try:
+            async with session.post(
+                url, data=body, headers=headers, timeout=self._timeout
+            ) as response:
+                text = await response.text()
+                try:
+                    payload = json.loads(text) if text else {}
+                    data = SlackResponse.model_validate(payload)
+                except Exception as exc:
+                    raise SlackResponseException(
+                        f"Slack API error on {method} (HTTP {response.status}):\n{text}"
+                    ) from exc
+
+                if not response.ok or not data.ok:
+                    raise SlackResponseException(
+                        f"Slack API error on {method} (HTTP {response.status}):\n{text}",
+                        data,
+                    )
+
+                return data
+        finally:
+            if self._owns_session:
+                await session.close()

microsoft_agents/hosting/slack/api/slack_channel_data.py

@@ -0,0 +1,67 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .action_payload import ActionPayload
+from .event_envelope import EventEnvelope
+
+
+class SlackChannelData(BaseModel):
+    """
+    Data associated with a Slack channel activity, as delivered by Azure Bot
+    Service in :attr:`Activity.channel_data`.
+
+    Bot Service historically named the envelope property ``SlackMessage`` and
+    the API token ``ApiToken``; this model accepts both the PascalCase JSON
+    names (via aliases) and snake_case Python names.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    envelope: Optional[EventEnvelope] = Field(default=None, alias="SlackMessage")
+    payload: Optional[ActionPayload] = Field(default=None, alias="Payload")
+    api_token: Optional[str] = Field(default=None, alias="ApiToken")
+
+    @property
+    def channel(self) -> Optional[str]:
+        """Slack channel id, sourced from the envelope or action payload."""
+        if self.envelope is not None:
+            return self.envelope.get("event.channel")
+        if self.payload is not None:
+            return self.payload.get("channel")
+        return None
+
+    @property
+    def thread_ts(self) -> Optional[str]:
+        """Thread timestamp, sourced from the envelope event or payload message."""
+        if self.envelope is not None:
+            return self.envelope.get("event.thread_ts") or self.envelope.get("event.ts")
+        if self.payload is not None:
+            return self.payload.get("message.thread_ts") or self.payload.get(
+                "message.ts"
+            )
+        return None
+
+    @classmethod
+    def from_activity(cls, activity: Any) -> "SlackChannelData":
+        """Build a :class:`SlackChannelData` from an Activity's ``channel_data``.
+
+        Accepts ``Activity.channel_data`` that is either a ``dict`` (typical for
+        deserialized incoming requests) or already a :class:`SlackChannelData`.
+        Returns an empty instance when ``channel_data`` is missing.
+        """
+        data = getattr(activity, "channel_data", None) if activity is not None else None
+        if data is None:
+            return cls()
+        if isinstance(data, cls):
+            return data
+        if isinstance(data, BaseModel):
+            data = data.model_dump(mode="json", by_alias=True)
+        return cls.model_validate(data)

microsoft_agents/hosting/slack/api/slack_model.py

@@ -0,0 +1,73 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type, TypeVar, overload
+
+from pydantic import BaseModel, ConfigDict
+
+from .._path_navigator import try_get_path_value
+
+T = TypeVar("T")
+
+
+class SlackModel(BaseModel):
+    """
+    Base class for Slack model objects that expose dot-notation path navigation via
+    :meth:`get` and :meth:`try_get`.
+
+    Subclasses are Pydantic models with ``extra="allow"`` so any unmodelled fields
+    from Slack are preserved and reachable by path. The path navigator walks the
+    serialized form (``by_alias=True``), so paths use the same snake_case names
+    that appear in the Slack docs.
+
+    Subclasses whose JSON field names differ from their Python property names
+    override :meth:`_normalize_path` to remap the alias before navigation (e.g.
+    :class:`EventEnvelope` maps ``event_content`` → ``event``).
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    def _data(self) -> dict[str, Any]:
+        """Return the serialized form used for path navigation. Subclasses with
+        their own backing store may override this."""
+        return self.model_dump(mode="json", by_alias=True, exclude_none=False)
+
+    def _normalize_path(self, path: str) -> str:
+        """Remap caller-supplied path before navigation. Default: identity."""
+        return path
+
+    @overload
+    def get(self, path: str) -> Any: ...
+    @overload
+    def get(self, path: str, default: T) -> T: ...
+    @overload
+    def get(self, path: str, type_: Type[T]) -> T: ...
+    @overload
+    def get(self, path: str, default: T, type_: Type[T]) -> T: ...
+
+    def get(
+        self, path: str, default: Optional[T] = None, type_: Type[T] = None
+    ) -> Optional[T]:
+        """Get a value at the dot-notation ``path``. Supports dot separators and
+        bracket array indexing (e.g. ``"message.attachments[0].text"``). Returns
+        ``default`` (or ``None``) when the path does not exist.
+
+        ``type_`` is accepted for API symmetry with the C# generic ``Get<T>`` but
+        is not enforced at runtime — Pydantic models keep values in their
+        deserialized shape.
+        """
+        if not path:
+            return self._data()
+
+        found, value = try_get_path_value(self._data(), self._normalize_path(path))
+        return value if found else default
+
+    def try_get(self, path: str) -> tuple[bool, Any]:
+        """Like :meth:`get`, but returns ``(found, value)``."""
+        if not path:
+            return True, self._data()
+        return try_get_path_value(self._data(), self._normalize_path(path))

microsoft_agents/hosting/slack/api/slack_response.py

@@ -0,0 +1,42 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import ConfigDict
+
+from .slack_model import SlackModel
+
+
+class SlackResponse(SlackModel):
+    """
+    Response from a Slack Web API call.
+
+    Named properties cover the fields common to every Slack response. Any
+    additional fields returned by a specific method are accessible via
+    :meth:`SlackModel.get` using dot-notation paths::
+
+        response = await slack_api.call("chat.postMessage", options, token)
+        channel = response.get("channel")
+        msg_ts  = response.get("message.ts")
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    ok: bool = False
+    error: Optional[str] = None
+    warning: Optional[str] = None
+    ts: Optional[str] = None
+    response_metadata: Optional[Any] = None
+
+
+class SlackResponseException(Exception):
+    """Raised when a Slack Web API call returns a non-2xx status or ``ok=false``."""
+
+    def __init__(self, message: str, response: Optional[SlackResponse] = None) -> None:
+        super().__init__(message)
+        self.response = response

microsoft_agents/hosting/slack/api/slack_stream.py

@@ -0,0 +1,160 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel
+
+from .chunks import MarkdownTextChunk, TaskDisplayMode
+from .slack_api import SlackApi
+
+
+def _chunk_to_dict(chunk: Any) -> Any:
+    if isinstance(chunk, BaseModel):
+        return chunk.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return chunk
+
+
+class SlackStream:
+    """
+    Incrementally builds and updates a single Slack message via
+    ``chat.startStream`` / ``chat.appendStream`` / ``chat.stopStream``.
+
+    Not thread-safe; concurrent operations on the same instance produce
+    undefined behavior. Call :meth:`start` before :meth:`append`, and
+    :meth:`stop` when finished.
+    """
+
+    def __init__(
+        self,
+        slack_api: SlackApi,
+        channel: str,
+        thread_ts: str,
+        token: str,
+    ) -> None:
+        self._slack_api = slack_api
+        self._channel = channel
+        self._thread_ts = thread_ts
+        self._token = token
+        self._message_ts: Optional[str] = None
+
+    async def start(
+        self, task_display_mode: str = TaskDisplayMode.PLAN
+    ) -> "SlackStream":
+        """Start a new Slack stream.
+
+        See https://docs.slack.dev/reference/methods/chat.startStream
+        """
+        result = await self._slack_api.call(
+            "chat.startStream",
+            {
+                "channel": self._channel,
+                "thread_ts": self._thread_ts,
+                "task_display_mode": task_display_mode,
+            },
+            self._token,
+        )
+        self._message_ts = result.ts
+        return self
+
+    async def append(
+        self,
+        chunk_or_text: Union[str, BaseModel, list[BaseModel]],
+    ) -> "SlackStream":
+        """Append one or more chunks to the stream.
+
+        Accepts a plain string (wrapped in a :class:`MarkdownTextChunk`), a
+        single chunk model, or an iterable of chunk models.
+
+        See https://docs.slack.dev/reference/methods/chat.appendStream
+        """
+        if self._message_ts is None:
+            raise ValueError(
+                "SlackStream.start() must be called before append() "
+                "to establish the message timestamp required by Slack's API"
+            )
+
+        if chunk_or_text is None:
+            raise ValueError("chunk_or_text must not be None")
+
+        if isinstance(chunk_or_text, str):
+            chunks: list[Any] = [MarkdownTextChunk(text=chunk_or_text)]
+        elif isinstance(chunk_or_text, BaseModel):
+            chunks = [chunk_or_text]
+        else:
+            chunks = list(chunk_or_text)
+
+        if not chunks:
+            return self
+
+        await self._slack_api.call(
+            "chat.appendStream",
+            {
+                "channel": self._channel,
+                "ts": self._message_ts,
+                "thread_ts": self._thread_ts,
+                "chunks": [_chunk_to_dict(c) for c in chunks],
+            },
+            self._token,
+        )
+        return self
+
+    async def stop(
+        self,
+        chunks: Optional[list[BaseModel]] = None,
+        blocks: Union[str, list[Any], dict, None] = None,
+    ) -> None:
+        """Stop the active stream, optionally finalizing with chunks and/or
+        Block Kit blocks.
+
+        ``blocks`` may be a JSON-array string, a JSON-object string containing
+        a ``"blocks"`` array, a Python list of block dicts, or a dict with a
+        top-level ``"blocks"`` key.
+
+        See https://docs.slack.dev/reference/methods/chat.stopStream
+        """
+        if not self._message_ts:
+            return
+
+        resolved_blocks = self._resolve_blocks(blocks)
+        resolved_chunks = (
+            [_chunk_to_dict(c) for c in chunks] if chunks is not None else None
+        )
+
+        body: dict[str, Any] = {
+            "channel": self._channel,
+            "ts": self._message_ts,
+            "thread_ts": self._thread_ts,
+        }
+        if resolved_chunks is not None:
+            body["chunks"] = resolved_chunks
+        if resolved_blocks is not None:
+            body["blocks"] = resolved_blocks
+
+        await self._slack_api.call("chat.stopStream", body, self._token)
+
+    @staticmethod
+    def _resolve_blocks(blocks: Any) -> Optional[list[Any]]:
+        if blocks is None:
+            return None
+        if isinstance(blocks, str):
+            try:
+                parsed = json.loads(blocks)
+            except json.JSONDecodeError as exc:
+                raise ValueError("blocks string is not valid JSON") from exc
+            return SlackStream._resolve_blocks(parsed)
+        if isinstance(blocks, dict):
+            if "blocks" not in blocks or not isinstance(blocks["blocks"], list):
+                raise ValueError("blocks object must contain a 'blocks' array property")
+            return blocks["blocks"]
+        if isinstance(blocks, list):
+            return blocks
+        raise ValueError(
+            "blocks must be a JSON array, a JSON object with a 'blocks' array, "
+            "or a string encoding either"
+        )

microsoft_agents/hosting/slack/slack_agent_extension.py

@@ -0,0 +1,202 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Generic, Optional, Pattern, TypeVar, Union
+
+from microsoft_agents.activity import ActivityTypes, Channels
+from microsoft_agents.hosting.core import TurnContext
+from microsoft_agents.hosting.core.app import AgentApplication, RouteRank
+from microsoft_agents.hosting.core.app.state import TurnState
+
+from .api import (
+    SlackApi,
+    SlackChannelData,
+    SlackResponse,
+    SlackStream,
+)
+
+StateT = TypeVar("StateT", bound=TurnState)
+
+TextSelector = Union[str, Pattern[str], None]
+
+_SLACK_API_SERVICE_KEY = "microsoft_agents.hosting.slack.SlackApi"
+
+
+def _matches_text(selector: TextSelector, text: Optional[str]) -> bool:
+    if selector is None:
+        return True
+    if text is None:
+        return False
+    if isinstance(selector, Pattern):
+        return re.fullmatch(selector, text) is not None
+    return text == selector
+
+
+def _is_slack_channel(context: TurnContext) -> bool:
+    return context.activity.channel_id == Channels.slack.value
+
+
+class SlackAgentExtension(Generic[StateT]):
+    """
+    Slack-specific route registration and helpers for an
+    :class:`~microsoft_agents.hosting.core.app.AgentApplication`.
+
+    Usage::
+
+        from microsoft_agents.hosting.slack import SlackAgentExtension
+        from microsoft_agents.hosting.slack.api import SlackChannelData
+
+        app = AgentApplication(options)
+        slack = SlackAgentExtension(app)
+
+        @slack.on_message("hello")
+        async def greet(context, state):
+            channel_data = SlackChannelData.from_activity(context.activity)
+            await slack.call(
+                context,
+                "chat.postMessage",
+                {
+                    "channel": channel_data.channel,
+                    "text": f"Hi, {context.activity.from_property.name}!",
+                },
+                token=channel_data.api_token,
+            )
+    """
+
+    def __init__(
+        self,
+        application: AgentApplication[StateT],
+        *,
+        slack_api: Optional[SlackApi] = None,
+    ) -> None:
+        self._app = application
+        self._slack_api = slack_api or SlackApi()
+
+    @property
+    def slack_api(self) -> SlackApi:
+        """The shared :class:`SlackApi` used by :meth:`call` and :meth:`create_stream`."""
+        return self._slack_api
+
+    # ── direct Slack API access ────────────────────────────────────────────
+
+    async def call(
+        self,
+        turn_context: TurnContext,
+        method: str,
+        options: Any = None,
+        token: str = "",
+    ) -> SlackResponse:
+        """Invoke a Slack Web API method, preferring a per-turn :class:`SlackApi`
+        if one has been cached on ``turn_context.services``."""
+        api = self._slack_api
+        if turn_context is not None and turn_context.has(_SLACK_API_SERVICE_KEY):
+            api = turn_context.get(_SLACK_API_SERVICE_KEY)  # type: ignore[assignment]
+        return await api.call(method, options, token)
+
+    async def create_stream(
+        self,
+        turn_context: TurnContext,
+        thread_ts: Optional[str] = None,
+    ) -> SlackStream:
+        """Create and start a :class:`SlackStream` for the current Slack thread."""
+        channel_data = SlackChannelData.from_activity(turn_context.activity)
+        if channel_data.envelope is None:
+            raise ValueError(
+                "create_stream requires a Slack event envelope on the activity"
+            )
+        resolved_thread_ts = thread_ts or channel_data.envelope.get("event.ts")
+        api = self._slack_api
+        if turn_context.has(_SLACK_API_SERVICE_KEY):
+            api = turn_context.get(_SLACK_API_SERVICE_KEY)  # type: ignore[assignment]
+        stream = SlackStream(
+            api,
+            channel_data.envelope.get("event.channel"),
+            resolved_thread_ts,
+            channel_data.api_token or "",
+        )
+        return await stream.start()
+
+    # ── message routes ─────────────────────────────────────────────────────
+
+    def on_message(
+        self,
+        select: TextSelector = None,
+        *,
+        auth_handlers: Optional[list[str]] = None,
+        rank: RouteRank = RouteRank.DEFAULT,
+    ) -> Callable:
+        """Register a handler for Slack message activities.
+
+        When ``select`` is ``None``, every Slack message matches; otherwise the
+        activity's ``text`` must equal ``select`` (string) or fully match it
+        (compiled regex).
+
+        ``rank`` defaults to :attr:`RouteRank.DEFAULT`; when ``select`` is
+        ``None`` the rank is downgraded to :attr:`RouteRank.LAST` so explicit
+        text routes win — matching the C# behavior.
+        """
+        effective_rank = (
+            RouteRank.LAST if (select is None and rank == RouteRank.DEFAULT) else rank
+        )
+
+        def __selector(context: TurnContext) -> bool:
+            if context.activity.type != ActivityTypes.message or not _is_slack_channel(
+                context
+            ):
+                return False
+            return _matches_text(select, context.activity.text)
+
+        def __call(func: Callable) -> Callable:
+            self._app.add_route(
+                __selector,
+                func,
+                rank=effective_rank,
+                auth_handlers=auth_handlers,
+            )
+            return func
+
+        return __call
+
+    # ── event routes ───────────────────────────────────────────────────────
+
+    def on_event(
+        self,
+        event_name: TextSelector = None,
+        *,
+        auth_handlers: Optional[list[str]] = None,
+        rank: RouteRank = RouteRank.DEFAULT,
+    ) -> Callable:
+        """Register a handler for Slack event activities.
+
+        When ``event_name`` is ``None``, every Slack event matches; otherwise
+        the activity's ``name`` must equal it (string) or fully match it
+        (compiled regex).
+        """
+        effective_rank = (
+            RouteRank.LAST
+            if (event_name is None and rank == RouteRank.DEFAULT)
+            else rank
+        )
+
+        def __selector(context: TurnContext) -> bool:
+            if context.activity.type != ActivityTypes.event or not _is_slack_channel(
+                context
+            ):
+                return False
+            return _matches_text(event_name, context.activity.name)
+
+        def __call(func: Callable) -> Callable:
+            self._app.add_route(
+                __selector,
+                func,
+                rank=effective_rank,
+                auth_handlers=auth_handlers,
+            )
+            return func
+
+        return __call

microsoft_agents/hosting/slack/slack_helpers.py

@@ -0,0 +1,61 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def slack_encode(value: Optional[str]) -> Optional[str]:
+    """Encode text for Slack. See https://api.slack.com/docs/message-formatting."""
+    if value is None:
+        return None
+    return value.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def slack_decode(value: Optional[str]) -> Optional[str]:
+    """Decode text from Slack. See https://api.slack.com/docs/message-formatting."""
+    if value is None:
+        return None
+    return value.replace("&amp;", "&").replace("&lt;", "<").replace("&gt;", ">")
+
+
+def create_conversation_id(
+    slack_bot_id: str,
+    slack_team_id: str,
+    slack_channel_id: str,
+    slack_thread_ts: Optional[str] = None,
+) -> str:
+    """Compose a Bot Service-compatible conversation id from Slack identifiers."""
+    if slack_thread_ts is None:
+        return f"{slack_bot_id}:{slack_team_id}:{slack_channel_id}"
+    return f"{slack_bot_id}:{slack_team_id}:{slack_channel_id}:{slack_thread_ts}"
+
+
+def _from_conversation_id(conversation_id: str, pos: int) -> Optional[str]:
+    if conversation_id is None or not conversation_id.strip():
+        raise ValueError("conversation_id must be a non-empty string")
+    parts = conversation_id.split(":")
+    if len(parts) not in (3, 4):
+        raise ValueError(f"Invalid conversation_id: {conversation_id}")
+    if pos >= len(parts):
+        return None
+    return parts[pos]
+
+
+def slack_bot_id_from_conversation_id(conversation_id: str) -> Optional[str]:
+    return _from_conversation_id(conversation_id, 0)
+
+
+def slack_team_id_from_conversation_id(conversation_id: str) -> Optional[str]:
+    return _from_conversation_id(conversation_id, 1)
+
+
+def slack_channel_id_from_conversation_id(conversation_id: str) -> Optional[str]:
+    return _from_conversation_id(conversation_id, 2)
+
+
+def slack_thread_ts_from_conversation_id(conversation_id: str) -> Optional[str]:
+    return _from_conversation_id(conversation_id, 3)

microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-hosting-slack
+Version: 1.1.0.dev8
+Summary: Integration library for Microsoft Agents with Slack
+Author: Microsoft Corporation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: microsoft-agents-hosting-core==1.1.0.dev8
+Requires-Dist: aiohttp>=3.11.11
+Dynamic: license-file
+Dynamic: requires-dist
+
+# Microsoft Agents Hosting - Slack
+
+[![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-hosting-slack)](https://pypi.org/project/microsoft-agents-hosting-slack/)
+
+Integration library for building Slack agents using the Microsoft 365 Agents SDK. Provides direct-to-Slack responses (the full Slack Web API surface, beyond what Azure Bot Service exposes), a typed `SlackChannelData` envelope with dot-notation property access, and a `SlackStream` helper for `chat.startStream` / `chat.appendStream` / `chat.stopStream`.
+
+## Installation
+
+```bash
+pip install microsoft-agents-hosting-slack
+```
+
+## Usage
+
+```python
+from microsoft_agents.hosting.core.app import AgentApplication
+from microsoft_agents.hosting.slack import SlackAgentExtension
+from microsoft_agents.hosting.slack.api import SlackChannelData
+
+app = AgentApplication(options)
+slack = SlackAgentExtension(app)
+
+@slack.on_message()
+async def on_slack_message(context, state):
+    channel_data = SlackChannelData.from_activity(context.activity)
+    await slack.call(
+        context,
+        "chat.postMessage",
+        {
+            "channel": channel_data.get("event.channel"),
+            "text": f"You said: {context.activity.text}",
+        },
+        token=channel_data.api_token,
+    )
+```
+
+## Key Classes
+
+- **`SlackAgentExtension`** — registers Slack-channel-scoped message/event handlers; exposes `call(...)` and `create_stream(...)`.
+- **`SlackChannelData`** — typed wrapper around Bot Service's Slack channel-data payload with `get(path)` / `try_get(path)` accessors.
+- **`SlackApi`** — async HTTP client for the Slack Web API.
+- **`SlackStream`** — wraps Slack's streaming methods for incremental message updates.
+- **`SlackHelpers`** — encode/decode and conversation-id parsing utilities.
+
+# Quick Links
+
+- 📦 [All SDK Packages on PyPI](https://pypi.org/search/?q=microsoft-agents)
+- 📖 [Complete Documentation](https://aka.ms/agents)
+- 🐛 [Report Issues](https://github.com/microsoft/Agents-for-python/issues)

microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/RECORD

@@ -0,0 +1,19 @@
+microsoft_agents/hosting/slack/__init__.py,sha256=cyaF_M7-BcGs-WmGWWMF7gqOXsQPe2qPbzjxrawcAFw,697
+microsoft_agents/hosting/slack/_path_navigator.py,sha256=fUgaOVipjH-ad8mqaokNb8qmB_XjWZcFE1B-QfJcETk,3048
+microsoft_agents/hosting/slack/slack_agent_extension.py,sha256=vUx80m6Z58Xb14hw8RiYAxtTsKxALp3hmmLvRFdwzCg,6982
+microsoft_agents/hosting/slack/slack_helpers.py,sha256=jJ_P8hNOR5nOhiKr5gVQU0lfKpBsvCzxUOrLrXttdLs,2082
+microsoft_agents/hosting/slack/api/__init__.py,sha256=6ORph89cJLGgeZioNOJHRyjZWxFdhUZf6bOLuAF45zU,977
+microsoft_agents/hosting/slack/api/action_payload.py,sha256=4uW49YYsLaPt1RcVFcNyA-v4398-2KgU28rvZySEiH8,627
+microsoft_agents/hosting/slack/api/chunks.py,sha256=3A49eF8gGMovl0dfVNEakRs5klUtmnA84WPQ8RbWD2o,1995
+microsoft_agents/hosting/slack/api/event_content.py,sha256=nTL68Ues16GaASZ0754adcdTNuvboVS9oc0uzFA_r7c,1367
+microsoft_agents/hosting/slack/api/event_envelope.py,sha256=HaH4oRonA59GMDRgvT7V0b8HOSDbfSLz74bbq2mXoS4,1920
+microsoft_agents/hosting/slack/api/slack_api.py,sha256=bUyghKap9tR-BbNWEOhuV7Fhf_q7A0BcYHYFN017OLI,4288
+microsoft_agents/hosting/slack/api/slack_channel_data.py,sha256=QQieLewDBH7QPaBZahs9qIDBz7AjmWwPUlYIGUBQIWg,2506
+microsoft_agents/hosting/slack/api/slack_model.py,sha256=wVonGP3Fl0zHjl8dsZx2cRFzG5GENM7nSR3UMMJdggY,2692
+microsoft_agents/hosting/slack/api/slack_response.py,sha256=_hNOSxeovDlBd5tnwEqYnZ3fM3f122Gas5xS6p87Tf0,1207
+microsoft_agents/hosting/slack/api/slack_stream.py,sha256=Icsu7V7gJvZQOmoUXX3ALf-lB4DlWaXAH8Z2NyL-ip8,5132
+microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/METADATA,sha256=m1uaw-BaQ7xEXO6aOpvdftHHqfVvwuqDURWFCBLvHWQ,2832
+microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
+microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/RECORD,,

microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

microsoft_agents_hosting_slack-1.1.0.dev8.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents