turnstone/docs/channels.md

Channel Integrations

The turnstone-channel gateway connects external messaging platforms to turnstone workstreams via direct HTTP to the server (single-node) or the console routing proxy (multi-node). Each platform adapter translates platform-native events (messages, button clicks, slash commands) into turnstone API calls, and renders workstream output back into the platform's UI.

Discord ships as the first adapter. The adapter protocol is designed for future Slack and Teams integrations.

---

Architecture

Discord Gateway
      |
      v
turnstone-channel  (Discord adapter)
      |
      v
turnstone-server   (direct HTTP)
      or
turnstone-console  (routing proxy, multi-node)

Key components:

• ChannelAdapter protocol (turnstone/channels/_protocol.py) — generic interface for any messaging platform. Defines start(), stop(), send(), send_notification(), edit_message(), send_approval_request(), send_plan_review(), and create_thread().
• ChannelRouter (turnstone/channels/_routing.py) — maps channel/thread IDs to turnstone workstream IDs. Handles workstream creation via HTTP, stale route detection, and user identity resolution.
• channel_users table — maps (channel_type, channel_user_id) to a turnstone user_id. Messages from unlinked users are silently dropped.
• channel_routes table — persistent channel-to-workstream mappings. Survives bot restarts. Stale routes (evicted workstreams) are detected and refreshed on the next message.

---

Discord Setup

1. Create a Discord Application

1. Go to https://discord.com/developers/applications
2. Click New Application and give it a name
3. Navigate to the Bot tab and click Reset Token to generate a bot token. Copy it immediately — it is shown only once.
4. On the same Bot tab, scroll down to Privileged Gateway Intents and enable MESSAGE CONTENT INTENT
5. Navigate to OAuth2 > URL Generator
6. Under Scopes, check bot and applications.commands
7. Under Bot Permissions, check:
   • View Channels
   • Send Messages
   • Send Messages in Threads
   • Create Public Threads
   • Read Message History
   • Add Reactions
   • Embed Links
8. Copy the generated URL, open it in a browser, and add the bot to your Discord server

2. Configure Turnstone

Environment variables (recommended for Docker):

TURNSTONE_DISCORD_TOKEN=your-bot-token-here
TURNSTONE_DISCORD_GUILD=123456789  # optional, restrict to one guild

CLI flags (bare-metal):

turnstone-channel \
  --discord-token "your-bot-token" \
  --discord-guild 123456789 \
  --server-url http://localhost:8080

Docker Compose (production profile):

# In .env file:
TURNSTONE_DISCORD_TOKEN=your-bot-token
TURNSTONE_DISCORD_GUILD=123456789

Then start the stack:

docker compose --profile production up

The channel service starts automatically when TURNSTONE_DISCORD_TOKEN is set.

3. Link User Accounts

Discord users must link their account to a turnstone user before they can interact with the bot. Unlinked users' messages are silently ignored.

1. The user must have a turnstone API token — created via the admin panel or turnstone-admin create-token
2. In Discord, the user runs /link. A modal appears prompting for the API token (the token is never visible in Discord audit logs because it is submitted via modal, not as a slash command argument).
3. The token is validated against the database. If valid, a channel_users mapping is created.
4. The user can now @mention the bot or use slash commands.

An admin can also force-link or unlink users via the console admin panel (Admin > Channels tab).

---

Usage

Conversations

• @mention the bot in any allowed channel to start a new conversation. The bot creates a Discord thread from the message and a turnstone workstream behind it.
• All subsequent messages in the thread are routed to the same workstream.
• The bot streams responses via message edits, updated approximately every 1.5 seconds.
• If the workstream is evicted for capacity, the next message in the thread auto-creates a new workstream and atomically resumes the previous workstream via the resume_ws field on CreateWorkstreamMessage. The server resumes the workstream during creation (same HTTP request), and the server emits a WorkstreamResumedEvent back to the channel. The thread receives a "Resumed: {name} ({count} messages restored)" confirmation.

Slash Commands

