@zooid/transport-matrix 0.7.0

package/src/bot-pool.ts

@@ -0,0 +1,112 @@
+import type { MatrixClient } from './matrix-client.js'
+import type { AgentBinding } from './router.js'
+import { serverNameFromMxid } from './space-provisioner.js'
+
+export interface BootstrapOpts {
+  /** Invited to any newly-created room; absent = no invite. */
+  adminUserId?: string
+  /** Workforce space room ID. When set, every resolved agent room is attached as m.space.child. */
+  spaceRoomId?: string
+  /** AS bot user ID. Required when spaceRoomId is set; sender of the m.space.child write. */
+  asUserId?: string
+}
+
+export class BotPool {
+  constructor(
+    private readonly client: Pick<
+      MatrixClient,
+      'registerBot' | 'joinRoom' | 'resolveAlias' | 'createRoom' | 'sendStateEvent' | 'setDisplayName'
+    >,
+    private readonly agents: AgentBinding[],
+  ) {}
+
+  async bootstrap(opts: BootstrapOpts = {}): Promise<void> {
+    const aliasToId = new Map<string, string>()
+    const attachedToSpace = new Set<string>()
+    for (const a of this.agents) {
+      const lp = localpart(a.userId)
+      try {
+        await this.client.registerBot(lp)
+      } catch (err) {
+        console.warn(`[matrix] register failed for ${a.userId}: ${(err as Error).message}`)
+      }
+      try {
+        await this.client.setDisplayName(a.userId, a.displayName ?? lp)
+      } catch (err) {
+        console.warn(`[matrix] setDisplayName(${a.userId}) failed: ${(err as Error).message}`)
+      }
+      for (let i = 0; i < a.rooms.length; i++) {
+        const room = a.rooms[i]
+        try {
+          let resolved = room
+          if (room.startsWith('#')) {
+            const cached = aliasToId.get(room)
+            if (cached) {
+              resolved = cached
+            } else {
+              const existing = await this.client.resolveAlias(room)
+              if (existing) {
+                resolved = existing
+              } else {
+                const colon = room.indexOf(':')
+                const aliasLocalpart = colon > 1 ? room.slice(1, colon) : room.slice(1)
+                const sender = opts.adminUserId ?? a.userId
+                resolved = await this.client.createRoom({
+                  roomAliasName: aliasLocalpart,
+                  invite: opts.adminUserId ? [opts.adminUserId] : [],
+                  senderUserId: sender,
+                  name: aliasLocalpart,
+                })
+              }
+              aliasToId.set(room, resolved)
+            }
+          }
+          // Store the canonical room_id on the binding so the router (which
+          // matches on event.room_id) sees a hit when Tuwunel pushes events.
+          a.rooms[i] = resolved
+          await this.client.joinRoom(resolved, a.userId)
+
+          if (
+            opts.spaceRoomId &&
+            opts.asUserId &&
+            !attachedToSpace.has(resolved)
+          ) {
+            attachedToSpace.add(resolved)
+            const via = serverNameFromMxid(a.userId)
+            try {
+              await this.client.sendStateEvent({
+                roomId: opts.spaceRoomId,
+                asUserId: opts.asUserId,
+                eventType: 'm.space.child',
+                stateKey: resolved,
+                content: { via: [via] },
+              })
+            } catch (err) {
+              console.warn(
+                `[matrix] m.space.child(${resolved}) failed: ${(err as Error).message}`,
+              )
+            }
+          }
+        } catch (err) {
+          console.warn(
+            `[matrix] join failed (${a.userId} → ${room}): ${(err as Error).message}`,
+          )
+        }
+      }
+    }
+  }
+
+  findByUserId(userId: string): AgentBinding | undefined {
+    return this.agents.find((a) => a.userId === userId)
+  }
+
+  findByName(name: string): AgentBinding | undefined {
+    return this.agents.find((a) => a.name === name)
+  }
+}
+
+function localpart(userId: string): string {
+  const m = /^@([^:]+):/.exec(userId)
+  if (!m) throw new Error(`bad user id: ${userId}`)
+  return m[1]
+}

