# Matrix Channel Adapter Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add a Matrix channel adapter using raw fetch against the Matrix Client-Server API v3, with zero external dependencies (no matrix-js-sdk).

**Architecture:** Polling-based adapter using `/_matrix/client/v3/sync` with incremental `since` tokens. Auth via pre-provisioned access token in config. Room allowlist + mention gating for multi-room safety. DM detection via `m.direct` account data. Outbound via `/_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}`.

**Tech Stack:** Node.js fetch (built-in), Vitest for tests, Zod for config schema validation.

---

## Context

### Existing Patterns

All Flynn channel adapters follow a consistent pattern:

1. **Config interface** — e.g. `TelegramAdapterConfig`, `DiscordAdapterConfig`
2. **Adapter class** implementing `ChannelAdapter` from `src/channels/types.ts`
3. **Barrel export** from `src/channels/<name>/index.ts`
4. **Re-export** in `src/channels/index.ts`
5. **Zod schema** in `src/config/schema.ts` (optional field on root config)
6. **Registration** in `src/daemon/channels.ts` (conditional on config presence)
7. **Tests** mocking the platform SDK; here we mock `global.fetch`

### Key ChannelAdapter interface

```typescript
interface ChannelAdapter {
  readonly name: string;
  readonly status: ChannelStatus;
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  send(peerId: string, message: OutboundMessage): Promise<void>;
  onMessage(handler: (msg: InboundMessage) => void): void;
}
```

### senderId convention

- Telegram: `String(chatId)` (numeric chat ID)
- Discord: `channelId` (snowflake string)
- Slack: `channelId:threadTs`
- WhatsApp: `number@c.us`

For Matrix: `roomId` (e.g. `!abc123:matrix.org`). This gives one session per room, matching the Discord pattern. The Matrix userId (e.g. `@flynn:matrix.org`) goes into `senderName`.

### peerId convention

`peerId` passed to `send()` is the `roomId`. This is the same as `senderId` since replies go back to the same room.

---

## Config Shape

```yaml
matrix:
  homeserver_url: "https://matrix.example.org"
  access_token: "${MATRIX_ACCESS_TOKEN}"
  allowed_room_ids:
    - "!abc123:matrix.org"
  require_mention: true        # default: true
  sync_timeout_ms: 30000       # default: 30000 (long-poll timeout)
  display_name: "Flynn"        # optional: set bot display name on connect
```

Zod schema:

```typescript
const matrixSchema = z.object({
  homeserver_url: z.string().url('Homeserver URL is required'),
  access_token: z.string().min(1, 'Access token is required'),
  allowed_room_ids: z.array(z.string()).default([]),
  require_mention: z.boolean().default(true),
  sync_timeout_ms: z.number().min(1000).max(120000).default(30000),
  display_name: z.string().optional(),
}).optional();
```

---

## Matrix Client-Server API Endpoints Used

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/_matrix/client/v3/sync` | GET | Long-poll for events (with `?since=&timeout=&filter=`) |
| `/_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}` | PUT | Send a message |
| `/_matrix/client/v3/user/{userId}/account_data/m.direct` | GET | Detect DM rooms |
| `/_matrix/client/v3/account/whoami` | GET | Resolve own userId on connect |

### Sync filter (minimize bandwidth)

```json
{
  "room": {
    "timeline": { "limit": 50 },
    "state": { "lazy_load_members": true }
  },
  "presence": { "not_types": ["*"] },
  "account_data": { "types": ["m.direct"] }
}
```

---

## Design Decisions

### 1. No matrix-js-sdk dependency
- **Choice**: Raw fetch calls against `/_matrix/client/v3` endpoints
- **Rationale**: User explicitly requested minimal dependencies. The Matrix CS API is well-documented REST/JSON. We only need sync, send, whoami, and account_data — 4 endpoints total.
- **Alternatives**: matrix-js-sdk (heavy, ~2MB, pulls in many transitive deps), matrix-bot-sdk (lighter but still a dep).

### 2. Polling via /sync long-poll (not WebSocket or SSE)
- **Choice**: `/sync` with `timeout` param for long-polling, looped in an async function with `AbortController` for clean shutdown.
- **Rationale**: This is the standard Matrix sync mechanism. Simple, robust, no extra deps. The `timeout` param makes it behave like long-polling (server holds connection open until events arrive or timeout elapses).
- **Alternatives**: Sliding Sync (MSC3575, not universally supported), WebSocket transport (experimental extension).

### 3. senderId = roomId
- **Choice**: Use the Matrix room ID (`!...`) as `senderId` in `InboundMessage`, matching the Discord adapter pattern where `senderId = channelId`.
- **Rationale**: Flynn creates one session per `channel:senderId` pair. Using `roomId` means one session per room, which is the natural boundary. The human user's Matrix ID goes into `senderName`.

### 4. DM detection via m.direct account data
- **Choice**: On connect, fetch the bot's `m.direct` account data to build a `Set<string>` of known DM room IDs. DM rooms bypass `require_mention`.
- **Rationale**: Matrix DMs are just rooms, but the `m.direct` account data flags which rooms are direct messages. This is the standard approach and doesn't require room member counting heuristics.

### 5. Mention detection via body text
- **Choice**: Check for `@displayName` or bot's Matrix user ID in the message body text.
- **Rationale**: Matrix `m.room.message` events include both `body` (plain text) and optional `formatted_body` (HTML with `<a href="https://matrix.to/#/@user:server">` pill links). Checking the plain text `body` for the display name or MXID is simpler and sufficient. The HTML formatted_body could also be checked for matrix.to links, but body text matching covers all clients.

### 6. Transaction ID for idempotent sends
- **Choice**: Generate txnId as `m${Date.now()}.${counter++}` per adapter instance.
- **Rationale**: Matrix PUT send requires a txnId for idempotency. A timestamp + counter ensures uniqueness within a process lifetime.

### 7. Message size limit
- **Choice**: Use `splitMessage()` utility with a 65536-char limit (Matrix spec allows up to 65536 bytes for event content).
- **Rationale**: Matrix's limit is much higher than Telegram (4096) or Discord (2000), but chunking at 65536 chars prevents oversized events.

---

## Implementation Steps

### Task 1: Add Matrix Zod Schema to Config

**Files:**
- Modify: `src/config/schema.ts`

**Step 1: Add the matrixSchema definition**

Add after the `whatsappSchema` definition (around line 350):

```typescript
const matrixSchema = z.object({
  homeserver_url: z.string().url('Homeserver URL is required'),
  access_token: z.string().min(1, 'Access token is required'),
  allowed_room_ids: z.array(z.string()).default([]),
  require_mention: z.boolean().default(true),
  sync_timeout_ms: z.number().min(1000).max(120000).default(30000),
  display_name: z.string().optional(),
}).optional();
```

**Step 2: Add `matrix` to configSchema**

In `configSchema` (around line 510), add after `whatsapp`:

```typescript
matrix: matrixSchema,
```

**Step 3: Add exported type**

After the existing type exports (around line 559), add:

```typescript
export type MatrixConfig = z.infer<typeof matrixSchema>;
```

**Step 4: Run typecheck**

Run: `pnpm typecheck`
Expected: PASS

**Step 5: Commit**

```bash
git add src/config/schema.ts
git commit -m "feat(matrix): add Matrix channel config schema"
```

---

### Task 2: Create Matrix Adapter — Core Structure and Connect

**Files:**
- Create: `src/channels/matrix/adapter.ts`
- Create: `src/channels/matrix/adapter.test.ts`
- Create: `src/channels/matrix/index.ts`

**Step 1: Write the adapter.test.ts skeleton with connect/disconnect tests**

Create `src/channels/matrix/adapter.test.ts`:

```typescript
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { MatrixAdapter, type MatrixAdapterConfig } from './adapter.js';
import type { InboundMessage } from '../types.js';

