Transport Layer & Messaging
Relevant source files
The following files were used as context for generating this wiki page:
The Transport Layer in Cogmo serves as the decoupled interface between external communication platforms (Channels) and the internal agentic loop. It is responsible for identity resolution, session management, inbound message emission, and outbound response delivery. By utilizing an adapter pattern, the system abstracts platform-specific complexities (such as Telegram's HTML subset or Slack's Block Kit) into a canonical markdown format used by the LLM providers.
Sources: CLAUDE.md:65-68, design/transport/adapters.md:4-8, design/transport/adapters.md:155-160
Architecture Overview
The messaging architecture is built on event-driven decoupling via Inngest. Components communicate through events rather than direct imports, allowing new channels to be added without modifying the core orchestrator.
Core Components
- Adapters: Platform-specific handlers (Telegram, Direct, etc.) that manage I/O and normalize input.
- Transport Interface: A scoped API provided to adapters for interacting with the database and internal events without direct table access.
- Delivery Router: Orchestrates the fan-out of responses to active sessions across multiple channels.
Sources: CLAUDE.md:144-147, design/transport/adapters.md:10-15, design/transport/response-routing.md:10-15
Data Flow Diagram
The following diagram illustrates the lifecycle of a message from arrival at a platform to the delivery of an agent's response.
The Adapter Contract
Adapters interact with Cogmo through a strictly defined Transport interface. This interface acts as a trust boundary, preventing adapters from touching user_identities or other sensitive tables directly.
Transport Interface Methods
| Category | Method | Description |
|---|---|---|
| Sessions | resolveSession | Finds active session for a platform address. |
createConversation | Resolves identity and creates a new conversation/session. | |
closeSession | Sets status to 'closed', stopping delivery. | |
| Inbound | emit | Persists inbound_messages and triggers the orchestrator. |
| Admin | conversations.setProfile | Switches the active profile for the next turn. |
profiles.list | Lists available Org and User-owned profiles. | |
| Discovery | models.list | Returns user-selectable models from providers. |
Sources: design/transport/adapters.md:21-65, design/transport/adapters.md:84-110
Identity and Identity Modes
Identity resolution is handled internally by the Transport layer based on the channel's mode:
- Fixed: All messages mapped to a single hardcoded user.
- Mapped: Requires pre-existing mapping between platform handles and Cogmo users.
- Create: Automatically creates a new Cogmo user on first contact (reserved for future use).
Sources: design/transport/adapters.md:81-83, src/setup/wizard.ts:380-385
Response Routing & Delivery
The DeliveryRouter handles the "fan-out" of agent responses. Since a single conversation can be active across multiple sessions (e.g., Telegram and a Web UI), the router ensures delivery to all relevant endpoints.
Delivery Logic
- Resolution: The router loads the message and identifies the target conversation.
- Filtering: It identifies all sessions for that conversation with
receiveset to"all"or"routed". - Rendering: For each session, it calls the specific adapter's
renderOutput(markdown)function. - Transmission: Calls
adapter.deliver()for platform-specific sending.
Output Rendering
Cogmo follows the industry standard of having LLMs output canonical markdown, which adapters then transform for their specific platform.
Platform-Specific Post-Processing
- Telegram: Uses
markedto convert GFM to HTML. A custom post-processor handles Telegram-specific fixes like<blockquote>tags, emoji adjacency, and table wrapping in<pre>. - Direct/Console: Renders raw markdown text.
- Web UI: Leverages SSE (Server-Sent Events) for real-time streaming to the browser.
Sources: design/transport/adapters.md:167-185, design/transport/adapters.md:135-145
Steering Rules by Channel
Instructional guidance can be scoped by channel_type in the steering_rules table. This allows the agent to behave differently depending on the medium (e.g., "avoid tables on Telegram" vs "use rich formatting on Web").
| profile_id | channel_type | Applies to |
|---|---|---|
| null | null | Global (everywhere) |
| set | null | Specific profile, all channels |
| null | set | All profiles, specific channel |
Sources: design/transport/adapters.md:158-166
Summary
The Transport Layer & Messaging system provides a robust, adapter-based framework for Cogmo's external communications. By decoupling the agent's logic from platform-specific APIs and utilizing an event-driven delivery router, Cogmo supports multi-channel conversations while maintaining a single, evolvable instruction surface through markdown and steering rules.
Sources: design/transport/overview.md, design/transport/adapters.md:200-210