package/src/context-provider.test.ts

@@ -0,0 +1,317 @@
+import { describe, it, expect, vi } from 'vitest'
+import { MatrixContextProvider } from './context-provider.js'
+import type { MatrixClient } from './matrix-client.js'
+
+function fakeClient(overrides: Partial<MatrixClient> = {}): MatrixClient {
+  return {
+    fetchRoomMessages: vi.fn(),
+    getJoinedMembers: vi.fn(),
+    fetchRoomName: vi.fn(),
+    fetchEvent: vi.fn(),
+    fetchThreadRelations: vi.fn(),
+    ...overrides,
+  } as unknown as MatrixClient
+}
+
+describe('MatrixContextProvider', () => {
+  it('maps Matrix m.room.message events into Message[] oldest-first', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$e2',
+            sender: '@bob:hs',
+            origin_server_ts: 2000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.text', body: 'second' },
+          },
+          {
+            event_id: '$e1',
+            sender: '@alice:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.text', body: 'first' },
+          },
+        ],
+        end: 'matrix-pagination-token',
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+
+    const page = await provider.getRoomHistory('!room:hs', { limit: 50 })
+
+    expect(page.messages.map((m) => m.id)).toEqual(['$e1', '$e2'])
+    expect(page.messages[0].sender).toBe('@alice:hs')
+    expect(page.messages[0].is_agent).toBe(false)
+    expect(page.next_before).toBe('matrix-pagination-token')
+    expect(page.has_more).toBe(true)
+  })
+
+  it('flags messages from registered agent bots as is_agent + agent_name', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$e1',
+            sender: '@architect:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.text', body: 'thinking...' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+    const page = await provider.getRoomHistory('!room:hs', {})
+    expect(page.messages[0]).toMatchObject({
+      sender: '@architect:hs',
+      is_agent: true,
+      agent_name: 'architect',
+    })
+    expect(page.has_more).toBe(false)
+  })
+
+  it('surfaces thread_id on messages that belong to a thread', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$reply',
+            sender: '@alice:hs',
+            origin_server_ts: 2000,
+            type: 'm.room.message',
+            content: {
+              msgtype: 'm.text',
+              body: 'in-thread reply',
+              'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+            },
+          },
+          {
+            event_id: '$top',
+            sender: '@bob:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.text', body: 'top-level' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const page = await provider.getRoomHistory('!room:hs', {})
+    const byId = new Map(page.messages.map((m) => [m.id, m]))
+    expect(byId.get('$reply')?.thread_id).toBe('$root')
+    expect(byId.get('$top')?.thread_id).toBeUndefined()
+  })
+
+  it('passes channelId and pagination opts through to the matrix client without thread filtering', async () => {
+    const fetchRoomMessages = vi.fn().mockResolvedValue({ chunk: [], end: undefined })
+    const provider = new MatrixContextProvider({
+      client: fakeClient({ fetchRoomMessages } as unknown as Partial<MatrixClient>),
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    await provider.getRoomHistory('!room:hs', { limit: 25, before: 'cursor-1' })
+    expect(fetchRoomMessages).toHaveBeenCalledWith({
+      roomId: '!room:hs',
+      asUserId: '@_zooid:hs',
+      limit: 25,
+      from: 'cursor-1',
+      filter: { types: ['m.room.message'] },
+    })
+  })
+
+  it('getChannelMembers returns joined members with is_agent flags', async () => {
+    const client = fakeClient({
+      getJoinedMembers: vi.fn().mockResolvedValue({
+        joined: {
+          '@alice:hs': { display_name: 'Alice' },
+          '@architect:hs': { display_name: 'architect' },
+        },
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+    const members = await provider.getChannelMembers('!room:hs')
+    expect(members).toEqual([
+      { id: '@alice:hs', name: 'Alice', is_agent: false },
+      { id: '@architect:hs', name: 'architect', is_agent: true, agent_name: 'architect' },
+    ])
+  })
+
+  it('getChannelInfo returns the room name and transport: matrix', async () => {
+    const client = fakeClient({
+      fetchRoomName: vi.fn().mockResolvedValue('engineering'),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const info = await provider.getChannelInfo('!room:hs')
+    expect(info).toEqual({ id: '!room:hs', name: 'engineering', transport: 'matrix' })
+  })
+
+  it('getRecentThreads returns top-level entries newest-first with bundled thread metadata, skipping thread replies', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$top2',
+            sender: '@bob:hs',
+            origin_server_ts: 3000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.text', body: 'standalone' },
+          },
+          {
+            event_id: '$reply1',
+            sender: '@alice:hs',
+            origin_server_ts: 2500,
+            type: 'm.room.message',
+            content: {
+              msgtype: 'm.text',
+              body: 'in-thread',
+              'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+            },
+          },
+          {
+            event_id: '$root',
+            sender: '@alice:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.text', body: 'thread root' },
+            unsigned: {
+              'm.relations': {
+                'm.thread': { count: 3, latest_event: { origin_server_ts: 2500 } },
+              },
+            },
+          },
+        ],
+        end: 'next-page',
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const page = await provider.getRecentThreads('!room:hs', { limit: 50 })
+    expect(page.threads.map((t) => t.id)).toEqual(['$top2', '$root'])
+    expect(page.threads[0]).toMatchObject({
+      id: '$top2',
+      reply_count: 0,
+      last_activity_at: new Date(3000).toISOString(),
+    })
+    expect(page.threads[1]).toMatchObject({
+      id: '$root',
+      reply_count: 3,
+      last_activity_at: new Date(2500).toISOString(),
+    })
+    expect(page.has_more).toBe(true)
+    expect(page.next_before).toBe('next-page')
+  })
+
+  it('getThreadHistory prepends the root event then appends replies oldest-first', async () => {
+    const client = fakeClient({
+      fetchEvent: vi.fn().mockResolvedValue({
+        event_id: '$root',
+        sender: '@alice:hs',
+        origin_server_ts: 1000,
+        type: 'm.room.message',
+        content: { msgtype: 'm.text', body: 'root msg' },
+      }),
+      fetchThreadRelations: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$r1',
+            sender: '@bob:hs',
+            origin_server_ts: 1500,
+            type: 'm.room.message',
+            content: {
+              msgtype: 'm.text',
+              body: 'first reply',
+              'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+            },
+          },
+          {
+            event_id: '$r2',
+            sender: '@alice:hs',
+            origin_server_ts: 2000,
+            type: 'm.room.message',
+            content: {
+              msgtype: 'm.text',
+              body: 'second reply',
+              'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+            },
+          },
+        ],
+        next_batch: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const page = await provider.getThreadHistory('!room:hs', '$root', {})
+    expect(page.messages.map((m) => m.id)).toEqual(['$root', '$r1', '$r2'])
+    expect(page.messages.every((m) => m.thread_id === '$root')).toBe(true)
+    expect(page.has_more).toBe(false)
+  })
+
+  it('getThreadHistory skips the root fetch when paginating (before is set)', async () => {
+    const fetchEvent = vi.fn()
+    const fetchThreadRelations = vi.fn().mockResolvedValue({
+      chunk: [],
+      next_batch: 'next-cursor',
+    })
+    const provider = new MatrixContextProvider({
+      client: fakeClient({ fetchEvent, fetchThreadRelations } as unknown as Partial<MatrixClient>),
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const page = await provider.getThreadHistory('!room:hs', '$root', {
+      limit: 50,
+      before: 'cursor-1',
+    })
+    expect(fetchEvent).not.toHaveBeenCalled()
+    expect(fetchThreadRelations).toHaveBeenCalledWith({
+      roomId: '!room:hs',
+      rootEventId: '$root',
+      asUserId: '@_zooid:hs',
+      limit: 50,
+      from: 'cursor-1',
+    })
+    expect(page.next_before).toBe('next-cursor')
+    expect(page.has_more).toBe(true)
+  })
+
+  it('falls back to the room id when no name state is set', async () => {
+    const client = fakeClient({
+      fetchRoomName: vi.fn().mockResolvedValue(null),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const info = await provider.getChannelInfo('!room:hs')
+    expect(info.name).toBe('!room:hs')
+  })
+})

package/src/context-provider.ts

@@ -0,0 +1,187 @@
+import type {
+  TransportContextProvider,
+  HistoryOptions,
+  HistoryPage,
+  Member,
+  ChannelInfo,
+  Message,
+  ThreadOverview,
+  ThreadOverviewPage,
+} from '@zooid/core'
+import type { MatrixClient } from './matrix-client.js'
+
+interface MatrixMessageEvent {
+  event_id: string
+  sender: string
+  origin_server_ts: number
+  type: string
+  content?: {
+    msgtype?: string
+    body?: string
+    'm.relates_to'?: { rel_type?: string; event_id?: string }
+  }
+  unsigned?: {
+    'm.relations'?: {
+      'm.thread'?: {
+        count?: number
+        latest_event?: { origin_server_ts?: number }
+      }
+    }
+  }
+}
+
+export interface MatrixContextProviderOpts {
+  client: MatrixClient
+  /** AS sender_localpart user (read access). */
+  asUserId: string
+  /** Map of Matrix user IDs → agent names, for is_agent / agent_name flags. */
+  agentBots: Map<string, string>
+}
+
+export class MatrixContextProvider implements TransportContextProvider {
+  constructor(private readonly opts: MatrixContextProviderOpts) {}
+
+  async getRoomHistory(channelId: string, hopts: HistoryOptions): Promise<HistoryPage> {
+    // Server-side filter: only `m.room.message` events. Without this we'd
+    // burn the page budget on reactions, `eco.zoon.*` custom events, typing
+    // notifications, etc., and routinely return empty pages with a stale
+    // `has_more` cursor.
+    const { chunk, end } = await this.opts.client.fetchRoomMessages({
+      roomId: channelId,
+      asUserId: this.opts.asUserId,
+      limit: hopts.limit,
+      from: hopts.before,
+      filter: { types: ['m.room.message'] },
+    })
+    const messages: Message[] = []
+    for (let i = chunk.length - 1; i >= 0; i--) {
+      const ev = chunk[i] as unknown as MatrixMessageEvent
+      const msg = this.toMessage(ev)
+      if (msg) messages.push(msg)
+    }
+    return {
+      messages,
+      next_before: end,
+      has_more: end !== undefined,
+    }
+  }
+
+  async getRecentThreads(
+    channelId: string,
+    hopts: HistoryOptions,
+  ): Promise<ThreadOverviewPage> {
+    // Server-side filter: `m.room.message` only, and exclude thread replies
+    // (`not_rel_types: ['m.thread']`) so the overview shows top-level entries
+    // and thread roots, not the reply noise underneath them.
+    const { chunk, end } = await this.opts.client.fetchRoomMessages({
+      roomId: channelId,
+      asUserId: this.opts.asUserId,
+      limit: hopts.limit,
+      from: hopts.before,
+      filter: { types: ['m.room.message'], not_rel_types: ['m.thread'] },
+    })
+    // /messages returns newest-first; keep that order for the overview.
+    const threads: ThreadOverview[] = []
+    for (const ev of chunk as unknown as MatrixMessageEvent[]) {
+      if (ev.type !== 'm.room.message') continue
+      if (ev.content?.msgtype !== 'm.text' || typeof ev.content.body !== 'string') continue
+      const relatesTo = ev.content['m.relates_to']
+      if (relatesTo?.rel_type === 'm.thread') continue // skip thread replies
+      const agent = this.opts.agentBots.get(ev.sender)
+      const bundled = ev.unsigned?.['m.relations']?.['m.thread']
+      const replyCount = bundled?.count ?? 0
+      const latestTs = bundled?.latest_event?.origin_server_ts ?? ev.origin_server_ts
+      threads.push({
+        id: ev.event_id,
+        sender: ev.sender,
+        text: ev.content.body,
+        timestamp: new Date(ev.origin_server_ts).toISOString(),
+        is_agent: agent !== undefined,
+        ...(agent !== undefined ? { agent_name: agent } : {}),
+        reply_count: replyCount,
+        last_activity_at: new Date(latestTs).toISOString(),
+      })
+    }
+    return {
+      threads,
+      next_before: end,
+      has_more: end !== undefined,
+    }
+  }
+
+  async getThreadHistory(
+    channelId: string,
+    threadId: string,
+    hopts: HistoryOptions,
+  ): Promise<HistoryPage> {
+    // Root event first (only on the first page when no pagination cursor).
+    const messages: Message[] = []
+    if (!hopts.before) {
+      const root = (await this.opts.client.fetchEvent(
+        channelId,
+        threadId,
+        this.opts.asUserId,
+      )) as unknown as MatrixMessageEvent | null
+      if (root) {
+        const rootMsg = this.toMessage(root)
+        if (rootMsg) messages.push({ ...rootMsg, thread_id: threadId })
+      }
+    }
+    const { chunk, next_batch } = await this.opts.client.fetchThreadRelations({
+      roomId: channelId,
+      rootEventId: threadId,
+      asUserId: this.opts.asUserId,
+      limit: hopts.limit,
+      from: hopts.before,
+    })
+    for (const ev of chunk as unknown as MatrixMessageEvent[]) {
+      const reply = this.toMessage(ev)
+      if (reply) messages.push({ ...reply, thread_id: threadId })
+    }
+    return {
+      messages,
+      next_before: next_batch,
+      has_more: next_batch !== undefined,
+    }
+  }
+
+  private toMessage(ev: MatrixMessageEvent): Message | null {
+    if (ev.type !== 'm.room.message') return null
+    if (ev.content?.msgtype !== 'm.text' || typeof ev.content.body !== 'string') return null
+    const agent = this.opts.agentBots.get(ev.sender)
+    const relatesTo = ev.content['m.relates_to']
+    const threadId =
+      relatesTo?.rel_type === 'm.thread' && relatesTo.event_id ? relatesTo.event_id : undefined
+    return {
+      id: ev.event_id,
+      sender: ev.sender,
+      text: ev.content.body,
+      timestamp: new Date(ev.origin_server_ts).toISOString(),
+      is_agent: agent !== undefined,
+      ...(agent !== undefined ? { agent_name: agent } : {}),
+      ...(threadId !== undefined ? { thread_id: threadId } : {}),
+    }
+  }
+
+  async getChannelMembers(channelId: string): Promise<Member[]> {
+    const { joined } = await this.opts.client.getJoinedMembers(channelId, this.opts.asUserId)
+    return Object.entries(joined).map(([id, info]) => {
+      const agent = this.opts.agentBots.get(id)
+      return {
+        id,
+        name: info.display_name ?? id,
+        is_agent: agent !== undefined,
+        ...(agent !== undefined ? { agent_name: agent } : {}),
+      }
+    })
+  }
+
+  async getChannelInfo(channelId: string): Promise<ChannelInfo> {
+    const name = await this.opts.client.fetchRoomName(channelId, this.opts.asUserId)
+    return {
+      id: channelId,
+      name: name ?? channelId,
+      transport: 'matrix',
+    }
+  }
+}