// ── Mock global fetch ─────────────────────────────────────────────

const mockFetch = vi.fn();

beforeEach(() => {
  vi.stubGlobal('fetch', mockFetch);
});

afterEach(() => {
  vi.restoreAllMocks();
});

const baseConfig: MatrixAdapterConfig = {
  homeserverUrl: 'https://matrix.example.org',
  accessToken: 'syt_test_token',
  allowedRoomIds: ['!room1:example.org'],
  requireMention: true,
  syncTimeoutMs: 30000,
};

/** Helper: create a mock fetch Response. */
function mockResponse(body: unknown, status = 200): Response {
  return {
    ok: status >= 200 && status < 300,
    status,
    json: async () => body,
    text: async () => JSON.stringify(body),
  } as Response;
}

/** Helper: make fetch return specific responses in sequence. */
function mockFetchSequence(...responses: Response[]) {
  for (const response of responses) {
    mockFetch.mockResolvedValueOnce(response);
  }
}

describe('MatrixAdapter', () => {
  let adapter: MatrixAdapter;

  beforeEach(() => {
    vi.clearAllMocks();
    adapter = new MatrixAdapter(baseConfig);
  });

  afterEach(async () => {
    // Ensure sync loop is stopped
    if (adapter.status === 'connected' || adapter.status === 'connecting') {
      await adapter.disconnect();
    }
  });

  // ── Basic properties ────────────────────────────────────────────

  it('has name "matrix"', () => {
    expect(adapter.name).toBe('matrix');
  });

  it('starts as disconnected', () => {
    expect(adapter.status).toBe('disconnected');
  });

  // ── connect / disconnect ────────────────────────────────────────

  it('connect resolves userId via whoami and sets connected', async () => {
    // whoami
    mockFetch.mockResolvedValueOnce(mockResponse({ user_id: '@flynn:example.org' }));
    // m.direct account data
    mockFetch.mockResolvedValueOnce(mockResponse({}));
    // First sync (will be aborted on disconnect)
    mockFetch.mockResolvedValueOnce(
      new Promise(() => {}), // never resolves — simulates long-poll
    );

    await adapter.connect();

    expect(adapter.status).toBe('connected');
    // Verify whoami was called
    expect(mockFetch).toHaveBeenCalledWith(
      'https://matrix.example.org/_matrix/client/v3/account/whoami',
      expect.objectContaining({
        headers: expect.objectContaining({
          Authorization: 'Bearer syt_test_token',
        }),
      }),
    );
  });

  it('connect throws on whoami failure', async () => {
    mockFetch.mockResolvedValueOnce(mockResponse({ errcode: 'M_UNKNOWN_TOKEN' }, 401));

    await expect(adapter.connect()).rejects.toThrow();
  });

  it('disconnect sets status to disconnected', async () => {
    // whoami
    mockFetch.mockResolvedValueOnce(mockResponse({ user_id: '@flynn:example.org' }));
    // m.direct
    mockFetch.mockResolvedValueOnce(mockResponse({}));
    // sync long-poll (never resolves)
    mockFetch.mockResolvedValueOnce(new Promise(() => {}));

    await adapter.connect();
    expect(adapter.status).toBe('connected');

    await adapter.disconnect();
    expect(adapter.status).toBe('disconnected');
  });

  it('disconnect is safe when not connected', async () => {
    await adapter.disconnect();
    expect(adapter.status).toBe('disconnected');
  });
});
```

**Step 2: Run test to verify it fails (adapter doesn't exist yet)**

Run: `pnpm test:run src/channels/matrix/adapter.test.ts`
Expected: FAIL — cannot resolve `./adapter.js`

**Step 3: Write adapter.ts with connect/disconnect**

Create `src/channels/matrix/adapter.ts`:

```typescript
/**
 * Matrix channel adapter.
 *
 * Implements the ChannelAdapter interface using raw fetch against the
 * Matrix Client-Server API v3. No external Matrix SDK dependency.
 * Uses /sync long-polling for inbound messages and PUT /send for outbound.
 */

