python-slack-agents 0.6.3__tar.gz → 0.8.0__tar.gz

{python_slack_agents-0.6.3 → python_slack_agents-0.8.0}/.gitignore

@@ -1,6 +1,9 @@
 # Worktrees
 .worktrees/
 
+# Local implementation plans (working docs)
+.plans/
+
 # Python
 __pycache__/
 *.py[cod]
@@ -34,4 +37,6 @@ agents-local/
 
 # Certificates
 *.pem
+you c
 /ONGOING.md
+/docs/superpowers/

{python_slack_agents-0.6.3 → python_slack_agents-0.8.0}/AGENTS.md

@@ -102,12 +102,14 @@ The project includes AI-agent-friendly documentation following the llms.txt conv
 
 ## Releasing
 
-1. Update `version` in `pyproject.toml`
-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
+`CHANGELOG.md` is the gate. Entries accumulate under `## [Unreleased]` as PRs land; releasing just renames that heading to the new version. If prior releases skipped this step (as 0.6.3 did), backfill those versions first so the changelog is honest about history.
+
+1. **CHANGELOG.md** — rename `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD` with today's date, and add a fresh empty `## [Unreleased]` above it.
+2. **pyproject.toml** — bump `version` to `X.Y.Z`.
+3. **llms-full.txt** — regenerate: `python3 src/slack_agents/scripts/generate_llms_full.py`.
+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.
 
 The PyPI deployment requires manual approval in the GitHub Actions UI. Do NOT publish to PyPI manually — the GitHub Release trigger handles it.
 

python_slack_agents-0.8.0/CHANGELOG.md

