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

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

@@ -103,16 +103,20 @@ The project includes AI-agent-friendly documentation following the llms.txt conv
 ## Releasing
 
 1. Update `version` in `pyproject.toml`
-2. Update the minimum version in `src/slack_agents/cli/init.py` (`python-slack-agents>=X.Y,<2`)
-3. Commit and push to `main`
-3. Create a GitHub Release (which creates a git tag)
-4. The `publish.yml` workflow automatically builds and publishes to PyPI via trusted publishing
+2. Update `CHANGELOG.md` with the new version and changes
+3. Run `python3 src/slack_agents/scripts/generate_llms_full.py` to regenerate `llms-full.txt`
+4. Commit and push to `main`
+5. Create a GitHub Release (which creates a git tag)
+6. The `publish.yml` workflow automatically builds and publishes to PyPI via trusted publishing
 
-Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
+The PyPI deployment requires manual approval in the GitHub Actions UI. Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
 
 ## 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.
+- **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.2/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [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
+
+- `slack-agents init` now generates `.gitignore` 
+- `.env.example` template includes comments explaining where to get each token and links to setup guide
+- `build-docker` lists required environment variables after build completes
+- `build-docker` errors if `req*.txt` files are found (dependencies must be in `pyproject.toml`)
+- `init` warns when `req*.txt` files are found with migration instructions
+
+### Changed
+
+- `pyproject.toml` template uses `python-slack-agents<2` (no minimum pin) 
+- Setup flow uses venv-first approach: create venv, install package, then `slack-agents init`
+- Updated README, docs/setup.md, and docs/private-repo.md with new setup flow
+
+### Fixed
+
+- Config loader now strips YAML comments before env var interpolation — commented-out `{ENV_VAR}` patterns no longer cause `KeyError`
+- `init` shows proposed file content when skipping existing files
+
+## [0.6.0] - 2026-03-18
+
+### Added
+
+- `slack-agents init <project_name>` CLI command to scaffold new projects
+- `llms.txt` and `llms-full.txt` for AI agent discoverability
+- `llms-full.txt` bundled in PyPI wheel
+- Script to generate `llms-full.txt` from docs (`src/slack_agents/scripts/generate_llms_full.py`)
+- "Project Structure" section in README
+- Release process documentation in AGENTS.md
+
+### Changed
+
+- Simplified Dockerfile: empty placeholders for README.md and llms-full.txt so builds work for both framework and user projects
+- Updated docs/private-repo.md to use `slack-agents init`
+- Updated docs/cli.md with `init` command reference
+
+## [0.5.0] - 2025-03-13
+
+### Added
+
+- Plugin architecture for LLM providers, storage backends, and tools
+- Anthropic and OpenAI LLM providers
+- SQLite and PostgreSQL storage providers
+- MCP over HTTP tool provider
+- Built-in document export tools (PDF, DOCX, XLSX, CSV, PPTX)
+- Streaming output with native Slack table rendering
+- Socket Mode support (no public URL required)
+- OpenTelemetry observability
+- `{ENV_VAR}` interpolation in agent configs
+- Per-agent Docker builds via `docker-build-and-push.sh`

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-slack-agents
-Version: 0.6.0
+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
@@ -82,17 +82,16 @@ Each agent is a directory with two files: a `config.yaml` and a `system_prompt.t
 ## Quick Start
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
 pip install python-slack-agents
 
-# Scaffold a new project
-mkdir my-agents && cd my-agents
+# Scaffold the project
 slack-agents init my-agents
 
-# Add your tokens
-cp .env.example .env
-# Edit .env: SLACK_BOT_TOKEN, SLACK_APP_TOKEN, ANTHROPIC_API_KEY
-
-# Install for development (makes custom providers importable)
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens
 pip install -e .
 
 # Run the hello-world agent
@@ -330,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.0 → python_slack_agents-0.6.2}/README.md

@@ -36,17 +36,16 @@ Each agent is a directory with two files: a `config.yaml` and a `system_prompt.t
 ## Quick Start
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
 pip install python-slack-agents
 
-# Scaffold a new project
-mkdir my-agents && cd my-agents
+# Scaffold the project
 slack-agents init my-agents
 
-# Add your tokens
-cp .env.example .env
-# Edit .env: SLACK_BOT_TOKEN, SLACK_APP_TOKEN, ANTHROPIC_API_KEY
-
-# Install for development (makes custom providers importable)
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens
 pip install -e .
 
 # Run the hello-world agent
@@ -284,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.0 → 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.0 → python_slack_agents-0.6.2}/docs/private-repo.md

@@ -16,6 +16,9 @@ For production agents with company-specific prompts, tools, and configs, create
 
 ```bash
 mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
 slack-agents init my-agents
 pip install -e .
 ```

{python_slack_agents-0.6.0 → python_slack_agents-0.6.2}/docs/setup.md

@@ -6,9 +6,32 @@
 - A Slack workspace (all plans supported, including free)
 - API key for your LLM provider (Anthropic and/or OpenAI)
 
-## Installation
+## New Project
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
+
+# Scaffold the project
+slack-agents init my-agents
+
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens (see below)
+pip install -e .
+
+# Run the hello-world agent
+slack-agents run agents/hello-world
+```
+
+## Framework Development
+
+If you're working on the framework itself:
+
+```bash
+git clone https://github.com/CompareNetworks/python-slack-agents.git
+cd python-slack-agents
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
@@ -40,7 +63,7 @@ ANTHROPIC_API_KEY=sk-ant-...
   - Copy: App Token (eg, SLACK_APP_TOKEN=xapp-...)
 - Settings > Install App
   - Copy: Bot User OAuth Token (eg, SLACK_BOT_TOKEN=xoxb-...)