import type {
  InboundMessage,
  OutboundMessage,
  ChannelAdapter,
  ChannelStatus,
} from '../types.js';
import { splitMessage } from '../utils.js';
import type { PairingManager } from '../pairing.js';

/** Configuration for the Matrix channel adapter. */
export interface MatrixAdapterConfig {
  homeserverUrl: string;
  accessToken: string;
  /** Room IDs to respond in. Empty = all joined rooms. */
  allowedRoomIds?: string[];
  /** Require @mention to respond in rooms (default: true). DMs always respond. */
  requireMention?: boolean;
  /** Long-poll timeout for /sync in milliseconds (default: 30000). */
  syncTimeoutMs?: number;
  /** Optional display name to set on connect. */
  displayName?: string;
  /** Optional pairing manager for DM pairing codes. */
  pairingManager?: PairingManager;
}

/** Maximum message length before chunking (Matrix allows up to 65536 bytes). */
const MAX_MESSAGE_LENGTH = 65536;

/**
 * Matrix channel adapter backed by raw Client-Server API v3 fetch calls.
 *
 * Handles room allowlist filtering, optional mention requirement,
 * DM detection via m.direct, and message chunking.
 */
export class MatrixAdapter implements ChannelAdapter {
  readonly name = 'matrix';

  private _status: ChannelStatus = 'disconnected';
  private messageHandler?: (msg: InboundMessage) => void;
  private config: MatrixAdapterConfig;

  /** Resolved bot user ID (e.g. @flynn:example.org). */
  private userId: string | null = null;
  /** Resolved bot display name (for mention detection). */
  private botDisplayName: string | null = null;
  /** Set of room IDs that are direct messages. */
  private dmRoomIds: Set<string> = new Set();
  /** Incremental sync token. */
  private syncToken: string | null = null;
  /** AbortController for the sync loop. */
  private syncAbort: AbortController | null = null;
  /** Transaction ID counter for idempotent sends. */
  private txnCounter = 0;

  get status(): ChannelStatus {
    return this._status;
  }

  constructor(config: MatrixAdapterConfig) {
    this.config = config;
  }

  /** Register the inbound message handler. Called by the registry before connect(). */
  onMessage(handler: (msg: InboundMessage) => void): void {
    this.messageHandler = handler;
  }

  /**
   * Connect to the Matrix homeserver:
   * 1. Resolve bot userId via /account/whoami
   * 2. Fetch m.direct account data for DM detection
   * 3. Start the /sync long-poll loop
   */
  async connect(): Promise<void> {
    this._status = 'connecting';

    try {
      // Resolve our own user ID
      const whoami = await this.matrixGet<{ user_id: string }>(
        '/_matrix/client/v3/account/whoami',
      );
      this.userId = whoami.user_id;
      this.botDisplayName = this.config.displayName ?? this.userId.split(':')[0].slice(1);

      // Fetch m.direct account data for DM detection
      await this.loadDirectRooms();

      // Start sync loop (fire and forget — runs until disconnect)
      this.syncAbort = new AbortController();
      this.runSyncLoop(this.syncAbort.signal);

      this._status = 'connected';
      console.log(`Matrix adapter connected as ${this.userId}`);
    } catch (error) {
      this._status = 'error';
      throw error;
    }
  }

  /** Stop the sync loop and clean up. */
  async disconnect(): Promise<void> {
    if (this.syncAbort) {
      this.syncAbort.abort();
      this.syncAbort = null;
    }
    this.userId = null;
    this.syncToken = null;
    this.dmRoomIds.clear();
    this._status = 'disconnected';
  }

  /** Send an outbound message to a Matrix room. */
  async send(peerId: string, message: OutboundMessage): Promise<void> {
    if (this._status !== 'connected') {
      throw new Error('Matrix adapter not connected');
    }

    const text = message.text ?? '';
    if (!text.trim()) { return; }

    if (text.length <= MAX_MESSAGE_LENGTH) {
      await this.sendRoomMessage(peerId, text);
    } else {
      const chunks = splitMessage(text, MAX_MESSAGE_LENGTH);
      for (const chunk of chunks) {
        await this.sendRoomMessage(peerId, chunk);
      }
    }
  }

  // ── Private: Matrix API helpers ─────────────────────────────────

