Skip to content

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.py
index 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():
return
for 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), but
can still hit this for a private channel/DM, so slack_post_message uses
this too.
@@ -544,7 +553,8 @@ def _request_requiring_membership(
joining changes the channel's member list, which is visible to everyone
in it, so the calling agent should check with the user first and only
then 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 build
the option list for an ask_user_question when the user has not named a
channel. 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 this
request, described unambiguously as a set by its membership (e.g. "every
channel 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 fetch
the 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 its
topic, 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, by
default, 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 look
for 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 an
diff --git a/tests/web/tools/test_slack_channel_access_policy.py b/tests/web/tools/test_slack_channel_access_policy.py
index 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.py
index 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 agent
away 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 conversations
even when the bot can already read them. Pin the phrases the agent
relies 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(monkeypa
assert 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,