-3. If App does not appeat in your Slack client:
+3. If App does not appear in your Slack client:
   - ... > Tools > Apps > (search by name and add the app)
 
 ## Download Fonts
@@ -53,12 +76,6 @@ python -m slack_agents.scripts.download_fonts
 
 This downloads `DejaVuSans.ttf` and `DejaVuSans-Bold.ttf` into `fonts/` (~700KB total). Without these fonts, PDF generation falls back to Helvetica (latin-1 only).
 
-## Running an Agent
-
-```bash
-slack-agents run agents/hello-world
-```
-
 ## Optional: PostgreSQL
 
 For conversation persistence via PostgreSQL, update your agent's `config.yaml`:

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

@@ -1,7 +1,8 @@
 # python-slack-agents: Complete Reference
 
 > A Python framework for deploying AI agents as Slack bots.
-> Each agent is a YAML config and a system prompt — pick your LLM, connect some MCP tools, and `slack-agents run`.
+> Each agent is a YAML config and a system prompt — pick your LLM,
+> connect some MCP tools, and `slack-agents run`.
 
 - **Package:** `pip install python-slack-agents`
 - **CLI entry point:** `slack-agents`
@@ -11,15 +12,26 @@
 
 ## How to read this document
 
-This file is a concatenation of all documentation files, designed to be consumed in a single read.
-The sections below correspond to individual doc files in the `docs/` directory.
+This file is a concatenation of all documentation files,
+designed to be consumed in a single read.
+The sections below correspond to individual doc files
+in the `docs/` directory.
 
 ### Key concepts
 
-- **Config-driven:** each agent is a directory with `config.yaml` + `system_prompt.txt`. All behavior is configured in YAML.
-- **Plugin pattern:** every pluggable component (LLM, storage, tools, access) uses a `type` field with a dotted Python import path pointing to a module with a `Provider` class. All other config keys are passed as kwargs to `Provider.__init__`.
-- **Two kinds of tool providers:** `BaseToolProvider` (tools the LLM calls) and `BaseFileImporterProvider` (file handlers the *framework* calls automatically — invisible to the LLM). Both are configured under `tools:` in config.yaml.
-- **Environment variables:** `{ENV_VAR}` patterns in config values are resolved from environment variables at startup.
+- **Config-driven:** each agent is a directory with
+  `config.yaml` + `system_prompt.txt`.
+  All behavior is configured in YAML.
+- **Plugin pattern:** every pluggable component (LLM, storage,
+  tools, access) uses a `type` field with a dotted Python import
+  path pointing to a module with a `Provider` class. All other
+  config keys are passed as kwargs to `Provider.__init__`.
+- **Two kinds of tool providers:** `BaseToolProvider` (tools the
+  LLM calls) and `BaseFileImporterProvider` (file handlers the
+  *framework* calls automatically — invisible to the LLM). Both
+  are configured under `tools:` in config.yaml.
+- **Environment variables:** `{ENV_VAR}` patterns in config values
+  are resolved from environment variables at startup.
 
 ---
 
@@ -31,9 +43,32 @@ The sections below correspond to individual doc files in the `docs/` directory.
 - A Slack workspace (all plans supported, including free)
 - API key for your LLM provider (Anthropic and/or OpenAI)
 
-## Installation
+## New Project
 
 ```bash
+mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
+
+# Scaffold the project
+slack-agents init my-agents
+
+# Add your tokens and install for development
+cp .env.example .env       # add your Slack and LLM tokens (see below)
+pip install -e .
+
+# Run the hello-world agent
+slack-agents run agents/hello-world
+```
+
+## Framework Development
+
+If you're working on the framework itself:
+
+```bash
+git clone https://github.com/CompareNetworks/python-slack-agents.git
+cd python-slack-agents
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
@@ -65,7 +100,7 @@ ANTHROPIC_API_KEY=sk-ant-...
   - Copy: App Token (eg, SLACK_APP_TOKEN=xapp-...)
 - Settings > Install App
   - Copy: Bot User OAuth Token (eg, SLACK_BOT_TOKEN=xoxb-...)
-3. If App does not appeat in your Slack client:
+3. If App does not appear in your Slack client:
   - ... > Tools > Apps > (search by name and add the app)
 
 ## Download Fonts
@@ -78,12 +113,6 @@ python -m slack_agents.scripts.download_fonts
 
 This downloads `DejaVuSans.ttf` and `DejaVuSans-Bold.ttf` into `fonts/` (~700KB total). Without these fonts, PDF generation falls back to Helvetica (latin-1 only).
 
-## Running an Agent
-
-```bash
-slack-agents run agents/hello-world
-```
-
 ## Optional: PostgreSQL
 
 For conversation persistence via PostgreSQL, update your agent's `config.yaml`:
@@ -573,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
 
@@ -583,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.
 
@@ -608,13 +637,49 @@ To expose only specific tools:
       - "canvas_create"
       - "canvas_get"
       - "canvas_update"
-      - "canvas_list"
 ```
 
-## Slack plan requirements
+### 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.
 
-- **Free plans**: 1 canvas per channel/DM. `canvas_create` requires `channel_id`.
-- **Paid plans** (Pro, Business+, Enterprise Grid): Unlimited canvases. `channel_id` is optional.
+## 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
 
@@ -635,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"
 
 ---
 
@@ -1101,6 +1165,9 @@ For production agents with company-specific prompts, tools, and configs, create
 
 ```bash
 mkdir my-agents && cd my-agents
+python3 -m venv .venv
+source .venv/bin/activate
+pip install python-slack-agents
 slack-agents init my-agents
 pip install -e .
 ```

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-slack-agents"
-version = "0.6.0"
+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.0 → 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]