---
title: "Platform adapters"
description: "How Slack, Discord, Telegram, and GitHub adapters convert platform events into mikan's shared runtime format."
url: "https://geminixiang.github.io/platform-adapters/"
---

# Platform adapters

Their goal is to keep `src/runtime/*` and `src/agent.ts` from knowing each platform's SDK, thread rules, message update API, or file download behavior.

    Convert native platform messages, mentions, slash commands, or replies into a shared
    `ConversationEvent`.
    Compute `sessionKey` from channels, threads, and reply chains so conversations enter the right
    session.
    `ConversationResponder` wraps replies, updates, typing/working state, and file uploads.

## What adapters do

1. Receive platform events such as messages, mentions, slash commands, or replies.
2. Decide whether the message should trigger mikan: DM, mention, thread reply, or auto-reply policy.
3. Convert it to shared `ConversationEvent` and `ConversationMessage` values.
4. Compute `sessionKey` so different channels, threads, and replies map to the right session.
5. Download attachments and write them to `attachments/` in the workspace.
6. Create a `ConversationResponder` that wraps replies, updates, typing/working state, and file uploads.
7. Hand the event to `MessagingEventHandler`, which is `ConversationRuntime`.

Shared types are exported from `src/adapter.ts`; implementation types live in `src/types.ts` and `src/adapters/types.ts`.

## Shared flow

```mermaid
sequenceDiagram
  participant P as Platform SDK
  participant A as Platform adapter
  participant I as processMessageIntake()
  participant R as ConversationRuntime
  participant C as ConversationResponder

  P->>A: native message / slash command / reply
  A->>A: parse conversation, user, thread, attachments
  A->>I: ConversationEvent base + trigger/log/attachment hooks
  I->>I: auto-reply / trigger decision
  I->>A: download attachments when needed
  I->>R: handler.handleEvent(event, bot, context)
  R->>C: respond / replaceResponse / setWorking / uploadFile
  C->>P: platform formatting and send
```

## Shared utilities

| File                        | Purpose                                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `src/adapter.ts`            | Exports shared interfaces such as `MessagingBot`, `ConversationEvent`, `ConversationMessage`, and `ConversationResponder`. |
| `src/adapters/intake.ts`    | Shared message intake flow: trigger, log, attachment, queue, and handler call order.                                       |
| `src/adapters/shared.ts`    | Shared retry, queue, long message splitting, log, and stop target resolution.                                              |
| `src/adapters/streaming.ts` | Buffers streaming response updates before flushing to avoid overly frequent platform message updates.                      |

## Platform differences

<LinkCard
  title="Slack"
  description="Socket Mode, channel/thread sessions, Block Kit, assistant status, and Slack mrkdwn."
  href="/platform-adapters/slack/"
/>
<LinkCard
  title="Discord"
  description="Gateway events, guild/DM/thread channels, slash commands, Discord Markdown, and typing indicators."
  href="/platform-adapters/discord/"
/>
<LinkCard
  title="Telegram"
  description="Long polling, private/group chat, reply-based sessions, Telegram HTML mode, and photo/document downloads."
  href="/platform-adapters/telegram/"
/>
<LinkCard
  title="GitHub"
  description="GitHub App polling, issue/PR conversations, watermark dedup, and comment-based streaming responses."
  href="/platform-adapters/github/"
/>

## Boundary with the core runtime

  Platform adapters may know platform SDKs and message formats, but should not know how the agent
  executes tasks.

The core runtime depends only on these shared abstractions:

- `ConversationEvent`: one user or platform event.
- `MessagingBot`: platform messaging bot capabilities, such as post message and upload file.
- `ConversationContext`: `message`, `responder`, and `platform` metadata attached to an event.
- `ConversationResponder`: the channel used by the agent to reply.

When adding a platform, implement these abstractions first. Do not bring platform SDK details into `src/runtime/*` or `src/agent.ts`.