python-slack-agents 0.8.1__tar.gz → 0.9.1__tar.gz

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/.gitignore

@@ -34,6 +34,8 @@ fonts/
 Thumbs.db
 
 agents-local/
+# Local-only agent variants (e.g. agents/a2a-agent-local/)
+*-local/
 
 # Certificates
 *.pem

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/.pre-commit-config.yaml

@@ -24,3 +24,8 @@ repos:
       - id: check-yaml
       - id: check-added-large-files
       - id: check-merge-conflict
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/CHANGELOG.md

@@ -1,4 +1,4 @@
-we don# Changelog
+# Changelog
 
 All notable changes to this project will be documented in this file.
 
@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-06-09
+
+### Added
+
+- **A2A per-user OAuth** (`auth: { type: oauth2 }`). Remote A2A agents can now require per-Slack-user OAuth 2.1: each user authenticates separately and the agent calls on their behalf. Auth metadata is discovered from the Agent Card's `securitySchemes.oauth2` (no `client_id`/`scopes` in YAML); the flow uses Dynamic Client Registration + authorization-code + PKCE + refresh, the same ephemeral "Authenticate" button, the shared `/oauth/*` ingress, and the same `PUBLIC_URL` / `OAUTH_SECRET_KEY` env contract as `mcp_http_oauth`. Long-running tasks polled in the background use the user's stored token non-interactively (silent refresh; a "session expired — please re-ask" notice if it can't be refreshed). When push is registered for a task, the token-dependent poller is skipped (push delivers regardless of later token state). See `docs/a2a.md`.
+- **A2A API-key auth** — `auth: { type: apiKey, name, value }` (sends the raw value as the named header, matching the Agent Card's `apiKey` scheme), alongside the existing `bearer` / `header` / `none` forms.
+- **OAuth user-info logging** (MCP and A2A). On first authentication the user's OIDC identity (`sub` / `preferred_username` / `name` / `email`) is fetched from the userinfo endpoint and logged. The `profile` scope is now requested and registered alongside `openid` / `offline_access`.
+
+### Changed
+
+- The provider-agnostic OAuth flow was extracted from `tools/mcp_http_oauth.py` into the `oauth/` package (`scopes`, `errors`, `discovery`, `flow`), parameterized by a discovery strategy — RFC 9728 PRM for MCP, Agent Card for A2A. No behavior change for MCP-OAuth.
+- DCR client registration now requests the OIDC baseline (`openid`, `offline_access`, `profile`) explicitly, so strict authorization-server registration policies (e.g. Keycloak's "Allowed Client Scopes") grant the client those scopes rather than rejecting the later authorize with `invalid_scope`.
+- **BREAKING (A2A):** removed the `name` field from `slack_agents.a2a.agent`. The single tool is now named after the provider's key under `tools:` (slugified to satisfy LLM tool-name rules); rename the key to rename the tool. Keys are unique within `tools:`, so two agents never collide.
+- **BREAKING (A2A):** removed `allowed_functions` from `slack_agents.a2a.agent` — an A2A agent exposes exactly one opaque tool, so there was nothing to filter. A stray `allowed_functions` on an A2A config is ignored at load with a warning.
+
+### Fixed
+
+- The in-process OAuth ingress crashed at startup with `TypeError: argument should be a bytes-like object … not 'bool'` whenever `OAUTH_SECRET_KEY` was set — `base64.b64decode(key, True)` passed `True` as the positional `altchars` argument instead of the keyword `validate=`. This was a latent bug in the shared ingress that affected MCP-OAuth and A2A-OAuth agents alike; it had no test coverage and is now exercised by `tests/test_ingress_startup.py`.
+- A2A `call_tool` now maps OAuth-specific failures to actionable results — a user-level authorization denial becomes a permission-denied error naming the missing scope, and an IdP `redirect_uri` rejection clears the stale client registration so the next attempt self-heals — instead of a generic "contact support".
+- The per-user A2A httpx client is closed if Agent Card resolution fails after construction, avoiding a connection-pool leak on the background poller's out-of-band re-auth path.
+
+## [0.9.0] - 2026-06-07
+
+### Added
+
+- **A2A push notifications (receiving).** A push-capable agent (`capabilities.pushNotifications`) can deliver task updates — status messages and file artifacts — to the Slack thread out-of-band, including reports that arrive after a synchronous reply. Opt in per agent with `push_notifications: true`. The framework registers the webhook inline on the first send with a random per-task token, validates the `X-A2A-Notification-Token` header, correlates by `taskId`, and de-duplicates by message/artifact id (the server re-pushes the immediate reply). The OAuth HTTP sidecar is generalized into a shared ingress (one listener starting for OAuth or push), configured by the new `PUBLIC_URL` / `HTTP_BIND_HOST` / `HTTP_BIND_PORT` env vars (see Changed). Verified end-to-end against a live agent. See `docs/a2a.md`.
+- **Agent2Agent (A2A) protocol integration** over the official `a2a-sdk` (1.x, protobuf), isolated behind `slack_agents.a2a.client`. Two topologies: `slack_agents.a2a.agent` exposes a remote A2A agent as a single free-text tool a real LLM delegates to (Option A, smart routing), and `slack_agents.a2a.proxy` turns Slack into a dumb frontend for one agent (Option B, dev/debugging). Features: per-thread `contextId` + `taskId` threading for correct multi-turn (`input-required`) conversations; synchronous replies plus detached background polling with out-of-band delivery for long-running (`working`) tasks (real LLMs re-process the result, the proxy posts it raw); bidirectional file attachments (Slack upload → A2A `raw` part, file artifact → Slack upload); static bearer/header auth. Includes an env-gated live integration test (`A2A_TEST_URL`). See `docs/a2a.md`.
+- `docs/private-repo.md` — "Protecting secrets in your overlay" section covering GitHub push protection (server-side block that survives `--no-verify`), a gitleaks pre-commit hook, and a one-time trufflehog history sweep. Aimed at overlay maintainers whose configs reference Slack tokens, LLM API keys, and OAuth client secrets via `{ENV_VAR}` placeholders.
+- `slack-agents init` now prints a visible "SECURITY: protect your secrets before pushing" banner at the end of scaffolding, linking to the new docs section.
+- `SECURITY.md` — pointer for overlay maintainers to the overlay security guidance.
+
+### Changed
+
+- **BREAKING (OAuth):** the in-process HTTP listener is now a shared ingress for OAuth callbacks and A2A push. Its env vars were renamed — `OAUTH_PUBLIC_URL` → `PUBLIC_URL`, `OAUTH_BIND_HOST` → `HTTP_BIND_HOST`, `OAUTH_BIND_PORT` → `HTTP_BIND_PORT` — with **no aliases**. (`OAUTH_SECRET_KEY` is unchanged.) Agents using OAuth must rename these in their environment. The startup validator fails fast with a clear message naming `PUBLIC_URL` when OAuth or push is configured but the var is missing.
+
+### Security
+
+- Dependency security updates clearing all open advisories. Lifted the speculative `cryptography` upper cap (`<46`) that had blocked the patch (the fix shipped in the next major) and raised the floor to `>=46.0.7`; refreshed the lockfile to current releases: `cryptography` 48, `aiohttp` 3.14.1, `pillow` 12.2.0, `lxml` 6.1.1, `urllib3` 2.7.0, `python-multipart` 0.0.32, `starlette` 1.2.1, `anthropic` 0.107.1, `pygments` 2.20.0.
+
 ## [0.8.1] - 2026-05-07
 
 ### Fixed
@@ -101,7 +140,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Added
 
-- `slack-agents init` now generates `.gitignore` 
+- `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`)
@@ -109,7 +148,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Changed
 
-- `pyproject.toml` template uses `python-slack-agents<2` (no minimum pin) 
+- `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
 

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-slack-agents
-Version: 0.8.1
+Version: 0.9.1
 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
@@ -17,11 +17,12 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Communications :: Chat
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.12
+Requires-Dist: a2a-sdk<2,>=1.0
 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: cryptography>=46.0.7
 Requires-Dist: fpdf2<3,>=2.8
 Requires-Dist: httpx<1,>=0.27
 Requires-Dist: mcp<2,>=1.0
@@ -41,7 +42,7 @@ Requires-Dist: slack-sdk[socket-mode-handlers]<4,>=3.33
 Provides-Extra: dev
 Requires-Dist: pre-commit<5,>=4.0; extra == 'dev'
 Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
-Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: pytest<10,>=8.0; extra == 'dev'
 Requires-Dist: ruff<1,>=0.8; extra == 'dev'
 Description-Content-Type: text/markdown
 

python_slack_agents-0.9.1/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities privately using [GitHub's security advisory feature](https://github.com/CompareNetworks/python-slack-agents/security/advisories/new).
+
+Do **not** open public issues for security concerns.
+
+We will acknowledge reports within 72 hours and aim to release fixes promptly.
+
+## For overlay maintainers
+
+If you operate an overlay repository (your own `agents/`, `src/`, and configs built on top of this framework), see [Protecting secrets in your overlay](docs/private-repo.md#protecting-secrets-in-your-overlay) for the recommended setup: GitHub push protection, a gitleaks pre-commit hook, and a one-time trufflehog history sweep.

python_slack_agents-0.9.1/agents/a2a-agent/config.yaml

@@ -0,0 +1,66 @@
+# Agent2Agent (A2A) example — connects to a remote A2A agent.
+#
+# It points at the official "helloworld" reference agent (a2a-sdk 1.x, no API
+# key), run locally in Docker. START THE SERVER FIRST:
+#
+#   git clone --depth 1 https://github.com/a2aproject/a2a-samples /tmp/a2a-samples
+#   cd /tmp/a2a-samples/samples/python/agents/helloworld
+#   # upstream binds 127.0.0.1 inside the container; make it bind 0.0.0.0:
+#   sed -i '' "s/host='127.0.0.1'/host='0.0.0.0'/" __main__.py   # GNU sed: use  sed -i
+#   docker build -f Containerfile -t helloworld-a2a-server .
+#   docker run -d -p 9999:9999 helloworld-a2a-server
+#
+# Then run this agent:  slack-agents run agents/a2a-agent
+
+version: "1.0.0"
+schema: "slack-agents/v1"
+
+slack:
+  bot_token: "{SLACK_BOT_TOKEN}"
+  app_token: "{SLACK_APP_TOKEN}"
+
+access:
+  type: slack_agents.access.allow_all
+
+# --- Routing: enable exactly ONE of the two llm blocks below. ---
+
+# Option A (default) — smart routing: a real LLM delegates to the A2A agent as a
+# tool, decides when to call it, and synthesizes the reply.
+
+# # Try in Slack:  "ask the a2a agent to say hello to Jim"  -> it sends "Hello Jim!" to the agent.
+
+llm:
+  type: slack_agents.llm.anthropic
+  model: claude-sonnet-4-6
+  api_key: "{ANTHROPIC_API_KEY}"
+  max_tokens: 4096
+  max_input_tokens: 200000
+
+# Option B — dumb frontend (dev/debugging): no local LLM. Every user message is
+# forwarded straight to the single A2A agent and its reply relayed back. To use
+# it, comment out the Option A block above and uncomment this one. `model` is the
+# a2a tool's key under `tools:` below.
+
+# Try in Slack:  "Jim"  -> it echoes your request.
+
+#llm:
+#  type: slack_agents.a2a.proxy
+#  model: "mya2a"
+
+storage:
+  type: slack_agents.storage.sqlite
+  path: ":memory:"
+
+tools:
+  # The remote A2A agent, exposed to the LLM as one free-text tool named after this
+  # key ("mya2a"). Rename the key to rename the tool.
+  mya2a:
+    type: slack_agents.a2a.agent
+    url: "http://127.0.0.1:9999"
+    auth: {}
+
+  # Lets the framework ACCEPT Slack file uploads; the a2a tool then forwards the
+  # raw bytes to the agent. (With Option A the LLM also sees the extracted text.)
+  import-files:
+    type: slack_agents.tools.file_importer
+    allowed_functions: [".*"]

python_slack_agents-0.9.1/agents/a2a-agent/system_prompt.txt

@@ -0,0 +1 @@
+You are a helpful assistant. Be concise and friendly.

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/agents/docs-assistant/system_prompt.txt

@@ -1,4 +1,4 @@
 You are a documentation assistant. You can search GitHub repositories for
 documentation using the DeepWiki tool and create PDF documents.
 
-When asked about a project, search for its documentation first, then summarize.
+When asked about a project, search for its documentation first, then summarize.

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/agents/hello-world/system_prompt.txt

@@ -1,3 +1,2 @@
 You are a helpful assistant. Be concise and friendly.
 Ask people if they want to know the secret but only tell them if they ask: "yellow submarine".
-

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/agents/kitchen-sink/config.yaml

@@ -146,4 +146,4 @@ tools:
 #        model: "langfuse.observation.model.name"
 #        input_tokens: "gen_ai.usage.input_tokens"
 #        output_tokens: "gen_ai.usage.output_tokens"
-#        usage: "langfuse.observation.usage_details"
+#        usage: "langfuse.observation.usage_details"

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/agents/kitchen-sink/system_prompt.txt

@@ -1 +1 @@
-You are a helpful assistant. This agent is configured as an example showcasing all available config options.
+You are a helpful assistant. This agent is configured as an example showcasing all available config options.

python_slack_agents-0.9.1/docs/a2a.md

@@ -0,0 +1,384 @@
+# Agent2Agent (A2A) integration
+
+`slack_agents.a2a.agent` and `slack_agents.a2a.proxy` connect this framework
+to remote agents over the
+[Agent2Agent protocol](https://a2a-protocol.org). A2A is an interaction
+protocol — the remote agent is an opaque, possibly-conversational message
+endpoint that describes itself via an Agent Card. The framework treats it as a
+single free-text channel (not a menu of typed tools the way MCP does).
+
+Built on the official [`a2a-sdk`](https://github.com/a2aproject/a2a-python)
+(1.x, protobuf-based). All SDK-specific code is isolated in
+`slack_agents.a2a.client`; the rest of the package depends only on a small
+stable interface, so SDK version changes are contained to one module.
+
+Two deployment topologies are supported from one codebase:
+
+- **Option A — smart router.** A real local LLM (`slack_agents.llm.anthropic`,
+  etc.) orchestrates a conversation and delegates to one or more remote A2A
+  agents exposed as tools (`slack_agents.a2a.agent`). The local LLM decides
+  when and how to invoke each agent, synthesizes the replies, and continues the
+  conversation normally. Multiple A2A agents can coexist alongside other tool
+  providers.
+- **Option B — dumb frontend.** No local reasoning at all. `slack_agents.a2a.proxy`
+  forwards every user message to a single remote A2A agent and relays the reply
+  back. Slack becomes a thin chat front-end; the intelligence lives entirely in
+  the remote agent. This is primarily a **development/debugging convenience** for
+  poking at an A2A agent directly through Slack — Option A is the production shape.
+
+## Configuration
+
+### Option A — smart router
+
+```yaml
+llm:
+  type: slack_agents.llm.anthropic
+  model: claude-sonnet-4-6
+  api_key: "{ANTHROPIC_API_KEY}"
+  max_tokens: 4096
+  max_input_tokens: 200000
+tools:
+  research-agent:
+    type: slack_agents.a2a.agent
+    url: "https://research.example.com"
+    auth: { type: bearer, token: "{RESEARCH_A2A_TOKEN}" }
+    poll_interval: 5
+    max_task_lifetime: 3600
+```
+
+### Option B — dumb frontend
+
+```yaml
+llm:
+  type: slack_agents.a2a.proxy
+  model: "mya2a"
+  max_input_tokens: 200000
+tools:
+  mya2a:
+    type: slack_agents.a2a.agent
+    url: "https://remote-agent.example.com"
+    auth: { type: bearer, token: "{A2A_API_KEY}" }
+```
+
+The system prompt is ignored in Option B; it is used normally in Option A.
+
+## `a2a.agent` — tool provider
+
+`slack_agents.a2a.agent` is a `BaseToolProvider`. At startup it fetches the
+remote agent's Agent Card and registers a single tool — named after the
+provider's key under `tools:` — using the card's description.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `url` | `str` | required | Base URL of the remote agent. The framework tries `<url>/.well-known/agent-card.json` automatically. |
+| `auth` | `dict` | none | Auth credentials. See [Auth](#auth) below. |
+| `timeout` | `float` | `300` | HTTP timeout in seconds for individual A2A requests. |
+| `poll_interval` | `float` | `5` | Seconds between polling attempts for long-running tasks. |
+| `max_task_lifetime` | `float` | `3600` | Maximum seconds to poll before abandoning a task and delivering a timeout message. |
+
+**One tool per agent.** A2A is a single opaque channel — it has no mechanism to
+advertise a menu of typed tools the way MCP does. Each `a2a.agent` provider
+exposes exactly one free-text tool, named after its key under `tools:`
+(slugified to satisfy the LLM tool-name rules — letters, digits, `_`, `-`).
+Rename the key to rename the tool; the key is also unique within `tools:`, so
+two agents never collide:
+
+```json
+{
+  "name": "<tools: key, slugified>",
+  "description": "<from Agent Card>",
+  "input_schema": {
+    "type": "object",
+    "properties": { "message": { "type": "string" } },
+    "required": ["message"]
+  }
+}
+```
+
+**Conversation continuity.** The framework tracks the A2A `contextId` (and, for
+multi-turn tasks, the `taskId`) per Slack thread, transparently — the LLM never
+sees or passes these. Successive messages in the same thread are sent on the
+same `contextId` so the remote agent can keep conversational state.
+
+When the agent replies with an **`input-required`** (or `auth-required`) state —
+i.e. it is mid-task and wants another message — the framework relays the agent's
+prompt to the user and **threads the same `taskId`** on the next message, so the
+exchange continues the *same* Task (and its server-side state). When the task
+reaches a terminal state, the saved `taskId` is cleared and the next message
+starts a fresh Task. This is what makes multi-turn agents (e.g. a step-by-step
+form or a guessing game) behave correctly instead of restarting each turn.
+
+**Files.** File attachments flow in both directions. A file a user uploads in
+Slack is forwarded to the agent as an A2A `raw` part (alongside the text); a
+file the agent returns as an artifact is surfaced back into the Slack thread as
+an upload. Non-text artifacts (CSV, PDF, …) come through as files; text
+artifacts are used as the reply.
+
+To **send** files you must also configure a file-import handler (e.g.
+`slack_agents.tools.file_importer`) in `tools:` — the framework only accepts
+uploads it has a handler for, and the a2a tool then forwards the raw bytes:
+
+```yaml
+tools:
+  mya2a:
+    type: slack_agents.a2a.agent
+    url: "https://remote-agent.example.com"
+  import-files:
+    type: slack_agents.tools.file_importer
+    allowed_functions: [".*"]
+```
+
+## `a2a.proxy` — passthrough LLM
+
+`slack_agents.a2a.proxy` is a `BaseLLMProvider` that does no local reasoning.
+It drives the same conversation loop as any other LLM provider, but instead of
+calling an LLM it routes directly to the configured A2A tool.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | `str` | — | Name of the target `a2a.agent` tool (the key under `tools:` in `config.yaml`). When set, it is always used. When omitted, the proxy auto-selects the tool **only if exactly one** is configured; with more than one tool and no `model:`, startup fails with an error. |
+| `max_input_tokens` | `int` | `200000` | Context-window guard, passed through to the loop. |
+
+## Auth
+
+### Static / API-key auth (service-level)
+
+Credentials are resolved from environment variables at startup via the standard
+`{ENV_VAR}` interpolation. These are shared across all users.
+
+```yaml
+# Bearer token — Authorization: Bearer <token>
+auth: { type: bearer, token: "{A2A_API_KEY}" }
+
+# Arbitrary header
+auth: { type: header, name: "X-API-Key", value: "{A2A_API_KEY}" }
+
+# API-key scheme — sends the raw value as the named header
+# (matches an Agent Card that advertises apiKey security)
+auth: { type: apiKey, name: "Authorization", value: "{A2A_API_KEY}" }
+
+# No auth (default when omitted)
+auth: { type: none }
+```
+
+### Per-user OAuth (`auth: { type: oauth2 }`)
+
+Each Slack user authenticates separately to the remote agent. The framework
+uses that user's access token on subsequent calls, exactly as it does for
+OAuth-protected MCP servers (see [docs/oauth.md](oauth.md)).
+
+```yaml
+tools:
+  research-agent:
+    type: slack_agents.a2a.agent
+    url: "https://research.example.com"
+    auth: { type: oauth2 }
+```
+
+There is intentionally no `client_id`/`scopes` field. The provider discovers
+OAuth metadata from the remote agent's **Agent Card** (`securitySchemes.oauth2`
+→ `oauth2MetadataUrl`), performs Dynamic Client Registration, and uses the
+auth-code + PKCE flow. This means a server whose RFC 9728 protected-resource-metadata
+endpoint is missing or internal still works as long as its Agent Card advertises
+the oauth2 scheme and `oauth2MetadataUrl`.
+
+**User experience.** The first time a user invokes an OAuth-protected A2A agent,
+the framework posts an ephemeral "Authenticate" button in Slack. Clicking it
+opens the remote agent's auth server in the user's browser. After consent the
+browser redirects to the shared callback URL and the original request is
+completed automatically.
+
+**Required environment variables.** Per-user OAuth needs the shared ingress
+(same as MCP OAuth) — configure `PUBLIC_URL` and `OAUTH_SECRET_KEY` exactly
+as described in [docs/oauth.md](oauth.md#required-environment-variables). These
+are validated at startup; the agent refuses to start if they are missing or
+malformed.
+
+## Long-running tasks
+
+The A2A protocol distinguishes between tasks that complete quickly and tasks
+that may take minutes or hours. The framework handles both transparently.
+
+The client sends every message with `blocking: true`, requesting that the
+server wait for completion before responding. This is only a hint — the server
+is free to return a non-terminal (`working`) task for long jobs.
+
+**Synchronous path.** If the remote agent returns a terminal result
+(`completed`, `failed`, `canceled`, or `rejected`) immediately, the result is
+returned inline to the LLM (Option A) or relayed directly to Slack (Option B).
+
+**Background-polling path.** If the remote agent returns a non-terminal
+(`submitted` or `working`) task, the framework:
+
+1. Persists an in-flight record (task ID, context, thread, channel) to the
+   storage backend.
+2. Returns an acknowledgement to the LLM/proxy immediately
+   ("Started a longer task — I'll post the result here when it's ready.").
+3. Spawns a background poller that calls `tasks/get` every `poll_interval`
+   seconds until the task reaches a terminal state or `max_task_lifetime` is
+   exceeded.
+4. On completion, delivers the result **out-of-band** into the original Slack
+   thread:
+   - **Option A (real LLM):** the result is injected as a synthetic inbound
+     turn and the standard loop re-runs, so the local LLM can interpret or act
+     on it before replying to the user.
+   - **Option B (proxy):** the result text is posted directly to the thread
+     without re-entering the loop (the proxy has no intelligence to add).
+
+This is entirely outbound — the background poller calls the remote agent's
+`tasks/get` endpoint on a timer. No public URL or inbound HTTP listener is
+needed. The Socket Mode deploy-anywhere property is preserved.
+
+**Crash resilience.** In-flight task records are persisted in the storage
+backend. If the agent process restarts while tasks are in flight, they are
+re-discovered at startup and pollers are resumed automatically.
+
+**OAuth and async delivery.** The two async paths behave differently with
+respect to the user's token, and the framework is **push-preferred**:
+
+- **Push (webhook).** Delivery is *inbound* — the agent POSTs updates to the
+  ingress, which relays them to Slack without ever calling the agent back. No
+  token is involved at delivery time, so a task started while the user was
+  authenticated **still delivers even if their OAuth token later expires or is
+  revoked.** When a push webhook is registered for a task, the framework does
+  **not** also run the poller for it (avoiding redundant — potentially double —
+  delivery).
+- **Polling (fallback, no push).** Only used when push is not registered (the
+  agent doesn't support it, or no `PUBLIC_URL`). The poller calls `tasks/get`
+  *outbound*, which requires the user's token: it builds a fresh per-user client
+  from the stored token and refreshes silently — no Slack interaction happens
+  out-of-band. If the token cannot be refreshed (revoked, or the refresh
+  expired), the bot posts "Your session for this task has expired — please ask
+  again and re-authenticate when prompted." to the thread, instead of prompting
+  out-of-band where there is no safe way to do so.
+
+## What a Slack user sees
+
+**For a fast response (synchronous path):**
+
+1. User asks the bot something.
+2. The bot forwards the message to the remote A2A agent and replies with the
+   result, same as any other tool call.
+
+**For a long-running task (async path):**
+
+1. User asks the bot something.
+2. The bot replies: "Started a longer task — I'll post the result here when
+   it's ready."
+3. When the remote agent finishes, the result appears in the same Slack thread.
+
+## Trying it against a reference agent
+
+You don't need to write an A2A agent to try the integration — point it at the
+official [`helloworld`](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/agents/helloworld)
+sample (a2a-sdk 1.x, no API key). It's a simple echo, so it exercises the core
+path — Agent Card resolution, send, completion, artifact handling — but not
+multi-turn or files.
+
+```bash
+git clone --depth 1 https://github.com/a2aproject/a2a-samples /tmp/a2a-samples
+cd /tmp/a2a-samples/samples/python/agents/helloworld
+
+# The upstream Containerfile's CMD passes --host 0.0.0.0, but __main__.py hardcodes
+# 127.0.0.1, so it binds container-loopback and isn't reachable from the host.
+# Make it bind 0.0.0.0 (the card's advertised url stays 127.0.0.1:9999, which is
+# correct for a client on the host):
+sed -i '' "s/host='127.0.0.1'/host='0.0.0.0'/" __main__.py   # GNU sed: use  sed -i
+
+docker build -f Containerfile -t helloworld-a2a-server .
+docker run -d -p 9999:9999 helloworld-a2a-server
+```
+
+Set `url: "http://127.0.0.1:9999"` in your `a2a.agent` config and message the
+bot — it replies `Hello, World! I have received your request (...)`. A ready-made
+example lives at [`agents/a2a-agent/config.yaml`](../agents/a2a-agent/config.yaml),
+which documents both the smart-routing and proxy topologies (proxy commented out
+for easy switching) and repeats these server-start steps inline.
+
+**Integration test.** `tests/a2a/test_integration.py` drives the real client
+against a live agent and is **skipped unless `A2A_TEST_URL` is set**, so it
+never affects CI:
+
+```bash
+A2A_TEST_URL=http://127.0.0.1:9999 pytest tests/a2a/test_integration.py -v
+```
+
+The assertions are agent-agnostic — the same test works against any conformant
+A2A agent.
+
+## Push notifications
+
+When a remote agent supports push (`capabilities.pushNotifications`), the
+framework can register a **webhook** so the agent delivers task updates —
+status messages and file artifacts — to the Slack thread out-of-band, including
+reports that arrive *after* a synchronous reply. This is the unified,
+**push-preferred** async path; the background poller remains the fallback for
+agents that don't support push.
+
+**Enable it** with `push_notifications: true` on the `a2a.agent` config (opt-in,
+because push requires a publicly reachable URL):
+
+```yaml
+tools:
+  mya2a:
+    type: slack_agents.a2a.agent
+    url: "https://remote-agent.example.com"
+    push_notifications: true
+```
+
+**Ingress.** Push needs the in-process HTTP listener (shared with OAuth) and a
+public URL the agent can POST to. Configure:
+
+| Env | Default | Purpose |
+|-----|---------|---------|
+| `PUBLIC_URL` | — (required) | Public base URL of the ingress; the webhook is `<PUBLIC_URL>/a2a/push`. |
+| `HTTP_BIND_HOST` | `0.0.0.0` | Listener bind host. |
+| `HTTP_BIND_PORT` | `8080` | Listener bind port. |
+
+This is the one A2A feature that needs **inbound** HTTP — unlike the polling
+path, which is outbound-only. For local testing the URL can be a loopback
+(`http://127.0.0.1:8080`) reachable by an agent on the same host.
+
+**How it works.** On the first send the framework registers the webhook inline
+(`SendMessageConfiguration.task_push_notification_config`) with a random
+per-task token, and persists a `taskId → thread` record. Incoming POSTs are
+validated against the token, correlated by `taskId`, **de-duplicated** by
+message/artifact id (the server re-pushes the immediate reply, which we already
+delivered synchronously), and any genuinely-new text/files are posted/uploaded
+to the thread.
+
+**Security & limits.** We validate the shared-secret token and only act on tasks
+we registered. The protocol's signing (JWS) and SSRF-allowlist are server-side
+concerns we don't yet rely on. There are no delivery retries (the agent sends a
+single POST), and a *server* restart drops its own registration — so a
+previously-registered task simply stops pushing.
+
+## Current limitations
+
+The following are not yet implemented. They are planned for future releases.
+
+- **Files: image uploads and the async path.** *Receiving* files works for any
+  type. When *sending*, only non-image uploads (CSV, PDF, DOCX, …) are forwarded
+  — images are not yet — and files are forwarded/surfaced only on the synchronous
+  path (a long-running task delivered out-of-band carries its text, not files).
+- **Atomic responses.** Responses are collected in full before being posted.
+  Token-by-token streaming to Slack is not supported yet.
+- **No A2A server mode.** This framework cannot be addressed as an A2A agent
+  by other agents. It is a client only.
+
+## Troubleshooting
+
+**"A2A agent returned a long-running task but async delivery is unavailable."**
+— the `a2a.agent` provider was not given a `framework_ctx` (injected
+automatically by the framework when the provider is loaded via `config.yaml`).
+This should not happen in normal operation; it can appear in test setups that
+construct the provider directly without the framework context.
+
+**The background poller never delivers a result.** Check that `poll_interval`
+and `max_task_lifetime` are appropriate for the remote agent. If the agent
+takes longer than `max_task_lifetime`, the task is abandoned and a timeout
+message is posted to the thread. Increase `max_task_lifetime` if needed.
+
+**"a2a.proxy: set `model:` to the target a2a tool name"** — you have more than
+one tool configured and the proxy doesn't know which one to route to. Set
+`model:` under the `llm:` section to the key of the intended `a2a.agent` tool.

{python_slack_agents-0.8.1 → python_slack_agents-0.9.1}/docs/oauth.md

@@ -35,10 +35,10 @@ single consolidated error message.
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `OAUTH_PUBLIC_URL` | yes | — | Externally reachable base URL of this agent process. Must be `https://`, or `http://` with a loopback host (`localhost`, `127.0.0.1`, `[::1]`) for local dev. |
+| `PUBLIC_URL` | yes | — | Externally reachable base URL of this agent process (shared with A2A push). Must be `https://`, or `http://` with a loopback host (`localhost`, `127.0.0.1`, `[::1]`) for local dev. |
 | `OAUTH_SECRET_KEY` | yes | — | Root key for HKDF; ≥32 bytes after base64 decode. Used to sign OAuth state tokens and encrypt refresh tokens at rest. |
-| `OAUTH_BIND_HOST` | no | `0.0.0.0` | Interface the in-process callback listener binds to. |
-| `OAUTH_BIND_PORT` | no | `8080` | TCP port for the callback listener. |
+| `HTTP_BIND_HOST` | no | `0.0.0.0` | Interface the in-process listener binds to (shared ingress). |
+| `HTTP_BIND_PORT` | no | `8080` | TCP port for the listener (shared ingress). |
 
 ### Generating `OAUTH_SECRET_KEY`
 
@@ -67,13 +67,13 @@ ngrok http 8080
 # → forwards https://abcd-1234.ngrok-free.app to localhost:8080
 
 # Terminal 2 — set env vars and run the agent:
-export OAUTH_PUBLIC_URL=https://abcd-1234.ngrok-free.app
+export PUBLIC_URL=https://abcd-1234.ngrok-free.app
 export OAUTH_SECRET_KEY=$(openssl rand -base64 32)
 slack-agents run agents/my-agent
 ```
 
 If you'd rather not use a tunnel, you can run with
-`OAUTH_PUBLIC_URL=http://localhost:8080` — the validator allows loopback
+`PUBLIC_URL=http://localhost:8080` — the validator allows loopback
 addresses over plain HTTP per RFC 8252.
 
 ## What a Slack user sees
@@ -190,7 +190,7 @@ plaintext (still in the private DB).
 
 ## Troubleshooting
 
-**"Configuration error: ... OAUTH_PUBLIC_URL is not set"** — set the env vars
+**"Configuration error: ... PUBLIC_URL is not set"** — set the env vars
 listed in the message and restart.
 
 **"Authentication timed out"** — the user didn't click the link within