python-slack-agents 0.6.1__tar.gz → 0.6.2__tar.gz

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/AGENTS.md

@@ -113,8 +113,10 @@ The PyPI deployment requires manual approval in the GitHub Actions UI. Do NOT pu
 
 ## Style
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full coding and commit conventions.
+
 - Python 3.12+, line length 100
 - Ruff rules: E, F, I (errors, pyflakes, isort)
 - Keep it simple. Minimal abstractions, no unnecessary indirection.
 - Commit messages: Conventional Commits — `feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`. Lowercase, imperative, under 72 chars.
-- **Always propose the commit message and wait for explicit user approval before committing or pushing.** Never commit or push autonomously.
+- **NEVER run `git commit` or `git push` without explicit user approval.** Always propose the commit message and file list, then STOP and wait for the user to say "go", "commit", "yes", or similar. This is non-negotiable — even if the user says "prepare a release" or "let's commit", you must present the plan and wait. "Prepare" ≠ "execute".

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-03-19
+
+### Added
+
+- Canvas user-level authorization — tools enforce requesting user's access level via `files.info` metadata
+- Canvas file importer (`application/vnd.slack-docs`) — users can attach canvases to messages
+- `file_id` field on `InputFile` — file import pipeline now passes Slack file IDs to handlers
+- `org_access` parameter on `canvas_access_add` for workspace-wide access
+
+### Changed
+
+- Canvas tool descriptions instruct the LLM to guide users to attach canvases via Slack's + button (never ask for IDs)
+- Canvas tool errors now return structured JSON instead of plain text
+
+### Removed
+
+- `canvas_list` tool (scaling concern with batch `files.info`; users discover canvases via Slack UI)
+- `channel_id` parameter from `canvas_create` (standalone canvases only)
+- `channel_ids` parameter from `canvas_access_add` and `canvas_access_remove`
+
 ## [0.6.1] - 2026-03-19
 
 ### Added

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-slack-agents
-Version: 0.6.1
+Version: 0.6.2
 Summary: A Python framework for deploying AI agents as Slack bots
 Project-URL: Homepage, https://github.com/CompareNetworks/python-slack-agents
 Project-URL: Repository, https://github.com/CompareNetworks/python-slack-agents
@@ -329,13 +329,13 @@ If you're an AI agent or coding assistant, see [`llms-full.txt`](https://raw.git
 
 ## Related Projects
 