Command	Description
/link	Link Discord account to turnstone (opens modal for API token)
/unlink	Unlink Discord account
/ask <message>	Create a new thread and workstream with an initial message
/status	Show workstream info for the current thread (ephemeral)
/close	Close the workstream, delete the route, and archive the thread

Tool Approvals

When manual approval is enabled (the default), tool calls are displayed as an orange embed with:

• Tool name and argument preview
• Approve (green), Reject (red), Always Approve (gray) buttons
• Only linked users can interact with approval buttons
• The approval decision is forwarded to the server via HTTP

Buttons use static custom_id values so they survive bot restarts. Correlation data (ws_id, correlation_id) is stored in the embed footer.

Auto-approval: When auto_approve is true (via --auto-approve), or when all tools in the request match the auto_approve_tools list in the adapter config, the bot auto-responds with approval and posts a "Tool auto-approved." notice to the thread instead of showing buttons. The auto_approve_tools list is set via the ChannelConfig.auto_approve_tools field (useful for allowing specific tools like bash or read_file while still requiring manual approval for others).

Plan Reviews

Plan review requests are displayed as a blue embed with:

• Approve Plan (green) button — approves the plan with empty feedback
• Request Changes (gray) button — opens a modal for feedback text (up to 2000 characters)
• Feedback is forwarded to the server via HTTP

---

Configuration Reference

CLI Flag	Env Var	Default	Description
--discord-token	TURNSTONE_DISCORD_TOKEN	—	Bot token (required to enable Discord)
--discord-guild	—	0 (all guilds)	Restrict to a single Discord guild
--discord-channels	—	empty (all)	Comma-separated channel IDs to allow
--server-url	TURNSTONE_SERVER_URL	http://localhost:8080	Server URL (single-node)
--console-url	TURNSTONE_CONSOLE_URL	—	Console URL (multi-node routing proxy)
--model	—	server default	Default model for new workstreams
--auto-approve	—	false	Auto-approve ALL tool calls (skips approval buttons entirely)
--http-host	—	127.0.0.1	HTTP server bind address for notify endpoint
--http-port	TURNSTONE_CHANNEL_PORT	8091	HTTP server port
--log-level	TURNSTONE_LOG_LEVEL	INFO	Log level
--log-format	TURNSTONE_LOG_FORMAT	auto	Log format (auto/json/text)

---

User Identity

• The channel_users table maps (channel_type, channel_user_id) to a turnstone user_id
• Self-service linking via the /link slash command (modal input, not visible in Discord audit logs)
• Admin can force-link or unlink via the console admin panel (Admin > Channels tab). Unlinking uses a styled confirmation modal.
• Unlinked users' messages are silently dropped
• A user can be linked across multiple platforms (e.g. Discord + Slack)

See Security: Database Schema for the channel_users table definition.

---

Workstream Lifecycle

1. Creation — @mention or /ask creates a Discord thread and a turnstone workstream. The ChannelRouter persists the mapping in the channel_routes table.
2. Active — messages are routed bidirectionally. The bot streams responses via message edits (updated every ~1.5 seconds).
3. Eviction — the server evicts an idle workstream for capacity. The route is preserved and the thread stays open.
4. Reactivation — the next message in the thread detects the stale route and creates a new workstream with the old ws_id as resume_ws on the creation request. The server resumes the workstream during creation (no separate command or reverse lookup needed). The channel receives a WorkstreamResumedEvent, and the thread displays "Resumed: {name} ({count} messages restored)". If the old workstream was pruned, a fresh one starts with no error.
5. Close — /close command closes the workstream via HTTP, deletes the route, unsubscribes from events, and archives the Discord thread.

---

Notifications

See also: Notification Flow diagram

The notify tool allows the LLM to proactively send notifications to users or channels on external platforms. This is useful for alerting people about task completion, errors, or important updates without waiting for them to check in.

Targeting

Two modes:

• Username — provide a turnstone username. The gateway resolves it via the channel_users table and sends to all linked channels (e.g. Discord + future Slack).
• Direct — provide channel_type + channel_id to target a specific platform channel or user DM.

Delivery Flow

Notifications use direct HTTP for low latency. The server calls the channel gateway directly over HTTP:

