@zooid/transport-matrix 0.7.0

package/src/router.ts

@@ -0,0 +1,72 @@
+import { extractMentions } from './mentions.js'
+
+export interface AgentBinding {
+  name: string
+  userId: string
+  /** Optional human-readable display name. Falls back to the user_id localpart. */
+  displayName?: string
+  rooms: string[]
+  trigger: 'mention' | 'any'
+}
+
+export interface ThreadState {
+  /** Agent names that have posted in this thread, in order. */
+  participants: string[]
+  /** Agent names @mentioned in the thread root event (or subsequently). */
+  rootMentions: string[]
+}
+
+interface MaybeEvent {
+  type?: string
+  room_id?: string
+  sender?: string
+  content?: {
+    msgtype?: string
+    'm.relates_to'?: { rel_type?: string; event_id?: string }
+  }
+}
+
+export type RouteMatch = AgentBinding
+
+function inboundThreadRoot(event: MaybeEvent): string | undefined {
+  const r = event.content?.['m.relates_to']
+  return r?.rel_type === 'm.thread' && r.event_id ? r.event_id : undefined
+}
+
+export function route(
+  event: MaybeEvent,
+  agents: AgentBinding[],
+  threadStates?: Map<string, ThreadState>,
+): RouteMatch[] {
+  if (event.type !== 'm.room.message') return []
+  if (!event.content?.msgtype) return []
+  const mentions = new Set(extractMentions(event as never))
+  const matches: RouteMatch[] = []
+  const threadRoot = inboundThreadRoot(event)
+  const threadState = threadRoot ? threadStates?.get(threadRoot) : undefined
+
+  for (const a of agents) {
+    if (event.sender === a.userId) continue
+    if (!a.rooms.includes(event.room_id ?? '')) continue
+    if (a.trigger === 'any') {
+      matches.push(a)
+      continue
+    }
+    // trigger === 'mention'
+    if (mentions.has(a.userId)) {
+      matches.push(a)
+      continue
+    }
+    // Implicit trigger in a thread: most-recent-poster, or root-mention
+    // inheritance if no agent has posted yet.
+    if (threadState) {
+      const lastPoster = threadState.participants.at(-1)
+      if (lastPoster) {
+        if (lastPoster === a.name) matches.push(a)
+      } else if (threadState.rootMentions.includes(a.name)) {
+        matches.push(a)
+      }
+    }
+  }
+  return matches
+}

package/src/space-provisioner.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi } from 'vitest'
+import { MatrixClient } from './matrix-client.js'
+import { ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
+
+function clientWithFetches(...handlers: Array<(url: string, init?: RequestInit) => Response>) {
+  let i = 0
+  const fetch = vi.fn(async (url: string, init?: RequestInit) => {
+    const h = handlers[i++]
+    if (!h) throw new Error(`unexpected fetch #${i}: ${url}`)
+    return h(url, init)
+  })
+  const client = new MatrixClient({
+    homeserver: 'https://hs.zoon.local',
+    asToken: 'as-tok',
+    fetch: fetch as unknown as typeof globalThis.fetch,
+  })
+  return { client, fetch }
+}
+
+describe('ensureWorkforceSpace', () => {
+  it('returns the room ID when the alias already resolves', async () => {
+    const { client, fetch } = clientWithFetches((url) => {
+      expect(url).toContain('/_matrix/client/v3/directory/room/%23dev%3Ahs.zoon.local')
+      return new Response(JSON.stringify({ room_id: '!existing:hs.zoon.local' }), { status: 200 })
+    })
+    const id = await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+    })
+    expect(id).toBe('!existing:hs.zoon.local')
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('creates the space when the alias is unknown', async () => {
+    const { client, fetch } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (url, init) => {
+        expect(url).toContain('/_matrix/client/v3/createRoom')
+        const body = JSON.parse(init!.body as string)
+        expect(body).toMatchObject({
+          room_alias_name: 'dev',
+          name: 'Dev',
+          preset: 'public_chat',
+          creation_content: { type: 'm.space' },
+        })
+        return new Response(JSON.stringify({ room_id: '!new:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    const id = await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+    })
+    expect(id).toBe('!new:hs.zoon.local')
+    expect(fetch).toHaveBeenCalledTimes(2)
+  })
+
+  it('throws on resolveAlias errors other than 404', async () => {
+    const { client } = clientWithFetches(() => new Response('boom', { status: 500 }))
+    await expect(
+      ensureWorkforceSpace({
+        client,
+        asUserId: '@zooid:hs.zoon.local',
+        serverName: 'hs.zoon.local',
+        spaceLocalpart: 'dev',
+        preset: 'public_chat',
+      }),
+    ).rejects.toThrow(/500/)
+  })
+})
+
+describe('serverNameFromMxid', () => {
+  it('returns the part after the first colon', () => {
+    expect(serverNameFromMxid('@zooid:zoon.local')).toBe('zoon.local')
+  })
+
+  it('handles federated server names with ports', () => {
+    expect(serverNameFromMxid('@zooid:hs.example.com:8448')).toBe('hs.example.com:8448')
+  })
+
+  it('throws on an mxid without a server', () => {
+    expect(() => serverNameFromMxid('@zooid')).toThrow(/server/)
+  })
+})

package/src/space-provisioner.ts

@@ -0,0 +1,34 @@
+import { MatrixClient } from './matrix-client.js'
+
+export interface EnsureSpaceOpts {
+  client: MatrixClient
+  asUserId: string
+  serverName: string
+  spaceLocalpart: string
+  preset: 'public_chat' | 'private_chat'
+}
+
+export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<string> {
+  const alias = `#${opts.spaceLocalpart}:${opts.serverName}`
+  const existing = await opts.client.resolveAlias(alias)
+  if (existing) return existing
+
+  const display = opts.spaceLocalpart.charAt(0).toUpperCase() + opts.spaceLocalpart.slice(1)
+  return opts.client.createRoomRaw({
+    asUserId: opts.asUserId,
+    body: {
+      room_alias_name: opts.spaceLocalpart,
+      name: display,
+      preset: opts.preset,
+      creation_content: { type: 'm.space' },
+    },
+  })
+}
+
+export function serverNameFromMxid(mxid: string): string {
+  const colon = mxid.indexOf(':')
+  if (colon < 0) {
+    throw new Error(`mxid lacks server: ${mxid}`)
+  }
+  return mxid.slice(colon + 1)
+}