  /** Make an authenticated GET request to the homeserver. */
  private async matrixGet<T>(path: string, query?: Record<string, string>): Promise<T> {
    const url = new URL(path, this.config.homeserverUrl);
    if (query) {
      for (const [k, v] of Object.entries(query)) {
        url.searchParams.set(k, v);
      }
    }

    const response = await fetch(url.toString(), {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${this.config.accessToken}`,
      },
    });

    if (!response.ok) {
      const body = await response.text();
      throw new Error(`Matrix API error (${response.status}): ${body}`);
    }

    return response.json() as Promise<T>;
  }

  /** Make an authenticated PUT request to the homeserver. */
  private async matrixPut<T>(path: string, body: unknown): Promise<T> {
    const url = new URL(path, this.config.homeserverUrl);

    const response = await fetch(url.toString(), {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${this.config.accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      const text = await response.text();
      throw new Error(`Matrix API error (${response.status}): ${text}`);
    }

    return response.json() as Promise<T>;
  }

  /** Send a text message to a room with idempotent txnId. */
  private async sendRoomMessage(roomId: string, text: string): Promise<void> {
    const txnId = `m${Date.now()}.${this.txnCounter++}`;
    await this.matrixPut(
      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/m.room.message/${txnId}`,
      {
        msgtype: 'm.text',
        body: text,
      },
    );
  }

  /** Load the m.direct account data to populate dmRoomIds. */
  private async loadDirectRooms(): Promise<void> {
    try {
      const data = await this.matrixGet<Record<string, string[]>>(
        `/_matrix/client/v3/user/${encodeURIComponent(this.userId!)}/account_data/m.direct`,
      );
      this.dmRoomIds.clear();
      // m.direct maps userId → [roomId, ...]. Flatten all room IDs.
      for (const roomIds of Object.values(data)) {
        if (Array.isArray(roomIds)) {
          for (const roomId of roomIds) {
            this.dmRoomIds.add(roomId);
          }
        }
      }
    } catch {
      // m.direct may not exist if the bot has no DMs yet — that's fine.
      this.dmRoomIds.clear();
    }
  }

  /** Check if a room is a DM. */
  private isDM(roomId: string): boolean {
    return this.dmRoomIds.has(roomId);
  }

  // ── Private: Sync loop ──────────────────────────────────────────

  /** Run the /sync long-poll loop until aborted. */
  private async runSyncLoop(signal: AbortSignal): Promise<void> {
    // Build the sync filter to minimize bandwidth
    const filter = JSON.stringify({
      room: {
        timeline: { limit: 50 },
        state: { lazy_load_members: true },
      },
      presence: { not_types: ['*'] },
      account_data: { types: ['m.direct'] },
    });

    while (!signal.aborted) {
      try {
        const query: Record<string, string> = {
          timeout: String(this.config.syncTimeoutMs ?? 30000),
          filter,
        };
        if (this.syncToken) {
          query.since = this.syncToken;
        }

        const url = new URL('/_matrix/client/v3/sync', this.config.homeserverUrl);
        for (const [k, v] of Object.entries(query)) {
          url.searchParams.set(k, v);
        }

        const response = await fetch(url.toString(), {
          method: 'GET',
          headers: {
            Authorization: `Bearer ${this.config.accessToken}`,
          },
          signal,
        });

        if (!response.ok) {
          const body = await response.text();
          console.error(`Matrix sync error (${response.status}): ${body}`);
          // Back off on error
          await this.sleep(5000, signal);
          continue;
        }

        const syncResponse = await response.json() as MatrixSyncResponse;
        this.syncToken = syncResponse.next_batch;

        // Process sync response
        this.processSyncResponse(syncResponse);
      } catch (error) {
        if (signal.aborted) { return; }
        console.error('Matrix sync loop error:', error instanceof Error ? error.message : 'Unknown error');
        // Back off on error
        await this.sleep(5000, signal);
      }
    }
  }

  /** Process a /sync response — extract timeline events from joined rooms. */
  private processSyncResponse(sync: MatrixSyncResponse): void {
    if (!this.messageHandler) { return; }

    const joinedRooms = sync.rooms?.join;
    if (!joinedRooms) { return; }

    // Update m.direct from account_data if present
    const accountData = sync.account_data?.events;
    if (accountData) {
      for (const event of accountData) {
        if (event.type === 'm.direct' && event.content) {
          this.dmRoomIds.clear();
          for (const roomIds of Object.values(event.content as Record<string, string[]>)) {
            if (Array.isArray(roomIds)) {
              for (const roomId of roomIds) {
                this.dmRoomIds.add(roomId);
              }
            }
          }
        }
      }
    }

    for (const [roomId, roomData] of Object.entries(joinedRooms)) {
      const events = roomData.timeline?.events;
      if (!events) { continue; }

      for (const event of events) {
        this.handleTimelineEvent(roomId, event);
      }
    }
  }

  /** Handle a single timeline event from a joined room. */
  private handleTimelineEvent(roomId: string, event: MatrixEvent): void {
    if (!this.messageHandler) { return; }

    // Only process m.room.message events
    if (event.type !== 'm.room.message') { return; }

    // Ignore our own messages
    if (event.sender === this.userId) { return; }

    // Room allowlist check
    const allowedRoomIds = this.config.allowedRoomIds ?? [];
    if (allowedRoomIds.length > 0 && !allowedRoomIds.includes(roomId)) {
      // Pairing fallback
      const pm = this.config.pairingManager;
      if (pm?.enabled) {
        if (pm.isApproved('matrix', roomId)) {
          // Approved — fall through
        } else {
          const text = (event.content?.body ?? '').trim();
          if (text && pm.validateCode('matrix', roomId, text)) {
            this.sendRoomMessage(roomId, 'Pairing successful! You can now chat with Flynn.').catch(() => {});
          }
          return;
        }
      } else {
        return;
      }
    }

    const body = event.content?.body ?? '';
    const isDm = this.isDM(roomId);

    // Mention gating: require mention in non-DM rooms
    const requireMention = this.config.requireMention ?? true;
    if (!isDm && requireMention) {
      const isMentioned = this.isBotMentioned(body);
      if (!isMentioned) { return; }
    }

    // Strip bot mention from text
    let text = body;
    if (this.botDisplayName) {
      text = text.replace(new RegExp(`@?${this.escapeRegex(this.botDisplayName)}\\b`, 'gi'), '').trim();
    }
    if (this.userId) {
      text = text.replace(new RegExp(this.escapeRegex(this.userId), 'g'), '').trim();
    }

    // Detect reset command
    if (text === '!reset' || text === 'reset') {
      this.messageHandler({
        id: event.event_id,
        channel: 'matrix',
        senderId: roomId,
        senderName: this.extractDisplayName(event.sender),
        text: '!reset',
        timestamp: event.origin_server_ts,
        metadata: { isCommand: true, command: 'reset' },
      });
      return;
    }

    // Regular message
    this.messageHandler({
      id: event.event_id,
      channel: 'matrix',
      senderId: roomId,
      senderName: this.extractDisplayName(event.sender),
      text,
      timestamp: event.origin_server_ts,
    });
  }

  /** Check if the bot is mentioned in the message text. */
  private isBotMentioned(text: string): boolean {
    if (this.botDisplayName && text.toLowerCase().includes(this.botDisplayName.toLowerCase())) {
      return true;
    }
    if (this.userId && text.includes(this.userId)) {
      return true;
    }
    return false;
  }

  /** Extract a display name from a Matrix user ID. @user:server → user */
  private extractDisplayName(userId: string): string {
    const match = userId.match(/^@([^:]+)/);
    return match ? match[1] : userId;
  }

  /** Escape a string for use in a RegExp. */
  private escapeRegex(str: string): string {
    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  }

  /** Sleep with abort support. */
  private sleep(ms: number, signal: AbortSignal): Promise<void> {
    return new Promise((resolve) => {
      const timer = setTimeout(resolve, ms);
      signal.addEventListener('abort', () => {
        clearTimeout(timer);
        resolve();
      }, { once: true });
    });
  }
}

// ── Matrix API response types ──────────────────────────────────────

interface MatrixSyncResponse {
  next_batch: string;
  rooms?: {
    join?: Record<string, MatrixJoinedRoom>;
  };
  account_data?: {
    events?: Array<{ type: string; content?: unknown }>;
  };
}

interface MatrixJoinedRoom {
  timeline?: {
    events?: MatrixEvent[];
  };
}

interface MatrixEvent {
  type: string;
  event_id: string;
  sender: string;
  origin_server_ts: number;
  content?: {
    body?: string;
    msgtype?: string;
    [key: string]: unknown;
  };
}
```

**Step 4: Run test to verify connect/disconnect pass**

Run: `pnpm test:run src/channels/matrix/adapter.test.ts`
Expected: PASS (4 tests)

**Step 5: Create barrel export**

Create `src/channels/matrix/index.ts`:

```typescript
export { MatrixAdapter, type MatrixAdapterConfig } from './adapter.js';
```

**Step 6: Commit**

```bash
git add src/channels/matrix/
git commit -m "feat(matrix): add Matrix adapter core with connect/disconnect"
```

---

### Task 3: Add Send Tests and Verify Send Works

**Files:**
- Modify: `src/channels/matrix/adapter.test.ts`

**Step 1: Add send tests to the test file**

Append these tests inside the `describe('MatrixAdapter')` block:

```typescript
  // ── send ──────────────────────────────────────────────────────