1. The LLM calls the notify tool with a message and target
2. _exec_notify() queries the services table for healthy channel gateways (heartbeat within the last 120 seconds)
3. The server mints a service JWT (aud: turnstone-channel) via ServiceTokenManager and POSTs to the first healthy gateway. The payload includes the originating ws_id for reply routing.
4. The gateway validates the JWT, resolves the target, and calls adapter.send_notification() which sends the message and tracks the outgoing message ID for reply routing
5. On failure, the server tries the next gateway. If all fail, it retries up to 2 more times (delays: 1s, 3s), re-querying the service registry on each attempt

Bidirectional Replies

Notifications support multi-turn DM conversations. When a user replies to a notification DM:

1. The bot looks up the originating ws_id from the tracked message ID (_notify_ws_map)
2. Verifies the replying user matches the original notification recipient (defence in depth — Discord DMs are already private)
3. Routes the reply to the workstream via router.send_message()
4. Registers the DM channel for response forwarding (_notify_reply_channels)
5. When the workstream responds (TurnCompleteEvent), the response is forwarded to the DM
6. The response message is itself tracked, so the user can reply again for another turn

This enables scenarios like an oncall engineer responding to a CI/CD failure notification from their phone before opening a laptop.

Limits:

• Tracking map capped at 100 entries (FIFO eviction of oldest)
• Entries cleaned up on workstream close/unsubscribe
• Replying to an expired notification sends "This notification is no longer active."
• DM reply content capped at 4096 characters

Service Registry

The channel gateway registers itself in the services database table on startup and sends a heartbeat every 30 seconds. On shutdown it deregisters. Services are considered stale after 120 seconds (4 missed heartbeats) and are excluded from list_services() queries.

The services table schema:

Column	Description
service_type	Service category (e.g. "channel")
service_id	Unique instance ID (channel-<hostname>-<random>)
url	HTTP base URL for the service
last_heartbeat	ISO 8601 timestamp of last heartbeat
created	ISO 8601 timestamp of initial registration

Security

• Authentication — the gateway's POST /v1/api/notify endpoint requires authentication. Configure TURNSTONE_JWT_SECRET so the server can mint JWTs with aud: turnstone-channel automatically. If the secret is not set, the gateway fails closed and rejects all requests with 401. Server JWTs (aud: turnstone-server) are rejected.
• Rate limit — maximum 5 notifications per turn. The counter only increments on successful delivery, so failures don't consume the budget.
• SSRF protection — only http:// and https:// service URLs are allowed. Other schemes are silently skipped.
• Mention sanitization — discord.utils.escape_mentions() is applied before sending, preventing @everyone / @here abuse.
• Error redaction — generic error messages are returned to the LLM. Internal details (service IDs, URLs, exception messages) are logged server-side only.

---

Adding New Adapters

The ChannelAdapter protocol defines the interface any platform adapter must implement:

class ChannelAdapter(Protocol):
    channel_type: str

    async def start(self) -> None: ...
    async def stop(self) -> None: ...
    async def send(self, channel_id: str, content: str) -> str: ...
    async def send_notification(self, channel_id: str, content: str, ws_id: str) -> str: ...
    async def edit_message(self, channel_id: str, message_id: str, content: str) -> None: ...
    async def send_approval_request(self, channel_id: str, ws_id: str, correlation_id: str, items: list[dict]) -> None: ...
    async def send_plan_review(self, channel_id: str, ws_id: str, correlation_id: str, content: str) -> None: ...
    async def create_thread(self, parent_channel_id: str, name: str, message_id: str = "") -> str: ...

send_notification() is like send() but associates the outgoing message with a ws_id so that user replies can be routed back to the originating workstream. Adapters must track the mapping from outgoing message ID to (ws_id, target_user_id) and handle DM replies.

To add a new platform:

1. Create turnstone/channels/<platform>/ package
2. Implement the ChannelAdapter protocol
3. Add a --<platform>-token flag and detection logic in turnstone/channels/cli.py
4. Add the optional dependency in pyproject.toml (e.g. turnstone[slack])

See turnstone/channels/discord/ as a reference implementation.