-If this framework isn't the right fit, here are some good alternatives:
+Other projects in this space:
 
 - **[Bolt for Python](https://github.com/slackapi/bolt-python)** — The official Slack SDK. python-slack-agents uses it internally. Use Bolt directly if you want full control over Slack interactions without an agent abstraction.
-- **[Slack Machine](https://github.com/DonDebonair/slack-machine)** — A mature Slack bot framework with a great plugin system for traditional chatops. No AI/LLM layer, but solid if you don't need agents.
-- **[bolt-python-ai-chatbot](https://github.com/slack-samples/bolt-python-ai-chatbot)** — Official Slack sample app for AI chatbots. Good starting point if you want to build from scratch rather than use a framework.
-- **[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)**, **[Pydantic AI](https://github.com/pydantic/pydantic-ai)**, **[MCP Agent](https://github.com/lastmile-ai/mcp-agent)** — Powerful general-purpose agent frameworks. None include Slack integration, but if you already use one and want to wire it up to Slack yourself, they're excellent.
-- **[slack-mcp-client](https://github.com/tuannvm/slack-mcp-client)** — A Go application bridging Slack and MCP servers. Deployed app rather than a library, but well-built if you prefer Go.
+- **[bolt-python-ai-chatbot](https://github.com/slack-samples/bolt-python-ai-chatbot)** — Official Slack sample app for AI chatbots. A starting point if you want to build from scratch rather than use a framework.
+- **[bolt-python-assistant-template](https://github.com/slack-samples/bolt-python-assistant-template)** — Official Slack template for building Agents & Assistants with Bolt and OpenAI.
+- **[langgraph-messaging-integrations](https://github.com/langchain-ai/langgraph-messaging-integrations)** — Connects LangGraph agents to Slack and other messaging platforms.
+- **[slack-mcp-client](https://github.com/tuannvm/slack-mcp-client)** — A Go application bridging Slack and MCP servers. Deployed app rather than a library.
 
 ## Disclaimer
 

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/README.md

@@ -283,13 +283,13 @@ If you're an AI agent or coding assistant, see [`llms-full.txt`](https://raw.git
 
 ## Related Projects
 
-If this framework isn't the right fit, here are some good alternatives:
+Other projects in this space:
 
 - **[Bolt for Python](https://github.com/slackapi/bolt-python)** — The official Slack SDK. python-slack-agents uses it internally. Use Bolt directly if you want full control over Slack interactions without an agent abstraction.
-- **[Slack Machine](https://github.com/DonDebonair/slack-machine)** — A mature Slack bot framework with a great plugin system for traditional chatops. No AI/LLM layer, but solid if you don't need agents.
-- **[bolt-python-ai-chatbot](https://github.com/slack-samples/bolt-python-ai-chatbot)** — Official Slack sample app for AI chatbots. Good starting point if you want to build from scratch rather than use a framework.
-- **[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)**, **[Pydantic AI](https://github.com/pydantic/pydantic-ai)**, **[MCP Agent](https://github.com/lastmile-ai/mcp-agent)** — Powerful general-purpose agent frameworks. None include Slack integration, but if you already use one and want to wire it up to Slack yourself, they're excellent.
-- **[slack-mcp-client](https://github.com/tuannvm/slack-mcp-client)** — A Go application bridging Slack and MCP servers. Deployed app rather than a library, but well-built if you prefer Go.
+- **[bolt-python-ai-chatbot](https://github.com/slack-samples/bolt-python-ai-chatbot)** — Official Slack sample app for AI chatbots. A starting point if you want to build from scratch rather than use a framework.
+- **[bolt-python-assistant-template](https://github.com/slack-samples/bolt-python-assistant-template)** — Official Slack template for building Agents & Assistants with Bolt and OpenAI.
+- **[langgraph-messaging-integrations](https://github.com/langchain-ai/langgraph-messaging-integrations)** — Connects LangGraph agents to Slack and other messaging platforms.
+- **[slack-mcp-client](https://github.com/tuannvm/slack-mcp-client)** — A Go application bridging Slack and MCP servers. Deployed app rather than a library.
 
 ## Disclaimer
 

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/agents/kitchen-sink/config.yaml

@@ -95,13 +95,21 @@ tools:
       # - "export_csv"
       # - "export_pptx"
 
-  # Slack canvases (create, read, edit, list, delete)
+  # Slack canvases (create, read, update, delete + access management)
   # Requires Slack scopes: canvases:read, canvases:write, files:read
+  # Enforces user-level authorization — agent acts as delegate for the requesting user
   # canvas:
   #   type: slack_agents.tools.canvas
   #   bot_token: "{SLACK_BOT_TOKEN}"
   #   allowed_functions: [".*"]
 
+  # Canvas file importer — reads canvases attached to messages
+  # Requires Slack scopes: canvases:read, files:read
+  # canvas-importer:
+  #   type: slack_agents.tools.canvas_importer
+  #   bot_token: "{SLACK_BOT_TOKEN}"
+  #   allowed_functions: [".*"]
+
   # Per-user memory backed by Slack canvases
   # Remembers user preferences and context across conversations.
   # Requires Slack scopes: canvases:read, canvases:write, files:read

python_slack_agents-0.6.2/docs/canvas.md

@@ -0,0 +1,118 @@
+# Canvas Tool
+
+The canvas tool lets your agent create, read, update, and delete [Slack canvases](https://slack.com/features/canvas) — rich documents that live inside Slack. It exposes a simple file-like API: no section IDs or low-level operations needed.
+
+## Setup
+
+### 1. Add Slack scopes
+
+In your Slack app settings (**OAuth & Permissions → Scopes → Bot Token Scopes**), add:
+
+| Scope | Purpose |
+|-------|---------|
+| `canvases:read` | Read canvas content |
+| `canvases:write` | Create, update, delete canvases and manage access |
+| `files:read` | Read canvas content and check user access (uses `files.info` API) |
+
+After adding scopes, reinstall the app to your workspace.
+
+### 2. Configure the tool
+
+Add the canvas tool to your agent's `config.yaml`:
+
+```yaml
+tools:
+  canvas:
+    type: slack_agents.tools.canvas
+    bot_token: "{SLACK_BOT_TOKEN}"
+    allowed_functions: [".*"]   # all canvas tools
+```
+
+To expose only specific tools:
+
+```yaml
+    allowed_functions:
+      - "canvas_create"
+      - "canvas_get"
+      - "canvas_update"
+```
+
+### 3. Canvas file importer (optional)
+
+To let users attach canvases to messages and have the agent read them automatically, add the canvas importer:
+
+```yaml
+tools:
+  canvas-importer:
+    type: slack_agents.tools.canvas_importer
+    bot_token: "{SLACK_BOT_TOKEN}"
+    allowed_functions: [".*"]
+```
+
+When a user attaches a canvas (mimetype `application/vnd.slack-docs`) to a message, the importer reads its markdown content via the Slack API and includes it in the conversation context. Authorization is enforced — the agent only reads canvases the requesting user can access.
+
+## Authorization model
+
+All canvas operations enforce **user-level permissions**. The agent acts as a delegate for the requesting user — it will not access canvases the user can't access themselves.
+
+Access is resolved from `files.info` metadata (no extra storage or scopes needed):
+
+| Check | Source field |
+|-------|-------------|
+| Is user the creator? | `user` / `canvas_creator_id` |
+| Per-user access | `dm_mpdm_users_with_file_access` |
+| Workspace-wide access | `org_or_workspace_access` |
+
+**Access levels** (higher includes lower): `owner` > `write` > `read`
+
+**Required access per tool:**
+
+| Tool | Required |
+|------|----------|
+| `canvas_create` | — (no existing canvas) |
+| `canvas_get` | read |
+| `canvas_update` | write |
+| `canvas_delete` | owner |
+| `canvas_access_get` | read |
+| `canvas_access_add` | owner |
+| `canvas_access_remove` | owner |
+
+If the user lacks sufficient access, the tool returns an error message explaining what access level is needed.
+
+## Canvas content format
+
+Canvas content is **markdown**. Supported elements:
+
+- Headings (`#`, `##`, `###`)
+- Bullet and numbered lists
+- Tables
+- Code blocks
+- Block quotes
+- Links
+- Mentions (`<@U1234567890>`)
+- Unfurls / embeds (`![](URL)`)
+
+Block Kit is **not** supported in canvases.
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `canvas_create` | Create a standalone canvas with title + content. |
+| `canvas_get` | Get a canvas by ID. Returns title, full markdown content, and permalink. |
+| `canvas_update` | Update a canvas — replace content, rename title, or both. |
+| `canvas_delete` | Permanently delete a canvas. |
+| `canvas_access_get` | Get sharing/access info for a canvas. |
+| `canvas_access_add` | Grant read/write/owner access to users. Optionally set `org_access` for workspace-wide access. |
+| `canvas_access_remove` | Remove access for users. |
+
+## Example usage
+
+**Create a canvas:**
+> "Create a canvas titled 'Q1 Roadmap' with our milestone list"
+
+**Read and update a canvas:**
+> "Get the canvas F12345 and update it with the latest status"
+
+**Share a canvas with specific users:**
+> "Give users U123 and U456 write access to canvas F12345"

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/llms-full.txt

@@ -602,7 +602,7 @@ Any extra keys beyond `type` are passed as keyword arguments to the `Provider` c
 
 # Canvas Tool
 
-The canvas tool lets your agent create, read, update, list, and delete [Slack canvases](https://slack.com/features/canvas) — rich documents that live inside Slack. It exposes a simple file-like API: no section IDs or low-level operations needed.
+The canvas tool lets your agent create, read, update, and delete [Slack canvases](https://slack.com/features/canvas) — rich documents that live inside Slack. It exposes a simple file-like API: no section IDs or low-level operations needed.
 
 ## Setup
 
@@ -612,9 +612,9 @@ In your Slack app settings (**OAuth & Permissions → Scopes → Bot Token Scope
 
 | Scope | Purpose |
 |-------|---------|
-| `canvases:read` | Read canvas content and list canvases |
+| `canvases:read` | Read canvas content |
 | `canvases:write` | Create, update, delete canvases and manage access |
-| `files:read` | List canvases and read content (uses `files.list` / `files.info` APIs) |
+| `files:read` | Read canvas content and check user access (uses `files.info` API) |
 
 After adding scopes, reinstall the app to your workspace.
 
@@ -637,13 +637,49 @@ To expose only specific tools:
       - "canvas_create"
       - "canvas_get"
       - "canvas_update"
-      - "canvas_list"
 ```
 
-## Slack plan requirements
+### 3. Canvas file importer (optional)
 
-- **Free plans**: 1 canvas per channel/DM. `canvas_create` requires `channel_id`.
-- **Paid plans** (Pro, Business+, Enterprise Grid): Unlimited canvases. `channel_id` is optional.
+To let users attach canvases to messages and have the agent read them automatically, add the canvas importer:
+
+```yaml
+tools:
+  canvas-importer:
+    type: slack_agents.tools.canvas_importer
+    bot_token: "{SLACK_BOT_TOKEN}"
+    allowed_functions: [".*"]
+```
+
+When a user attaches a canvas (mimetype `application/vnd.slack-docs`) to a message, the importer reads its markdown content via the Slack API and includes it in the conversation context. Authorization is enforced — the agent only reads canvases the requesting user can access.
+
+## Authorization model
+
+All canvas operations enforce **user-level permissions**. The agent acts as a delegate for the requesting user — it will not access canvases the user can't access themselves.
+
+Access is resolved from `files.info` metadata (no extra storage or scopes needed):
+
+| Check | Source field |
+|-------|-------------|
+| Is user the creator? | `user` / `canvas_creator_id` |
+| Per-user access | `dm_mpdm_users_with_file_access` |
+| Workspace-wide access | `org_or_workspace_access` |
+
+**Access levels** (higher includes lower): `owner` > `write` > `read`
+
+**Required access per tool:**
+
+| Tool | Required |
+|------|----------|
+| `canvas_create` | — (no existing canvas) |
+| `canvas_get` | read |
+| `canvas_update` | write |
+| `canvas_delete` | owner |
+| `canvas_access_get` | read |
+| `canvas_access_add` | owner |
+| `canvas_access_remove` | owner |
+
+If the user lacks sufficient access, the tool returns an error message explaining what access level is needed.
 
 ## Canvas content format
 
@@ -664,25 +700,24 @@ Block Kit is **not** supported in canvases.
 
 | Tool | Description |
 |------|-------------|
-| `canvas_create` | Create a canvas with title + content. Optional `channel_id` to share it. |
+| `canvas_create` | Create a standalone canvas with title + content. |
 | `canvas_get` | Get a canvas by ID. Returns title, full markdown content, and permalink. |
 | `canvas_update` | Update a canvas — replace content, rename title, or both. |
 | `canvas_delete` | Permanently delete a canvas. |
-| `canvas_list` | List canvases visible to the bot. Optional `channel_id` filter. |
 | `canvas_access_get` | Get sharing/access info for a canvas. |
-| `canvas_access_add` | Grant read/write/owner access to users or channels. |
-| `canvas_access_remove` | Remove access for users or channels. |
+| `canvas_access_add` | Grant read/write/owner access to users. Optionally set `org_access` for workspace-wide access. |
+| `canvas_access_remove` | Remove access for users. |
 
 ## Example usage
 
-**Create a canvas in a channel:**
-> "Create a canvas in #project-updates titled 'Q1 Roadmap' with our milestone list"
+**Create a canvas:**
+> "Create a canvas titled 'Q1 Roadmap' with our milestone list"
 
 **Read and update a canvas:**
 > "Get the canvas F12345 and update it with the latest status"
 
-**Share a canvas with another team:**
-> "Give the #design channel write access to canvas F12345"
+**Share a canvas with specific users:**
+> "Give users U123 and U456 write access to canvas F12345"
 
 ---
 

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-slack-agents"
-version = "0.6.1"
+version = "0.6.2"
 description = "A Python framework for deploying AI agents as Slack bots"
 authors = [{name = "Eric Pichon", email = "epichon@comparenetworks.com"}]
 readme = "README.md"

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/src/slack_agents/__init__.py

@@ -1,7 +1,7 @@
 """slack-agents: A Python framework for deploying AI agents as Slack bots."""
 
 from importlib.metadata import version
-from typing import TypedDict
+from typing import NotRequired, TypedDict
 
 __version__ = version("python-slack-agents")
 
@@ -23,3 +23,4 @@ class InputFile(TypedDict):
     file_bytes: bytes
     mimetype: str
     filename: str
+    file_id: NotRequired[str]

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/src/slack_agents/files.py

@@ -34,6 +34,7 @@ class FileHandlerRegistry:
         filename: str,
         user_conversation_context: UserConversationContext,
         storage: BaseStorageProvider,
+        file_id: str | None = None,
     ) -> ContentBlock | None:
         entry = self._mime_map.get(mimetype)
         if not entry:
@@ -50,6 +51,8 @@ class FileHandlerRegistry:
                 ),
             }
         input_file = InputFile(file_bytes=file_bytes, mimetype=mimetype, filename=filename)
+        if file_id is not None:
+            input_file["file_id"] = file_id
         try:
             return await provider.call_tool(
                 handler_name, input_file, user_conversation_context, storage

python_slack_agents-0.6.2/src/slack_agents/slack/canvas_auth.py

@@ -0,0 +1,58 @@
+"""Canvas user-level authorization.
+
+Resolves a user's access level for a canvas using ``files.info`` metadata
+from the Slack API — no additional storage or scopes required.
+"""
+
+from slack_sdk.web.async_client import AsyncWebClient
+
+from slack_agents.slack.canvases import CanvasError, get_canvas_info
+
+# Level hierarchy (higher index = more permissive)
+_LEVEL_RANK = {"read": 1, "write": 2, "owner": 3}
+
+
+class CanvasAccessDenied(CanvasError):
+    """Raised when a user lacks sufficient access to a canvas."""
+
+
+def resolve_user_access(file_info: dict, user_id: str) -> str | None:
+    """Return the user's access level for a canvas, or ``None`` if denied.
+
+    Returns one of ``"owner"``, ``"write"``, ``"read"``, or ``None``.
+    """
+    # Creator is the owner
+    creator = file_info.get("user") or file_info.get("canvas_creator_id")
+    if creator and creator == user_id:
+        return "owner"
+
+    # Explicit per-user access list
+    for entry in file_info.get("dm_mpdm_users_with_file_access", []):
+        if entry.get("user_id") == user_id:
+            return entry.get("access")
+
+    # Org/workspace-wide access
+    org_access = file_info.get("org_or_workspace_access", "none")
+    if org_access != "none":
+        return org_access
+
+    return None
+
+
+async def check_canvas_access(
+    client: AsyncWebClient,
+    *,
+    canvas_id: str,
+    user_id: str,
+    required_level: str,
+) -> dict:
+    """Verify that *user_id* has at least *required_level* access to *canvas_id*.
+
+    Returns the ``file_info`` dict on success.
+    Raises :class:`CanvasAccessDenied` if the user lacks sufficient access.
+    """
+    file_info = await get_canvas_info(client, canvas_id=canvas_id)
+    access = resolve_user_access(file_info, user_id)
+    if access is None or _LEVEL_RANK.get(access, 0) < _LEVEL_RANK.get(required_level, 0):
+        raise CanvasAccessDenied(f"You don't have {required_level} access to canvas {canvas_id}")
+    return file_info

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/src/slack_agents/slack/canvases.py

@@ -30,27 +30,9 @@ async def create_canvas(
     *,
     title: str | None = None,
     markdown: str | None = None,
-    channel_id: str | None = None,
 ) -> dict:
-    """Create a new canvas, optionally posting it to a channel.
-
-    If *channel_id* is provided the canvas is created inside that
-    conversation (required on free Slack plans).  Otherwise a
-    standalone canvas is created via ``canvases.create``.
-    """
-    if channel_id:
-        kwargs: dict = {}
-        if title:
-            kwargs["title"] = title
-        if markdown is not None:
-            kwargs["document_content"] = {"type": "markdown", "markdown": markdown}
-        resp = await client.api_call(
-            "conversations.canvases.create",
-            json={"channel_id": channel_id, **kwargs},
-        )
-        return _check(resp, "create")
-
-    kwargs = {}
+    """Create a new standalone canvas via ``canvases.create``."""
+    kwargs: dict = {}
     if title:
         kwargs["title"] = title
     if markdown is not None:
@@ -168,42 +150,20 @@ async def rename_canvas(
     return _check(resp, "rename")
 
 
-async def list_canvases(
-    client: AsyncWebClient,
-    *,
-    channel: str | None = None,
-    count: int = 20,
-) -> list[dict]:
-    """List canvases visible to the bot.
-
-    Uses ``files.list`` with ``types=canvas``.  Optionally filter by
-    *channel*.
-    """
-    kwargs: dict = {"types": "canvas", "count": count}
-    if channel:
-        kwargs["channel"] = channel
-    resp = await client.api_call("files.list", params=kwargs)
-    _check(resp, "list")
-    return resp.get("files", [])
-
-
 async def set_canvas_access(
     client: AsyncWebClient,
     *,
     canvas_id: str,
     access_level: str,
     user_ids: list[str] | None = None,
-    channel_ids: list[str] | None = None,
 ) -> dict:
-    """Grant access to a canvas for users and/or channels.
+    """Grant access to a canvas for users.
 
     *access_level* is one of ``read``, ``write``, or ``owner``.
     """
     payload: dict = {"canvas_id": canvas_id, "access_level": access_level}
     if user_ids:
         payload["user_ids"] = user_ids
-    if channel_ids:
-        payload["channel_ids"] = channel_ids
     resp = await client.api_call("canvases.access.set", json=payload)
     return _check(resp, "access.set")
 
@@ -213,13 +173,10 @@ async def delete_canvas_access(
     *,
     canvas_id: str,
     user_ids: list[str] | None = None,
-    channel_ids: list[str] | None = None,
 ) -> dict:
-    """Remove access to a canvas for users and/or channels."""
+    """Remove access to a canvas for users."""
     payload: dict = {"canvas_id": canvas_id}
     if user_ids:
         payload["user_ids"] = user_ids
-    if channel_ids:
-        payload["channel_ids"] = channel_ids
     resp = await client.api_call("canvases.access.delete", json=payload)
     return _check(resp, "access.delete")

{python_slack_agents-0.6.1 → python_slack_agents-0.6.2}/src/slack_agents/slack/files.py

@@ -63,7 +63,12 @@ async def process_files_for_message(
         }
 
         block = await registry.process_file(
-            file_bytes, mimetype, filename, user_conversation_context, storage
+            file_bytes,
+            mimetype,
+            filename,
+            user_conversation_context,
+            storage,
+            file_id=file_info.get("id"),
         )
         if block is not None:
             if block.get("type") != "image":