Enterprise agent platform for building, deploying, and operating AI teammates.
fix(slack): tell the agent which public channels the bot can read (#3770)
leyoonafr4f080d44f8ab
diff --git a/src/xagent/web/tools/mcp/slack.py b/src/xagent/web/tools/mcp/slack.pyindex 2f6234240..c271747b2 100644--- a/src/xagent/web/tools/mcp/slack.py+++ b/src/xagent/web/tools/mcp/slack.py@@ -69,6 +69,13 @@ def _write_tool(fn: Callable[..., str]) -> Callable[..., str]:return mcp.tool()(fn)+def _runtime_policy_installed() -> bool:+ """Whether a runtime policy is installed; the server then offers no write+ tools, slack_join_channel included."""++ return os.environ.get(_CHANNEL_ACCESS_POLICY_ENV_VAR) is not None++def _drop_tools_the_policy_forbids() -> None:"""Hide the write tools from a server started under a runtime policy.@@ -79,7 +86,7 @@ def _drop_tools_the_policy_forbids() -> None:each write tool remains the enforcement; this only stops offering them."""- if os.environ.get(_CHANNEL_ACCESS_POLICY_ENV_VAR) is None:+ if not _runtime_policy_installed():returnfor name in sorted(_WRITE_TOOL_NAMES):mcp.remove_tool(name)@@ -510,13 +517,15 @@ def _request_requiring_membership(json_data: dict[str, Any] | None = None,membership_already_proven: bool = False,) -> dict[str, Any]:- """Call a Slack endpoint that requires the bot to already be a channel- member, and raise an actionable error if it isn't yet.-- This covers conversations.history/replies/info (regardless of which- *:history scopes are granted), reactions.add/remove, and- files.completeUploadExternal — none of them work for a channel the bot- hasn't joined. chat.postMessage is the one exception for a *public*+ """Call a Slack endpoint that can fail because the bot is not a member of+ the channel, and raise an actionable error if it does.++ conversations.history/replies (regardless of which *:history scopes are+ granted), reactions.add/remove, and files.completeUploadExternal need+ membership: none of them work for a channel the bot hasn't joined.+ conversations.info is routed through here too, because a conversation+ hidden from the bot fails it with the same codes (e.g.+ channel_not_found). chat.postMessage is the one exception for a *public*channel (chat:write.public lets a bot post there without joining), butcan still hit this for a private channel/DM, so slack_post_message usesthis too.@@ -544,7 +553,8 @@ def _request_requiring_membership(joining changes the channel's member list, which is visible to everyonein it, so the calling agent should check with the user first and onlythen call slack_join_channel — never silently, just because a call- failed.+ failed. Under a runtime policy slack_join_channel is not offered, so the+ error asks for a channel member to `/invite` the bot instead."""not_a_member_codes = _NOT_A_MEMBER_CODES_BY_PATH.get(path, _DEFAULT_NOT_A_MEMBER_CODES@@ -576,13 +586,23 @@ def _request_requiring_membership(# not_in_channel is unambiguous per Slack's own docs — no need# to hedge.cause = "because the bot isn't a member of it"+ if _runtime_policy_installed():+ # slack_join_channel is not offered under a policy (see+ # _drop_tools_the_policy_forbids), so only a member can add it.+ advice = (+ "tell the user the bot has to be added first — a member of "+ "the channel needs to run `/invite @<this app's bot name>`."+ )+ else:+ advice = (+ "ask the user whether to add the bot to it; if they agree, "+ "call slack_join_channel (only works for a public channel) — "+ "for a private channel or DM, a member needs to run "+ "`/invite @<this app's bot name>` instead."+ )raise _SlackNotAMemberError(- f"{e.code}: the bot cannot access this channel — {cause}. If "- "the channel is genuinely there: ask the user whether to add "- "the bot to it; if they agree, call slack_join_channel (only "- "works for a public channel) — for a private channel or DM, "- "a member needs to run `/invite @<this app's bot name>` "- "instead."+ f"{e.code}: the bot cannot access this channel — {cause}. If the "+ f"channel is genuinely there: {advice}") from None@@ -667,7 +687,12 @@ def slack_list_channels(limit: int = MAX_CHANNELS,) -> str:"""- List public channels in the connected Slack workspace (id, name, is_archived).+ List public channels in the connected Slack workspace (id, name,+ is_archived, is_member).+ is_member: whether this connector's bot is in the channel — true or+ false as Slack reports it, null when Slack did not say (unknown, not+ false). Before reading a listed channel, apply+ slack_get_channel_history's membership rule.Use this to resolve a channel name to an id before posting, or to buildthe option list for an ask_user_question when the user has not named achannel. The list is discovery, not permission: do not read every@@ -727,6 +752,10 @@ def slack_list_channels("id": channel.get("id"),"name": channel.get("name"),"is_archived": channel.get("is_archived", False),+ # None when Slack omits it: unknown, not "not a+ # member" — a wrong False would make the agent refuse+ # a channel it can read.+ "is_member": channel.get("is_member"),})if len(channels) >= max_channels:@@ -815,11 +844,20 @@ def slack_get_channel_history(Each message includes its "ts" (needed for slack_get_thread_replies,slack_add_reaction, and replying via slack_post_message's thread_ts) and,when it starts a thread, "thread_ts" and "reply_count".- If the bot isn't a member of the channel yet, you'll get an actionable- error instead of an empty/opaque failure: check with the user before- calling slack_join_channel to add the bot (only works for a public- channel), or ask a member to `/invite` the bot for a private channel or- DM.+ Membership rule: this connector reads with a bot token, and a bot can+ read a public channel only while it is a member. A public channel that+ slack_list_channels returned with is_member false cannot be read yet:+ do not call slack_get_channel_history, slack_get_thread_replies or+ slack_search_messages on it — tell the user the bot has to be added+ first (a member of the channel runs `/invite @<this app's bot name>`).+ When slack_join_channel is available, you may instead offer to add the+ bot with it, and call it only once the user agrees. An archived channel+ cannot be joined or invited into; say so instead. If the user says the+ bot has since been added, list the channels again or read once: an+ earlier listing may be stale. For a conversation the listing does not+ cover (a private channel, a DM, an id passed directly, or a channel+ named without listing first), just read it: if the bot cannot, the read+ fails with an error that says what to do, not an empty result.Scope rule: read only conversations the user asked for — named in thisrequest, described unambiguously as a set by its membership (e.g. "everychannel whose name starts with support-"), or selected in a previous@@ -884,11 +922,8 @@ def slack_get_thread_replies(thread_ts: the parent message's "ts".cursor: pass the next_cursor from a previous call's response to fetchthe next page of replies.- If the bot isn't a member of the channel yet, you'll get an actionable- error instead of an empty/opaque failure: check with the user before- calling slack_join_channel to add the bot (only works for a public- channel), or ask a member to `/invite` the bot for a private channel or- DM.+ If the bot isn't a member of the channel, see+ slack_get_channel_history's membership rule."""try:channel_id = _resolve_channel_id(channel)@@ -930,11 +965,8 @@ def slack_get_channel_info(channel: str) -> str:"""Get metadata for a channel, private channel, or DM — including itstopic, purpose, member count, and archived/private flags.- If the bot isn't a member of the channel yet, you'll get an actionable- error instead of an empty/opaque failure: check with the user before- calling slack_join_channel to add the bot (only works for a public- channel), or ask a member to `/invite` the bot for a private channel or- DM.+ slack_get_channel_history's membership rule does not block this call; if+ it fails because the bot isn't a member, follow the error."""try:channel_id = _resolve_channel_id(channel)@@ -1069,10 +1101,7 @@ def slack_search_messages(Search a channel, private channel, or DM's recent history (and, bydefault, its threads' replies) for messages containing `query`(case-insensitive substring match). If the bot isn't a member of the- channel yet, you'll get an actionable error instead of an empty/opaque- failure: check with the user before calling slack_join_channel to add- the bot (only works for a public channel), or ask a member to `/invite`- the bot for a private channel or DM.+ channel, see slack_get_channel_history's membership rule.limit: max matching messages to return (default 50, capped at 1000).scan_limit: max messages to scan from the conversation's history to lookfor matches in (default 200, capped at 1000) — distinct from `limit`,@@ -1185,7 +1214,7 @@ def slack_search_messages(# gap distinct from threads never attempted at all# (below) — it must still flag truncated even though# threads_scanned already counts the attempt for budget- # purposes. An actionable "call slack_join_channel"+ # purposes. An actionable not-a-member or missing-scope# message always wins over a later transient one (rate# limit, etc.) or over the history-pagination failure# above, so a membership problem is never masked by andiff --git a/tests/web/tools/test_slack_channel_access_policy.py b/tests/web/tools/test_slack_channel_access_policy.pyindex 4be9b40b5..77259fca4 100644--- a/tests/web/tools/test_slack_channel_access_policy.py+++ b/tests/web/tools/test_slack_channel_access_policy.py@@ -242,6 +242,66 @@ def test_listings_filter_out_of_policy_conversations(assert request.call_args.kwargs["params"]["types"] == types+def test_policy_lists_an_allowed_channel_the_bot_is_not_in(monkeypatch) -> None:+ # The policy decides which channels may be read; membership decides which+ # can be read right now. An allowed channel the bot has not joined stays+ # in the listing, marked, so the agent can ask for the bot to be added.+ _install_policy(monkeypatch)+ response = Mock(+ status_code=200,+ json=Mock(+ return_value={+ "ok": True,+ "channels": [+ {"id": ALLOWED, "name": "allowed", "is_member": False},+ {"id": DENIED, "name": "denied", "is_member": True},+ ],+ }+ ),+ raise_for_status=Mock(),+ )+ monkeypatch.setattr(slack.requests, "request", Mock(return_value=response))++ result = json.loads(slack.slack_list_channels())++ assert [(c["id"], c["is_member"]) for c in result["channels"]] == [(ALLOWED, False)]+++ "read, slack_error",+ [+ (lambda: slack.slack_get_channel_history(ALLOWED), "not_in_channel"),+ (+ lambda: slack.slack_get_thread_replies(ALLOWED, "1700000000.000100"),+ "not_in_channel",+ ),+ # Slack documents channel_not_found, not not_in_channel, for+ # conversations.info.+ (lambda: slack.slack_get_channel_info(ALLOWED), "channel_not_found"),+ (lambda: slack.slack_search_messages(ALLOWED, "deploy"), "not_in_channel"),+ ],+ ids=["history", "thread_replies", "channel_info", "search"],+)+def test_not_a_member_error_under_a_policy_asks_for_invite_not_join(+ monkeypatch, read, slack_error+) -> None:+ # A policy server drops slack_join_channel at startup, so the error must+ # not send the agent to it; adding the bot is left to a channel member.+ _install_policy(monkeypatch)+ response = Mock(+ status_code=200,+ json=Mock(return_value={"ok": False, "error": slack_error}),+ raise_for_status=Mock(),+ )+ monkeypatch.setattr(slack.requests, "request", Mock(return_value=response))++ result = json.loads(read())++ assert result["status"] == "error"+ assert "/invite" in result["message"]+ assert "slack_join_channel" not in result["message"]++def test_policy_absence_preserves_legacy_user_id_posting(monkeypatch) -> None:response = Mock(status_code=200,diff --git a/tests/web/tools/test_slack_mcp.py b/tests/web/tools/test_slack_mcp.pyindex 8bde7b45f..d7be11577 100644--- a/tests/web/tools/test_slack_mcp.py+++ b/tests/web/tools/test_slack_mcp.py@@ -222,8 +222,18 @@ def test_list_channels_returns_flat_list(monkeypatch):{"ok": True,"channels": [- {"id": "C1", "name": "general", "is_archived": False},- {"id": "C2", "name": "incidents", "is_archived": False},+ {+ "id": "C1",+ "name": "general",+ "is_archived": False,+ "is_member": True,+ },+ {+ "id": "C2",+ "name": "incidents",+ "is_archived": False,+ "is_member": False,+ },],})@@ -234,12 +244,69 @@ def test_list_channels_returns_flat_list(monkeypatch):assert result["status"] == "success"assert result["channels"] == [- {"id": "C1", "name": "general", "is_archived": False},- {"id": "C2", "name": "incidents", "is_archived": False},+ {"id": "C1", "name": "general", "is_archived": False, "is_member": True},+ {"id": "C2", "name": "incidents", "is_archived": False, "is_member": False},]assert result["truncated"] is False+def test_list_channels_reports_whether_the_bot_is_a_member(monkeypatch):+ """A bot token reads only channels the bot is in, so the listing must say+ which those are. Slack's own value passes through; a channel Slack sent+ without the field is unknown (null), never "not a member", because a+ wrong false would make the agent refuse a channel it can read."""+ monkeypatch.setattr(+ slack.requests,+ "request",+ Mock(+ return_value=MockResponse(+ {+ "ok": True,+ "channels": [+ {"id": "C1", "name": "general", "is_member": True},+ {"id": "C2", "name": "random", "is_member": False},+ {"id": "C3", "name": "announcements"},+ ],+ }+ )+ ),+ )++ result = json.loads(slack.slack_list_channels())++ assert {c["id"]: c["is_member"] for c in result["channels"]} == {+ "C1": True,+ "C2": False,+ "C3": None,+ }+++def test_list_channels_keeps_membership_when_filtering_by_name(monkeypatch):+ monkeypatch.setattr(+ slack.requests,+ "request",+ Mock(+ return_value=MockResponse(+ {+ "ok": True,+ "channels": [+ {"id": "C1", "name": "support-eu", "is_member": True},+ {"id": "C2", "name": "general", "is_member": True},+ {"id": "C3", "name": "support-us", "is_member": False},+ ],+ }+ )+ ),+ )++ result = json.loads(slack.slack_list_channels(name_contains="support"))++ assert [(c["id"], c["is_member"]) for c in result["channels"]] == [+ ("C1", True),+ ("C3", False),+ ]++@pytest.mark.parametrize(("value", "serialized"), [(True, "true"), (False, "false")])def test_list_channels_serializes_exclude_archived_lowercase(monkeypatch, value, serialized@@ -914,6 +981,15 @@ async def test_join_channel_is_discoverable_via_mcp_list_tools():assert "explicitly confirmed" in (tool.description or "")+async def _tool_descriptions() -> dict[str, str]:+ # Collapse the docstring line wrapping so the assertions pin phrases, not+ # where a sentence happens to break across lines.+ return {+ t.name: " ".join((t.description or "").split())+ for t in await slack.mcp.list_tools()+ }++async def test_read_tools_expose_channel_scope_rule_via_mcp_list_tools():"""The read/list tools' docstrings are the only thing steering the agentaway from sweeping every listed conversation: a broad request ("check my@@ -921,12 +997,7 @@ async def test_read_tools_expose_channel_scope_rule_via_mcp_list_tools():selected ones, and a selection must exclude unselected conversationseven when the bot can already read them. Pin the phrases the agentrelies on so a docstring rewrite can't silently drop the rule."""- # Collapse the docstring line wrapping so the assertions pin phrases, not- # where a sentence happens to break across lines.- tools = {- t.name: " ".join((t.description or "").split())- for t in await slack.mcp.list_tools()- }+ tools = await _tool_descriptions()# slack_get_channel_history carries the canonical rule; the other# conversation-reading tools point at it by name rather than repeating it.@@ -954,6 +1025,79 @@ async def test_read_tools_expose_channel_scope_rule_via_mcp_list_tools():assert "does not put it in scope for reading" in tools["slack_join_channel"]+async def test_read_tools_expose_membership_rule_via_mcp_list_tools():+ """A bot token reads a public channel only while the bot is in it, and+ nothing but these docstrings tells the agent to check slack_list_channels'+ is_member before reading. Without the rule the agent reads one listed+ channel after another and each fails with not_in_channel. Pin the phrases+ it relies on, the way the scope rule is pinned above."""+ tools = await _tool_descriptions()++ canonical = tools["slack_get_channel_history"]+ assert "this connector reads with a bot token" in canonical+ assert "a bot can read a public channel only while it is a member" in canonical+ assert "is_member false cannot be read yet" in canonical+ # Only the message reads need membership; slack_get_channel_info stays+ # usable for a channel the bot is not in.+ assert (+ "do not call slack_get_channel_history, slack_get_thread_replies or "+ "slack_search_messages on it" in canonical+ )+ assert "An archived channel cannot be joined or invited into" in canonical+ assert "`/invite @<this app's bot name>`" in canonical+ # A listing taken before the user added the bot must not block the read.+ assert "an earlier listing may be stale" in canonical+ # Joining stays user-gated where the tool exists (#1663).+ assert "call it only once the user agrees" in canonical+ # The join offer comes first, so "instead" in it cannot read as offering+ # to join an archived channel.+ assert canonical.index("When slack_join_channel is available") < (+ canonical.index("An archived channel cannot be joined")+ )++ assert "is_member" in tools["slack_list_channels"]+ for name in (+ "slack_list_channels",+ "slack_get_thread_replies",+ "slack_get_channel_info",+ "slack_search_messages",+ ):+ assert "slack_get_channel_history's membership rule" in tools[name], name+++async def test_membership_rule_does_not_block_channel_info():+ """The rule stops message reads only. Slack's conversations.info is not a+ message read, so its docstring must say the rule does not block it rather+ than point at a rule that names other tools."""+ tools = await _tool_descriptions()++ assert "membership rule does not block this call" in tools["slack_get_channel_info"]+++async def test_read_tools_mention_join_only_when_it_is_available():+ """A server under a runtime policy drops slack_join_channel, so a read+ tool's docstring that tells the agent to call it points at a tool the+ agent may not have. Every mention must be the conditional one."""+ tools = await _tool_descriptions()++ read_tools = set(tools) - slack._WRITE_TOOL_NAMES+ # Guard against a vacuous pass if the derivation ever yields too little.+ assert {+ "slack_list_channels",+ "slack_list_direct_messages",+ "slack_get_channel_history",+ "slack_get_thread_replies",+ "slack_get_channel_info",+ "slack_search_messages",+ } <= read_tools++ for name in sorted(read_tools):+ description = tools[name]+ assert description.count("slack_join_channel") == description.count(+ "When slack_join_channel is available"+ ), name++def test_join_channel_sends_expected_payload(monkeypatch):mock_request = Mock(return_value=MockResponse({"ok": True}))monkeypatch.setattr(slack.requests, "request", mock_request)@@ -1243,6 +1387,27 @@ def test_get_channel_history_reports_actionable_error_when_not_a_member(monkeypaassert mock_request.call_count == 1+def test_get_channel_history_no_policy_not_a_member_message_is_unchanged(monkeypatch):+ """Pins the exact no-policy advice text, so an edit made for the policy+ variant cannot change it unnoticed."""+ monkeypatch.delenv(slack._CHANNEL_ACCESS_POLICY_ENV_VAR, raising=False)+ mock_request = Mock(+ return_value=MockResponse({"ok": False, "error": "not_in_channel"})+ )+ monkeypatch.setattr(slack.requests, "request", mock_request)++ result = json.loads(slack.slack_get_channel_history("C0123456789"))++ assert result["message"] == (+ "not_in_channel: the bot cannot access this channel — because the "+ "bot isn't a member of it. If the channel is genuinely there: ask the "+ "user whether to add the bot to it; if they agree, call "+ "slack_join_channel (only works for a public channel) — for a "+ "private channel or DM, a member needs to run `/invite @<this app's "+ "bot name>` instead."+ )++# (conversations.history's channel_not_found handling was flipped to# actionable by a production incident — see# test_get_channel_history_hedges_channel_not_found_for_invalid_raw_id above,