  it('send throws when not connected', async () => {
    await expect(adapter.send('!room1:example.org', { text: 'hello' })).rejects.toThrow(
      'Matrix adapter not connected',
    );
  });

  it('send delivers a message via PUT with txnId', async () => {
    // Connect first
    mockFetch.mockResolvedValueOnce(mockResponse({ user_id: '@flynn:example.org' }));
    mockFetch.mockResolvedValueOnce(mockResponse({}));
    mockFetch.mockResolvedValueOnce(new Promise(() => {})); // sync hangs
    await adapter.connect();

    // Send message
    mockFetch.mockResolvedValueOnce(mockResponse({ event_id: '$sent1' }));
    await adapter.send('!room1:example.org', { text: 'Hello there' });

    // Find the PUT call (skip whoami, m.direct, sync)
    const putCall = mockFetch.mock.calls.find(
      (call) => call[1]?.method === 'PUT',
    );
    expect(putCall).toBeDefined();
    expect(putCall![0]).toContain('/_matrix/client/v3/rooms/');
    expect(putCall![0]).toContain('/send/m.room.message/');

    const body = JSON.parse(putCall![1].body);
    expect(body.msgtype).toBe('m.text');
    expect(body.body).toBe('Hello there');
  });

  it('send skips empty text', async () => {
    mockFetch.mockResolvedValueOnce(mockResponse({ user_id: '@flynn:example.org' }));
    mockFetch.mockResolvedValueOnce(mockResponse({}));
    mockFetch.mockResolvedValueOnce(new Promise(() => {}));
    await adapter.connect();

    await adapter.send('!room1:example.org', { text: '' });

    // No PUT call should have been made
    const putCall = mockFetch.mock.calls.find(
      (call) => call[1]?.method === 'PUT',
    );
    expect(putCall).toBeUndefined();
  });
```

**Step 2: Run tests**

Run: `pnpm test:run src/channels/matrix/adapter.test.ts`
Expected: PASS (7 tests)

**Step 3: Commit**

```bash
git add src/channels/matrix/adapter.test.ts
git commit -m "test(matrix): add send tests"
```

---

### Task 4: Add Inbound Message Handling Tests

**Files:**
- Modify: `src/channels/matrix/adapter.test.ts`

**Step 1: Add a helper to connect the adapter and simulate sync**

Add these helpers near the top of the test file (after `mockFetchSequence`):

```typescript
/** Helper: connect the adapter with standard mocks. Returns a function to simulate sync. */
async function connectAdapter(adapter: MatrixAdapter, directRooms: Record<string, string[]> = {}) {
  // whoami
  mockFetch.mockResolvedValueOnce(mockResponse({ user_id: '@flynn:example.org' }));
  // m.direct
  mockFetch.mockResolvedValueOnce(mockResponse(directRooms));
  // sync long-poll — we'll control this manually
  let syncResolve: ((value: Response) => void) | null = null;
  mockFetch.mockResolvedValueOnce(
    new Promise<Response>((resolve) => { syncResolve = resolve; }),
  );
  await adapter.connect();

  return {
    /** Simulate a sync response arriving. */
    async emitSync(syncData: unknown) {
      if (syncResolve) {
        syncResolve(mockResponse(syncData));
        syncResolve = null;
      }
      // Allow the sync loop to process
      await new Promise((r) => setTimeout(r, 10));
      // Set up next sync to hang
      mockFetch.mockResolvedValueOnce(new Promise(() => {}));
    },
  };
}

/** Helper: create a Matrix timeline event. */
function createMatrixEvent(overrides: Record<string, unknown> = {}) {
  return {
    type: 'm.room.message',
    event_id: '$evt1',
    sender: '@alice:example.org',
    origin_server_ts: 1700000000000,
    content: {
      msgtype: 'm.text',
      body: 'Hello Flynn',
    },
    ...overrides,
  };
}

/** Helper: wrap events into a sync response. */
function createSyncResponse(roomId: string, events: unknown[], extras: Record<string, unknown> = {}) {
  return {
    next_batch: 's_next',
    rooms: {
      join: {
        [roomId]: {
          timeline: { events },
        },
      },
    },
    ...extras,
  };
}
```

**Step 2: Add inbound message tests**

Append inside the `describe('MatrixAdapter')` block:

```typescript
  // ── Inbound message handling ────────────────────────────────────