@@ -0,0 +1,140 @@
+# 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.8.0] - 2026-05-06
+
+### Added
+
+- `slack_agents.tools.mcp_http_oauth` — OAuth-authenticated MCP tool provider with per-Slack-user tokens. Each user authenticates separately to the upstream service; refresh tokens are AES-GCM-encrypted at rest. The provider runs an in-process aiohttp callback listener alongside Slack Bolt's WebSocket connection — no public ingress beyond a single `/oauth/callback` path. Includes Dynamic Client Registration with PRM-driven scope catalog, scope-merging on every authorize request (OIDC baseline + cached-token scopes + server-hinted scopes), and post-step-up permission-denied detection. See `docs/oauth.md`.
+- `slack_agents.oauth/` package — signed-state codec, HKDF/AES-GCM crypto, callback listener, ephemeral auth-prompt builder, `DBTokenStorage` bridging the MCP SDK's `TokenStorage` Protocol to the agent's storage backend.
+- `oauth_tokens` and `oauth_clients` tables on both SQLite and PostgreSQL backends (created idempotently at startup).
+- `FrameworkContext` injection in `load_plugin` — providers that declare a `framework_ctx` parameter receive a shared object holding the bot token, Slack client, storage backend, and OAuth pending-flows registry. Existing providers are unaffected.
+- `validate_oauth_env(tools_config)` consolidated startup check. Required env vars when at least one `mcp_http_oauth` provider is configured: `OAUTH_PUBLIC_URL`, `OAUTH_SECRET_KEY`. Optional: `OAUTH_BIND_HOST` (default `0.0.0.0`), `OAUTH_BIND_PORT` (default `8080`). Missing/malformed values produce a single, actionable error and refuse to start.
+- Eager-auth pre-LLM hook in `SlackAgent` — each user's first message triggers OAuth setup before the LLM is invoked, so the LLM sees real tool lists rather than an empty/placeholder set.
+- `make_tool_error(...)` helper plus `ERROR_*` and `RECOVERY_*` constants in `slack_agents.tools.base`. Uniform JSON schema for tool-error payloads in `ToolResult.content` so the LLM consuming a tool result can reason about errors (permission_denied / system_error / input_error / auth_setup_failed) uniformly. The `recovery` enum (retry / contact_admin / contact_support / abort) drives how the LLM should advise the user. See `docs/tools.md` "Tool error schema".
+- LLM error classification in `slack/agent.py` — transient provider errors (`overloaded_error`, `rate_limit_error`, `api_error`, `timeout_error`) produce friendly user messages and log at WARNING (no traceback noise); configuration errors (`authentication_error`, `permission_error`, `not_found_error`, `invalid_request_error`) stay ERROR with full traceback.
+- `cryptography` runtime dependency (HKDF + AES-GCM).
+- `docs/oauth.md` — operator guide, scope-handling story, MCP SDK workarounds, troubleshooting (Trusted Hosts and Allowed Client Scopes policy gates, post-step-up permission denial).
+
+### Changed
+
+- Every built-in tool error site (`mcp_http`, `mcp_http_oauth`, `canvas`, `user_context`, `file_exporter`, plus `agent_loop`'s unknown-tool fallback) now emits the unified structured-error JSON schema in `ToolResult.content` when `is_error=True`. Custom tools should use `make_tool_error(...)`.
+- The Slack-user-facing message on unrecognized exceptions ("Sorry, I encountered an error processing your request.") is now the fallback only — known LLM-provider errors get specific messages instead.
+- `docs/tools.md` — example uses `make_tool_error` for the unknown-tool branch; new "Tool error schema" section.
+
+## [0.7.0] - 2026-04-14
+
+### Changed
+
+- **Overlays are no longer Python packages.** `slack-agents init` scaffolds a plain git repo with `requirements.txt` (pinning the currently-installed framework version) instead of `pyproject.toml`. No more `pip install -e .` step for overlays — users run `pip install -r requirements.txt` and are done.
+- The framework CLI now walks up from the agent directory on startup, finds the nearest `src/` sibling, and prepends it to `sys.path`. Custom providers under `src/<pkg>/` resolve without installing the overlay as a pip package.
+- Bundled Dockerfile installs overlay dependencies from `requirements.txt` (or PEP 735 `[dependency-groups]` as an alternative) instead of running `pip install .`. The `README.md` / `llms-full.txt` placeholder workaround is gone.
+- Scaffolder `.gitignore` drops `*.egg-info/` and `dist/` (overlays no longer build wheels).
+
+### Added
+
+- `_auto_extend_sys_path()` helper in `slack_agents.config`, called from `load_agent_config()` before any plugin import.
+- End-to-end overlay integration test covering scaffold → auto-sys.path → custom provider resolution, plus Dockerfile-shape assertions.
+
+### Removed
+
+- `build-docker` no longer rejects overlays with `req*.txt` files — that file is now the expected input.
+- `slack-agents init` no longer emits `pyproject.toml` or warns about requirements files.
+- "Framework Development" section removed from `docs/setup.md` — contributors see `CONTRIBUTING.md` instead, keeping user-facing docs focused on overlay users.
+
+### Docs
+
+- Full rewrite of `docs/private-repo.md` around a single-path overlay model. PEP 735 `[dependency-groups]` documented as an alternative for teams who want `pyproject.toml` without `[project]`.
+- `README.md` "Project Structure" and "Extending" sections rewritten to match.
+
+### Migration
+
+- Delete your overlay's `pyproject.toml` and any `*.egg-info/` directories.
+- Add a `requirements.txt` pinning `python-slack-agents==0.7.0` (or `<2`).
+- Run `pip install -r requirements.txt`.
+- Custom providers under `src/<pkg>/` work without `pip install -e .`.
+
+## [0.6.3] - 2026-03-31
+
+### Fixed
+
+- Preserve agent name in Docker image for multi-agent database support (`COPY` uses `${AGENT_NAME}` so each image's agent directory keeps its identity).
+- Remove `libmupdf-dev` from the Docker image — image size down to 354 MB.
+
+## [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.3 → python_slack_agents-0.8.0}/CONTRIBUTING.md

@@ -46,6 +46,12 @@ refactor: simplify streaming formatter table detection
 
 Prefixes: `feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`. First line under 72 characters. Add a body after a blank line if context is needed.
 
+## CHANGELOG
+
+When your change is user-visible (a new feature, a behavior change, a removed option, a fix with user-visible symptoms), add a bullet to `CHANGELOG.md` under `## [Unreleased]`. Group by Keep-a-Changelog categories (`### Added`, `### Changed`, `### Fixed`, `### Removed`). Internal refactors and test-only changes don't need an entry.
+
+Releasing is just renaming `[Unreleased]` — so if every PR touches it, releases stay cheap and honest.
+
 ## Pull Requests
 
 1. Fork the repo and create a branch

{python_slack_agents-0.6.3 → python_slack_agents-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-slack-agents
-Version: 0.6.3
+Version: 0.8.0
 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
@@ -21,6 +21,7 @@ Requires-Dist: aiohttp<4,>=3.9
 Requires-Dist: aiosqlite<1,>=0.20
 Requires-Dist: anthropic<1,>=0.40
 Requires-Dist: asyncpg<1,>=0.30
+Requires-Dist: cryptography<46,>=42
 Requires-Dist: fpdf2<3,>=2.8
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: mcp<2,>=1.0
@@ -63,7 +64,7 @@ Each agent is a directory with two files: a `config.yaml` and a `system_prompt.t
 
 **LLM providers** — Anthropic and OpenAI built in, plus any OpenAI-compatible API (Mistral, Groq, Together, Ollama, vLLM). Extend to any other provider by implementing a simple base class.
 
-**Tool calling with MCP** — Connect any [MCP server](https://modelcontextprotocol.io/) over HTTP. Tools are discovered automatically, executed in parallel, and filtered with regex patterns. No tool registration boilerplate.
+**Tool calling with MCP** — Connect any [MCP server](https://modelcontextprotocol.io/) over HTTP. Tools are discovered automatically, executed in parallel, and filtered with regex patterns. No tool registration boilerplate. **OAuth-protected MCP servers are supported with per-Slack-user tokens** — see [docs/oauth.md](docs/oauth.md).
 
 **File handling** — Agents can read files your users upload (PDF, DOCX, XLSX, PPTX, CSV, images) and generate documents back (PDF, DOCX, XLSX, CSV, PPTX). All built in, no extra setup.
 
@@ -90,9 +91,9 @@ 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
-pip install -e .
+# Add your tokens and install framework + deps
+cp .env.example .env                 # add your Slack and LLM tokens
+pip install -r requirements.txt
 
 # Run the hello-world agent
 slack-agents run agents/hello-world
@@ -241,23 +242,45 @@ tools:
       - "get_document"    # exact match works too
 ```
 
+For MCP servers that require OAuth 2.1 (per-user authentication), use `mcp_http_oauth` — same auto-discovery, with each Slack user authenticating separately to the upstream service:
+
+```yaml
+tools:
+  my-oauth-mcp:
+    type: slack_agents.tools.mcp_http_oauth
+    url: "https://my-server.example.com/mcp"
+    allowed_functions: [".*"]
+```
+
+Tokens are persisted per Slack user, refresh tokens are AES-GCM-encrypted at rest, and an in-process callback listener handles the OAuth dance alongside the Slack Bolt connection. See [docs/oauth.md](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/oauth.md) for setup (env vars, tunnel for local dev, scope handling, troubleshooting).
+
 ## Project Structure
 
-When you add custom providers (tools, LLM, storage, or access control), your project needs a `pyproject.toml` and a `src/` directory so that `pip install -e .` makes your code importable and `slack-agents build-docker` works:
+Your overlay is a plain git repo — not a Python package. You edit configs, commit, and run; there's no
+install-the-overlay-as-a-package step. A typical layout looks like:
 
 ```
 my-agents/
-├── pyproject.toml          # declares python-slack-agents as dependency
-├── src/
-│   └── my_agents/          # your custom providers go here
-│       └── __init__.py
+├── requirements.txt        # pins python-slack-agents (and any extra deps)
+├── .env.example
+├── .gitignore
 ├── agents/
 │   └── my-agent/
 │       ├── config.yaml
 │       └── system_prompt.txt
-└── .env
+└── src/                    # optional — only if you add custom providers
+    └── my_agents/
+        └── __init__.py
 ```
 
+Two conventions to know:
+
+- **`src/` holds custom Python.** On `slack-agents run`, the framework walks up from the agent directory,
+  finds the nearest `src/` sibling, and prepends it to `sys.path`. Anything under `src/<pkg>/...` is
+  importable as `<pkg>.…` with no install step.
+- **`requirements.txt` pins your framework version and any extra Python deps.** `pip install -r requirements.txt`
+  is the only install command you ever run.
+
 `slack-agents init` scaffolds this for you. See [Organizing agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/private-repo.md) for details.
 
 ## Extending
@@ -281,7 +304,10 @@ class Provider(BaseLLMProvider):
         ...
 ```
 
-After `pip install -e .`, your providers are importable and the `type` field in config resolves them. This also works with `slack-agents build-docker` — the bundled Dockerfile runs `pip install .` automatically.
+After you drop a module under `src/`, it's picked up automatically on the next `slack-agents run` —
+the framework prepends `./src` to `sys.path` at startup. The same mechanism works inside Docker:
+the bundled Dockerfile installs dependencies from `requirements.txt` and copies your `src/` into the
+image, so custom providers resolve in production too.
 
 See the docs for the full interface for each component:
 
@@ -313,6 +339,7 @@ To create a Slack app, use the manifest in [`docs/slack-app-manifest.json`](http
 - [Setup](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/setup.md) — installation and Slack app creation
 - [Agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/agents.md) — creating and configuring agents
 - [Tools](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/tools.md) — MCP servers and custom tool providers
+- [OAuth-protected MCP servers](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/oauth.md) — per-Slack-user OAuth for MCP servers requiring authentication
 - [LLM](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/llm.md) — supported providers and adding your own
 - [Storage](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/storage.md) — SQLite, PostgreSQL, and custom backends
 - [Access control](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/access-control.md) — controlling who can use an agent

{python_slack_agents-0.6.3 → python_slack_agents-0.8.0}/README.md

@@ -17,7 +17,7 @@ Each agent is a directory with two files: a `config.yaml` and a `system_prompt.t
 
 **LLM providers** — Anthropic and OpenAI built in, plus any OpenAI-compatible API (Mistral, Groq, Together, Ollama, vLLM). Extend to any other provider by implementing a simple base class.
 
-**Tool calling with MCP** — Connect any [MCP server](https://modelcontextprotocol.io/) over HTTP. Tools are discovered automatically, executed in parallel, and filtered with regex patterns. No tool registration boilerplate.
+**Tool calling with MCP** — Connect any [MCP server](https://modelcontextprotocol.io/) over HTTP. Tools are discovered automatically, executed in parallel, and filtered with regex patterns. No tool registration boilerplate. **OAuth-protected MCP servers are supported with per-Slack-user tokens** — see [docs/oauth.md](docs/oauth.md).
 
 **File handling** — Agents can read files your users upload (PDF, DOCX, XLSX, PPTX, CSV, images) and generate documents back (PDF, DOCX, XLSX, CSV, PPTX). All built in, no extra setup.
 
@@ -44,9 +44,9 @@ 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
-pip install -e .
+# Add your tokens and install framework + deps
+cp .env.example .env                 # add your Slack and LLM tokens
+pip install -r requirements.txt
 
 # Run the hello-world agent
 slack-agents run agents/hello-world
@@ -195,23 +195,45 @@ tools:
       - "get_document"    # exact match works too
 ```
 
+For MCP servers that require OAuth 2.1 (per-user authentication), use `mcp_http_oauth` — same auto-discovery, with each Slack user authenticating separately to the upstream service:
+
+```yaml
+tools:
+  my-oauth-mcp:
+    type: slack_agents.tools.mcp_http_oauth
+    url: "https://my-server.example.com/mcp"
+    allowed_functions: [".*"]
+```
+
+Tokens are persisted per Slack user, refresh tokens are AES-GCM-encrypted at rest, and an in-process callback listener handles the OAuth dance alongside the Slack Bolt connection. See [docs/oauth.md](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/oauth.md) for setup (env vars, tunnel for local dev, scope handling, troubleshooting).
+
 ## Project Structure
 
-When you add custom providers (tools, LLM, storage, or access control), your project needs a `pyproject.toml` and a `src/` directory so that `pip install -e .` makes your code importable and `slack-agents build-docker` works:
+Your overlay is a plain git repo — not a Python package. You edit configs, commit, and run; there's no
+install-the-overlay-as-a-package step. A typical layout looks like:
 
 ```
 my-agents/
-├── pyproject.toml          # declares python-slack-agents as dependency
-├── src/
-│   └── my_agents/          # your custom providers go here
-│       └── __init__.py
+├── requirements.txt        # pins python-slack-agents (and any extra deps)
+├── .env.example
+├── .gitignore
 ├── agents/
 │   └── my-agent/
 │       ├── config.yaml
 │       └── system_prompt.txt
-└── .env
+└── src/                    # optional — only if you add custom providers
+    └── my_agents/
+        └── __init__.py
 ```
 
+Two conventions to know:
+
+- **`src/` holds custom Python.** On `slack-agents run`, the framework walks up from the agent directory,
+  finds the nearest `src/` sibling, and prepends it to `sys.path`. Anything under `src/<pkg>/...` is
+  importable as `<pkg>.…` with no install step.
+- **`requirements.txt` pins your framework version and any extra Python deps.** `pip install -r requirements.txt`
+  is the only install command you ever run.
+
 `slack-agents init` scaffolds this for you. See [Organizing agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/private-repo.md) for details.
 
 ## Extending
@@ -235,7 +257,10 @@ class Provider(BaseLLMProvider):
         ...
 ```
 
-After `pip install -e .`, your providers are importable and the `type` field in config resolves them. This also works with `slack-agents build-docker` — the bundled Dockerfile runs `pip install .` automatically.
+After you drop a module under `src/`, it's picked up automatically on the next `slack-agents run` —
+the framework prepends `./src` to `sys.path` at startup. The same mechanism works inside Docker:
+the bundled Dockerfile installs dependencies from `requirements.txt` and copies your `src/` into the
+image, so custom providers resolve in production too.
 
 See the docs for the full interface for each component:
 
@@ -267,6 +292,7 @@ To create a Slack app, use the manifest in [`docs/slack-app-manifest.json`](http
 - [Setup](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/setup.md) — installation and Slack app creation
 - [Agents](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/agents.md) — creating and configuring agents
 - [Tools](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/tools.md) — MCP servers and custom tool providers
+- [OAuth-protected MCP servers](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/oauth.md) — per-Slack-user OAuth for MCP servers requiring authentication
 - [LLM](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/llm.md) — supported providers and adding your own
 - [Storage](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/storage.md) — SQLite, PostgreSQL, and custom backends
 - [Access control](https://github.com/CompareNetworks/python-slack-agents/blob/main/docs/access-control.md) — controlling who can use an agent

{python_slack_agents-0.6.3 → python_slack_agents-0.8.0}/docs/cli.md

@@ -10,7 +10,7 @@ Scaffold a new project in the current directory.
 slack-agents init <project_name>
 ```
 
-Creates `pyproject.toml`, `src/<package>/`, `.env.example`, and a `hello-world` agent. Existing files are skipped with a warning.
+Creates `requirements.txt`, `src/<package>/`, `.env.example`, `.gitignore`, and a `hello-world` agent. Existing files are skipped with a warning.
 
 ## run