/platform/docs/FAKE-SLACK-SPEC.md

FakeSlack — Standalone Slack test double (spec)

Status: separate deliverable (assign to a sub-agent). Build this first — the messaging integration tests in UI-REFRESH-VERIFICATION.md depend on it.

Goal: a controllable, local fake of the slices of Slack we use (Web API + Socket Mode), so the real SlackAdapter/Gateway can run end-to-end without the network, tokens, or the Slack app console. Replaces the manual COWORKER_DEBUG_INJECT flow with deterministic, scriptable tests.

Non-goals: not a faithful Slack (no real auth, no rate limits, no full schema). Implement only what the adapter calls + what tests need to drive.

---

How the app points at it (the one required adapter change)

The Slack adapter (coworker/connectors/adapters.py) builds slack_bolt.async_app.AsyncApp + AsyncSocketModeHandler, which talk to https://slack.com/api/. Add a base-URL override so it can target the fake:

• Accept an override (env SLACK_API_URL, default https://slack.com/api/) and pass it to the AsyncWebClient(base_url=…) the app uses. Slack's apps.connections.open is itself a Web API call, so the socket URL the fake returns flows from the same base — one override redirects both Web API and the Socket Mode connection.
• This is the only production-code change FakeSlack requires; keep it minimal and documented.

Tests/standalone set SLACK_API_URL=http://127.0.0.1:<port>/api/ and connect the adapter with any fake xoxb-/xapp- strings.

---

Surfaces

1. Web API (HTTP) — implement exactly what the adapter calls

Base path /<port>/api/<method>; all return {"ok": true, …} (or {"ok": false, "error": …} when a test asks for a failure). Methods:

Method	Request	Response	Notes
auth.test	bot token	{ok, user_id, team, team_id, url}	identifies the bot; user_id = the fake bot's id (loop-guard)
apps.connections.open	app token	{ok, url: "ws://127.0.0.1:<port>/socket"}	hands back the fake's WS URL
users.info	user	{ok, user:{id, name, real_name, profile:{display_name, real_name}}}	from the registered user table; unknown id → {ok:false,error:"user_not_found"}
conversations.info	channel	{ok, channel:{id, name, is_im}}	from the channel table
chat.postMessage	channel, text, blocks?, thread_ts?	{ok, ts, channel}	record it (test-inspectable); allocate a monotonic ts
chat.update	channel, ts, text, blocks?	{ok, ts, channel}	record it

Anything else the adapter happens to call → {ok:true} no-op (log it so gaps surface).

2. Socket Mode (WebSocket) — /socket

Mimic Slack's envelope protocol the AsyncSocketModeHandler expects:

• On connect, send {"type":"hello"}.
• Inbound events (a user posts): send an envelope {"envelope_id": <uuid>, "type":"events_api", "payload":{"token":"…","type":"event_callback", "event":{"type":"message","channel":<id>,"channel_type":"channel"|"im","user":<id>,"text":<str>, "ts":<ts>,"thread_ts"?:<ts>}}}. Client replies {"envelope_id":…} (ack) — the fake may ignore acks or record them.
• Interactions (button click): send {"envelope_id":<uuid>,"type":"interactive","payload":{"type":"block_actions","user":{"id":<id>, "username":<name>},"channel":{"id":<id>},"message":{"ts":<ts>},"actions":[{"action_id":<str>, "value":<str>}]}}. Client acks.
• Match the exact envelope shape slack_bolt decodes (verify against the installed slack_bolt/ slack_sdk version in the aisuite venv — this is the fiddly part; write a focused test that the real handler dispatches a fake-sent envelope).

3. Control / admin API (the test-facing surface) — HTTP under /control/*

This is how tests + the standalone runner drive scenarios:

Endpoint	Purpose
POST /control/users {id, name, real_name}	register a user (so users.info resolves a name)
POST /control/channels {id, name, is_im}	register a channel/DM
POST /control/inbound {channel, user, text, thread_ts?, channel_type}	push a message over the socket
POST /control/interaction {channel, user, username, message_ts, action_id, value}	push a button click
GET /control/outbound	the recorded chat.postMessage/chat.update calls (for assertions)
POST /control/reset	clear users/channels/recorded calls + drop sockets
GET /control/health	readiness

Programmatic API mirrors these (a FakeSlack Python object with add_user/add_channel/ inbound/interaction/outbound/reset) so pytest can drive without HTTP when embedded.

---

Packaging & modes

• Location: platform/coworker/testing/fake_slack/ (a package), with server.py (aiohttp app — aiohttp is already a dep) and __init__.py exporting FakeSlack.
• Embedded (pytest): a fixture fake_slack that starts the server on an ephemeral port, sets SLACK_API_URL, yields the control object, tears down. Used by the integration/e2e tests.
• Standalone (manual GUI testing): python -m coworker.testing.fake_slack --port 8910 runs it; print the SLACK_API_URL to export + a tiny REPL or curl examples for the control API, so a human can drive the live dev app against it (replaces real Slack for visual review).
• No new third-party dependencies (aiohttp only).

---

Acceptance (the fake's own tests)

1. SlackAdapter with SLACK_API_URL → fake connects: connect() returns True, auth.test resolved the bot id, Socket Mode hello received.
2. POST /control/inbound → the gateway's inbound handler fires with a MessageEvent whose user_name/chat_name are resolved from the registered tables (exercises users.info + conversations.info caching).
3. Agent/test calls send/send_interactive → recorded under GET /control/outbound with the right channel/text/blocks.
4. POST /control/interaction → the adapter's ocw_* action handler fires → reaches Gateway._on_interaction (resolves the inbox item).
5. POST /control/reset returns the fake to a clean slate between tests.
6. A focused test proves the real slack_bolt handler dispatches a fake-sent events_api and interactive envelope (guards against envelope-shape drift).

When done, wire test_ui_refresh_e2e.py (VERIFICATION "Cross-cutting acceptance") on top of it.