  it('inbound message from allowed room with mention triggers handler', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: '@Flynn Hello there' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);
    const msg: InboundMessage = handler.mock.calls[0][0];
    expect(msg.channel).toBe('matrix');
    expect(msg.senderId).toBe('!room1:example.org');
    expect(msg.senderName).toBe('alice');
    expect(msg.text).toBe('Hello there');
    expect(msg.id).toBe('$evt1');
  });

  it('inbound message without mention is ignored when requireMention is true', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: 'Hello everyone' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).not.toHaveBeenCalled();
  });

  it('inbound message without mention is accepted when requireMention is false', async () => {
    const noMentionAdapter = new MatrixAdapter({
      ...baseConfig,
      requireMention: false,
    });
    const handler = vi.fn();
    noMentionAdapter.onMessage(handler);

    const { emitSync } = await connectAdapter(noMentionAdapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: 'Hello everyone' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);

    await noMentionAdapter.disconnect();
  });

  it('ignores own messages (sender === userId)', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      sender: '@flynn:example.org',
      content: { msgtype: 'm.text', body: 'My own message' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).not.toHaveBeenCalled();
  });

  it('ignores messages in disallowed rooms', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: '@Flynn hello' },
    });
    await emitSync(createSyncResponse('!notallowed:example.org', [event]));

    expect(handler).not.toHaveBeenCalled();
  });

  it('DM room bypasses mention requirement', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    // Mark !dm1 as a DM room via m.direct
    const directRooms = { '@alice:example.org': ['!dm1:example.org'] };
    const dmAdapter = new MatrixAdapter({
      ...baseConfig,
      allowedRoomIds: ['!dm1:example.org'],
    });
    dmAdapter.onMessage(handler);
    const { emitSync } = await connectAdapter(dmAdapter, directRooms);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: 'Hello without mention' },
    });
    await emitSync(createSyncResponse('!dm1:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);
    const msg: InboundMessage = handler.mock.calls[0][0];
    expect(msg.text).toBe('Hello without mention');

    await dmAdapter.disconnect();
  });

  it('!reset command delivers reset metadata', async () => {
    const noMentionAdapter = new MatrixAdapter({
      ...baseConfig,
      requireMention: false,
    });
    const handler = vi.fn();
    noMentionAdapter.onMessage(handler);

    const { emitSync } = await connectAdapter(noMentionAdapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: '!reset' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);
    const msg: InboundMessage = handler.mock.calls[0][0];
    expect(msg.text).toBe('!reset');
    expect(msg.metadata).toEqual({ isCommand: true, command: 'reset' });

    await noMentionAdapter.disconnect();
  });

  it('strips bot mention from message text', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: '@Flynn What is the weather?' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);
    const msg: InboundMessage = handler.mock.calls[0][0];
    expect(msg.text).toBe('What is the weather?');
  });

  it('ignores non-message events (e.g. m.room.member)', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      type: 'm.room.member',
      content: { membership: 'join' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).not.toHaveBeenCalled();
  });

  it('accepts all rooms when allowedRoomIds is empty', async () => {
    const openAdapter = new MatrixAdapter({
      ...baseConfig,
      allowedRoomIds: [],
      requireMention: false,
    });
    const handler = vi.fn();
    openAdapter.onMessage(handler);

    const { emitSync } = await connectAdapter(openAdapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: 'Hello from any room' },
    });
    await emitSync(createSyncResponse('!anyrandom:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);
    const msg: InboundMessage = handler.mock.calls[0][0];
    expect(msg.text).toBe('Hello from any room');

    await openAdapter.disconnect();
  });

  it('does nothing when no message handler is registered', async () => {
    // Don't call onMessage
    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: '@Flynn hello' },
    });

    // Should not throw
    await emitSync(createSyncResponse('!room1:example.org', [event]));
  });

  it('mention detection works with Matrix user ID', async () => {
    const handler = vi.fn();
    adapter.onMessage(handler);

    const { emitSync } = await connectAdapter(adapter);

    const event = createMatrixEvent({
      content: { msgtype: 'm.text', body: '@flynn:example.org can you help?' },
    });
    await emitSync(createSyncResponse('!room1:example.org', [event]));

    expect(handler).toHaveBeenCalledTimes(1);
    const msg: InboundMessage = handler.mock.calls[0][0];
    expect(msg.text).toBe('can you help?');
  });
