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.

Event normalization

Convert native platform messages, mentions, slash commands, or replies into a shared ConversationEvent.

Session routing

Compute sessionKey from channels, threads, and reply chains so conversations enter the right session.

Response capability

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

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

SlackSocket Mode, channel/thread sessions, Block Kit, assistant status, and Slack mrkdwn.

DiscordGateway events, guild/DM/thread channels, slash commands, Discord Markdown, and typing indicators.

TelegramLong polling, private/group chat, reply-based sessions, Telegram HTML mode, and photo/document downloads.

GitHubGitHub App polling, issue/PR conversations, watermark dedup, and comment-based streaming responses.

Boundary with the core runtime

Dependency direction

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.