dirigent/crates/dirigent_matrix/CLAUDE.md

Package: dirigent_matrix

Matrix integration for Dirigent session sharing.

Quick Facts

• Type: Library
• Main Entry: src/lib.rs
• Dependencies: matrix-sdk, dirigent_protocol, tokio, serde, thiserror, async-trait
• Status: Phase 1 -- Bot-mode session sharing

Purpose

Provides bidirectional bridging between Dirigent sessions and Matrix rooms. A session can be "shared" to a Matrix room, allowing Matrix users to send messages to the agent and see responses in real-time.

Architecture

MatrixService (service.rs)

Central singleton owning the matrix-sdk Client. Handles:

• Bot authentication (login with username/password, session restore via SQLite store)
• Background sync loop for receiving Matrix events
• Share registry (tracks active session shares by connector_id + session_id)
• Room message dispatch to appropriate shares

MatrixSessionShare (share.rs)

Bidirectional bridge for one (connector_id, session_id) to one Matrix room:

• Dirigent to Matrix: Subscribes to connector events, forwards completed assistant messages as m.notice
• Matrix to Dirigent: Receives room messages via MatrixService dispatch, sends ConnectorCommandProxy through mpsc channel
• Implements the SessionShare trait from dirigent_protocol

MatrixConfig (config.rs)

Configuration parsed from [matrix] section in dirigent.toml:

• Homeserver URL, username, password source (env var or inline)
• Device ID for session persistence across restarts
• Display name, default invite list, store path

Room Management (room.rs)

• Private, non-federated room creation for session shares
• Room naming conventions ("Dirigent: <title>")

Configuration

Identity and credentials live in an Account; sharing behavior in [matrix]:

[accounts.matrix-bot]
type = "matrix"
homeserver = "https://matrix.example.com"
username = "dirigent_bot"
device_id = "DIRIGENT_01"
display_name = "Dirigent Bot"

[accounts.matrix-bot.credentials.password]
source = "env"
key = "DIRIGENT_MATRIX_PASSWORD"

[matrix]
account = "matrix-bot"
default_invite = ["@user:example.com"]
store_path = "matrix/bot/store"

Key Types

• MatrixService -- Singleton service, owns Client and share registry
• MatrixSessionShare -- Bidirectional session-to-room bridge
• MatrixBehaviorConfig -- Sharing behavior (account ref, invites, store path)
• ConnectorCommandProxy -- Message proxy decoupling from dirigent_core types
• CreateRoomOptions -- Room creation parameters

Integration with CoreRuntime

The MatrixService is wired into CoreRuntime as an optional component (like archivist):

• CoreRuntime::start_matrix_service() -- Resolves Account from config, creates and starts service
• CoreRuntime::create_matrix_share() -- Creates room, starts bridge, spawns command proxy task
• CoreRuntime::matrix_service() -- Accessor for the running service

Event Flow

Connector emits Event::MessageCompleted (role=assistant)
  -> MatrixSessionShare event forwarder task
    -> Sends m.notice to Matrix room

Matrix user sends message in room
  -> MatrixService sync loop receives SyncRoomMessageEvent
    -> Looks up share by room_id
      -> share.inject_message(text) -> ConnectorCommandProxy
        -> Proxy task translates to ConnectorCommand::SendMessage
          -> Connector processes message

Related Packages

• dirigent_protocol: SessionShare trait, Event types consumed by share forwarder
• dirigent_core: CoreRuntime integration, ConnectorCommand, ConnectorHandle
• dirigent_config: Path resolution (DIRIGENT_DATA_DIR for SQLite store)