```

**Step 2: Run tests**

Run: `pnpm test:run src/channels/matrix/adapter.test.ts`
Expected: PASS (all ~19 tests)

**Step 3: Commit**

```bash
git add src/channels/matrix/adapter.test.ts
git commit -m "test(matrix): add inbound message handling and DM detection tests"
```

---

### Task 5: Wire Matrix Adapter into the System

**Files:**
- Modify: `src/channels/index.ts`
- Modify: `src/daemon/channels.ts`

**Step 1: Add Matrix exports to src/channels/index.ts**

Add after the WhatsApp export line:

```typescript
export { MatrixAdapter, type MatrixAdapterConfig } from './matrix/index.js';
```

**Step 2: Register Matrix adapter in src/daemon/channels.ts**

Add import at top:

```typescript
import { ChannelRegistry, TelegramAdapter, WebChatAdapter, DiscordAdapter, SlackAdapter, WhatsAppAdapter, MatrixAdapter, PairingManager } from '../channels/index.js';
```

Add registration block after the WhatsApp block (around line 71):

```typescript
  // Register Matrix adapter (if configured)
  if (config.matrix) {
    const matrixAdapter = new MatrixAdapter({
      homeserverUrl: config.matrix.homeserver_url,
      accessToken: config.matrix.access_token,
      allowedRoomIds: config.matrix.allowed_room_ids.length > 0 ? config.matrix.allowed_room_ids : undefined,
      requireMention: config.matrix.require_mention,
      syncTimeoutMs: config.matrix.sync_timeout_ms,
      displayName: config.matrix.display_name,
      pairingManager,
    });
    channelRegistry.register(matrixAdapter);
  }
```

**Step 3: Run typecheck**

Run: `pnpm typecheck`
Expected: PASS

**Step 4: Run all channel tests to ensure no regressions**

Run: `pnpm test:run src/channels/`
Expected: All existing tests PASS

**Step 5: Commit**

```bash
git add src/channels/index.ts src/daemon/channels.ts
git commit -m "feat(matrix): wire Matrix adapter into channel registry and daemon"
```

---

### Task 6: Add Config Schema Test

**Files:**
- Modify: `src/config/schema.test.ts` (if exists, otherwise verify with existing tests)

**Step 1: Check for existing config schema tests**

Read `src/config/schema.test.ts` and add a Matrix config validation test.

```typescript
it('validates matrix config', () => {
  const config = configSchema.parse({
    models: { default: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' } },
    matrix: {
      homeserver_url: 'https://matrix.example.org',
      access_token: 'syt_test_token',
      allowed_room_ids: ['!room1:example.org'],
      require_mention: true,
    },
  });
  expect(config.matrix).toBeDefined();
  expect(config.matrix!.homeserver_url).toBe('https://matrix.example.org');
  expect(config.matrix!.require_mention).toBe(true);
  expect(config.matrix!.sync_timeout_ms).toBe(30000); // default
});

it('matrix config is optional', () => {
  const config = configSchema.parse({
    models: { default: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' } },
  });
  expect(config.matrix).toBeUndefined();
});

it('matrix config rejects invalid homeserver URL', () => {
  expect(() => configSchema.parse({
    models: { default: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' } },
    matrix: {
      homeserver_url: 'not-a-url',
      access_token: 'token',
    },
  })).toThrow();
});
```

**Step 2: Run config schema tests**

Run: `pnpm test:run src/config/schema.test.ts`
Expected: PASS

**Step 3: Commit**

```bash
git add src/config/schema.test.ts
git commit -m "test(matrix): add config schema validation tests"
```

---

### Task 7: Add Credential Redaction for Matrix Token

**Files:**
- Modify: `src/gateway/handlers/config.ts`

**Step 1: Add matrix access_token to redaction**

In the `redactConfig()` function, add redaction for the Matrix access token alongside the existing channel token redactions:

```typescript
// After the existing channel token redactions (e.g., discord.bot_token)
if (redacted.matrix) {
  redacted.matrix = { ...redacted.matrix, access_token: REDACTED };
}
```

**Step 2: Run tests**

Run: `pnpm test:run src/gateway/handlers/handlers.test.ts`
Expected: PASS

**Step 3: Commit**

```bash
git add src/gateway/handlers/config.ts
git commit -m "feat(matrix): add access_token to config redaction"
```

---

### Task 8: Final Verification

**Step 1: Run full typecheck**

Run: `pnpm typecheck`
Expected: PASS

**Step 2: Run all tests**

Run: `pnpm test:run`
Expected: All tests PASS

**Step 3: Commit any remaining changes**

```bash
git add -A
git commit -m "feat(matrix): complete Matrix channel adapter implementation"
```

---

## Testing Summary

| Test Category | Count | Description |
|---------------|-------|-------------|
| Basic properties | 2 | name = "matrix", starts disconnected |
| connect/disconnect | 4 | whoami resolution, error handling, clean disconnect, safe disconnect when not connected |
| send | 3 | throws when disconnected, PUT with txnId, skips empty text |
| Inbound messages | 12 | mention gating, DM bypass, own message filtering, room allowlist, reset command, mention stripping, MXID mention, non-message events, open rooms, no handler |
| Config schema | 3 | valid config, optional, invalid URL rejection |
| **Total** | **~24** | |

## Error Handling Strategy

| Error | Recovery |
|-------|----------|
| `/account/whoami` 401 | Throw on connect — adapter stays in error state |
| `/sync` HTTP error | Log, back off 5s, retry |
| `/sync` network error | Log, back off 5s, retry |
| `/send` failure | Throw — caller (registry) logs the error |
| `m.direct` 404 | Silently ignore — no DMs known yet |
| AbortError during sync | Clean exit from loop |

## Sync Loop Lifecycle

```
connect()
  ├── GET /account/whoami → resolve userId
  ├── GET /user/{userId}/account_data/m.direct → populate dmRoomIds
  └── runSyncLoop() (fire-and-forget async)
        ├── GET /sync?timeout=30000 (first call, no since token)
        │     └── next_batch → save as syncToken
        │     └── rooms.join → process timeline events
        │     └── account_data → update dmRoomIds
        ├── GET /sync?timeout=30000&since=... (subsequent calls)
        │     └── (repeat)
        └── (on error) → sleep 5s → retry

disconnect()
  └── AbortController.abort() → sync loop exits
```

## Risks and Mitigations

| Risk | Mitigation |
|------|------------|
| Initial sync floods events from history | First sync may replay old events. The adapter could skip the first sync's events (only use it to get `next_batch`). However, this is how other adapters work (Telegram's grammy does NOT replay), so we process all events from the first sync. If this is a problem, a `skip_initial_sync` config flag can be added later. |
| Sync loop leak on unhandled error | `try/catch` wraps the entire loop body with exponential backoff. AbortController ensures clean shutdown. |
| Bot invited to many rooms, only some allowed | Room allowlist (`allowed_room_ids`) prevents processing. If empty, all joined rooms are processed. |
| Matrix homeserver rate limiting | The sync loop naturally rate-limits (one request at a time with 30s timeout). Send calls are user-triggered and unlikely to hit limits. |
| Access token expiry | Matrix access tokens are typically long-lived. If expired, whoami will fail on connect. Short-lived tokens (refresh tokens) are a future enhancement. |

## Open Questions

1. **Skip initial sync?** — Should the adapter skip processing events from the very first `/sync` response (which may contain old history)? Current design processes them all. Can add a `skip_initial_sync: true` config flag if needed.

2. **Typing indicators?** — Matrix supports `m.typing` events. Should the adapter send a typing indicator while processing? Deferred for initial implementation (other adapters do this inconsistently — Telegram yes, Discord yes, Slack no).

3. **Image/media attachments?** — Matrix supports `m.image`, `m.file`, `m.audio` msgtypes. The initial implementation only handles `m.text`. Media support can be added in a follow-up (download via `/_matrix/media/v3/download/{serverName}/{mediaId}`).

4. **Formatted messages?** — Matrix supports `format: "org.matrix.custom.html"` with `formatted_body`. Should outbound messages include HTML? Deferred — plain text is sufficient for initial implementation.

---

## Files Summary

| Action | File |
|--------|------|
| Modify | `src/config/schema.ts` — add `matrixSchema` + type export |
| Create | `src/channels/matrix/adapter.ts` — full adapter implementation |
| Create | `src/channels/matrix/adapter.test.ts` — 24 tests |
| Create | `src/channels/matrix/index.ts` — barrel export |
| Modify | `src/channels/index.ts` — re-export Matrix adapter |
| Modify | `src/daemon/channels.ts` — register Matrix adapter |
| Modify | `src/gateway/handlers/config.ts` — redact access_token |
| Modify | `src/config/schema.test.ts` — config validation tests |