@zooid/transport-matrix 0.7.0

package/src/transport.ts

@@ -0,0 +1,521 @@
+import { Hono } from 'hono'
+import { timingSafeEqual } from 'node:crypto'
+import type { AcpRegistry, ApprovalCorrelator, RegisteredApproval } from '@zooid/core'
+import type { AgentEvent } from '@zooid/acp-client'
+import { MatrixClient } from './matrix-client.js'
+import { BotPool } from './bot-pool.js'
+import { route, type AgentBinding, type ThreadState } from './router.js'
+import { stripMention, extractMentions } from './mentions.js'
+import { toToolCallBody, toUpdateBody, toPlanBody } from './event-encoders.js'
+import { toMatrixHtml } from './markdown-to-matrix-html.js'
+
+export interface CreateMatrixTransportOptions {
+  agents: AcpRegistry
+  approvals: ApprovalCorrelator
+  client: MatrixClient
+  bindings: AgentBinding[]
+  hsToken: string
+  /** Admin Matrix user ID. When set, BotPool.bootstrap invites this user into rooms it creates. */
+  adminUserId?: string
+}
+
+interface SessionContext {
+  agent: AgentBinding
+  roomId: string
+  /** Always set — every session is thread-scoped via agent-promotion. */
+  threadRoot: string
+}
+
+interface MatrixEvent {
+  type?: string
+  event_id?: string
+  origin_server_ts?: number
+  room_id?: string
+  sender?: string
+  content?: Record<string, unknown> & {
+    msgtype?: string
+    body?: string
+    'm.relates_to'?: { rel_type?: string; event_id?: string }
+  }
+}
+
+const STARTUP_GRACE_MS = 5_000
+const SEEN_EVENT_CAP = 5_000
+
+function inboundThreadRoot(evt: MatrixEvent): string | undefined {
+  const r = evt.content?.['m.relates_to']
+  return r?.rel_type === 'm.thread' && r.event_id ? r.event_id : undefined
+}
+
+export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
+  const { agents, approvals, client, bindings, hsToken, adminUserId } = opts
+  const pool = new BotPool(client, bindings)
+  const sessions = new Map<string, SessionContext>()
+  const buffers = new Map<string, string>()
+  // Per-session promise tail so out-of-band events (tool_call, plan, etc.)
+  // serialize on the wire even though the ACP producer doesn't await us.
+  const sendQueue = new Map<string, Promise<void>>()
+  // Thread participation index: keyed by thread root event_id.
+  const threadStates = new Map<string, ThreadState>()
+  // Drop events older than this — Tuwunel may replay a backlog after the
+  // daemon was offline, and we don't want yesterday's "@docs hi" to fire now.
+  const cutoffTs = Date.now() - STARTUP_GRACE_MS
+  // Idempotency: appservice transactions are retried on 4xx/5xx/timeout, and
+  // the same event_id can arrive twice. Skip ones we've already taken.
+  const seenEventIds = new Set<string>()
+
+  agents.onEvent = async (name, event: AgentEvent) => {
+    const ctx = sessions.get(event.sessionId)
+    if (!ctx) {
+      console.warn(`[matrix:${name}] no session ctx for ${event.sessionId}`)
+      return
+    }
+
+    if (event.type === 'agent_message_chunk') {
+      const block = event.content as { type?: string; text?: string }
+      if (block.type === 'text' && typeof block.text === 'string') {
+        buffers.set(event.sessionId, (buffers.get(event.sessionId) ?? '') + block.text)
+      } else {
+        console.warn(`[matrix:${name}] dropped chunk block type=${block.type}`, block)
+      }
+      return
+    }
+
+    const eventType =
+      event.type === 'tool_call'
+        ? 'eco.zoon.tool_call'
+        : event.type === 'tool_call_update'
+          ? 'eco.zoon.tool_call_update'
+          : 'eco.zoon.plan'
+    const body =
+      event.type === 'tool_call'
+        ? toToolCallBody(event)
+        : event.type === 'tool_call_update'
+          ? toUpdateBody(event)
+          : toPlanBody(event)
+    body['m.relates_to'] = { rel_type: 'm.thread', event_id: ctx.threadRoot }
+    const tail = (sendQueue.get(event.sessionId) ?? Promise.resolve()).then(async () => {
+      try {
+        await client.sendCustomEvent({
+          roomId: ctx.roomId,
+          asUserId: ctx.agent.userId,
+          eventType,
+          content: body,
+        })
+      } catch (err) {
+        console.warn(`[matrix:${name}] sendCustomEvent(${eventType}) failed:`, err)
+      }
+    })
+    sendQueue.set(event.sessionId, tail)
+    await tail
+  }
+
+  agents.onApprovalRequest = async (name, req) => {
+    const handle = approvals.register(name, (req as { sessionId: string }).sessionId, req, {
+      timeoutMs: agents.getApprovalTimeoutMs(name),
+    })
+    return handle.decisionPromise
+  }
+
+  approvals.on('registered', (handle: RegisteredApproval) => {
+    const ctx = sessions.get(handle.sessionId)
+    if (!ctx) return
+    const content: Record<string, unknown> = {
+      approval_id: handle.approvalId,
+      session_id: handle.sessionId,
+      tool_call_id: handle.toolCallId,
+      options: handle.options,
+    }
+    content['m.relates_to'] = { rel_type: 'm.thread', event_id: ctx.threadRoot }
+    if (handle.toolKind !== undefined) content.tool_kind = handle.toolKind
+    if (handle.toolTitle !== undefined) content.tool_title = handle.toolTitle
+    if (handle.toolInput !== undefined) content.tool_input = handle.toolInput
+    void client.sendCustomEvent({
+      roomId: ctx.roomId,
+      asUserId: ctx.agent.userId,
+      eventType: 'eco.zoon.approval_request',
+      content,
+    })
+  })
+
+  const app = new Hono()
+
+  function authOk(authHeader: string | undefined): boolean {
+    const h = authHeader ?? ''
+    if (!h.startsWith('Bearer ')) return false
+    const got = h.slice(7)
+    if (got.length !== hsToken.length) return false
+    return timingSafeEqual(Buffer.from(got), Buffer.from(hsToken))
+  }
+
+  app.put('/_matrix/app/v1/transactions/:txnId', async (c) => {
+    if (!authOk(c.req.header('authorization'))) {
+      return c.json({ errcode: 'M_FORBIDDEN' }, 403)
+    }
+    const body = (await c.req.json().catch(() => ({}))) as { events?: MatrixEvent[] }
+    for (const evt of body.events ?? []) {
+      if (evt.event_id) {
+        if (seenEventIds.has(evt.event_id)) {
+          continue
+        }
+        seenEventIds.add(evt.event_id)
+        if (seenEventIds.size > SEEN_EVENT_CAP) {
+          const first = seenEventIds.values().next().value
+          if (first !== undefined) seenEventIds.delete(first)
+        }
+      }
+      if (
+        evt.origin_server_ts !== undefined &&
+        evt.origin_server_ts < cutoffTs &&
+        evt.type === 'm.room.message'
+      ) {
+        console.log(
+          `[matrix] dropping stale message event ${evt.event_id} ` +
+            `(ts=${evt.origin_server_ts}, daemon started at ${cutoffTs + STARTUP_GRACE_MS})`,
+        )
+        continue
+      }
+      if (evt.type === 'eco.zoon.session_reset') {
+        // Spec § /clear: room-scope reset is unsupported. Only thread-scoped
+        // resets carry a thread relation; drop bare room-level resets silently.
+        const relates = evt.content?.['m.relates_to'] as
+          | { rel_type?: string; event_id?: string }
+          | undefined
+        const threadRoot =
+          relates?.rel_type === 'm.thread' && relates.event_id ? relates.event_id : undefined
+        if (!threadRoot) {
+          console.log('[matrix] dropping eco.zoon.session_reset without thread relation')
+          continue
+        }
+        console.log(`[matrix] inbound eco.zoon.session_reset in ${evt.room_id} thread=${threadRoot}`)
+        for (const a of bindings) {
+          agents.endSession(a.name, threadRoot)
+        }
+        // NB: keep threadStates intact. Per ZOD039 § /clear, only the agent's
+        // session memory is wiped — thread-routing state (participants /
+        // root-mentions) must survive so the next bare reply still routes to
+        // the most-recently-posting agent under the same sessionKey.
+        continue
+      }
+      if (evt.type === 'eco.zoon.interrupt') {
+        const content = (evt.content ?? {}) as { session_id?: string; reason?: string }
+        // Thread-relation form (client-friendly): /interrupt in a thread sends
+        // an empty event with `m.relates_to: thread/<root>`. Cancel every
+        // session whose threadRoot matches.
+        const relates = evt.content?.['m.relates_to'] as
+          | { rel_type?: string; event_id?: string }
+          | undefined
+        const threadRoot =
+          relates?.rel_type === 'm.thread' && relates.event_id ? relates.event_id : undefined
+        if (threadRoot) {
+          const targets: Array<{ sessionId: string; agent: string }> = []
+          for (const [sessionId, ctx] of sessions) {
+            if (ctx.threadRoot === threadRoot) {
+              targets.push({ sessionId, agent: ctx.agent.name })
+            }
+          }
+          for (const t of targets) {
+            console.log(
+              `[matrix] interrupt session=${t.sessionId} agent=${t.agent} thread=${threadRoot}` +
+                (content.reason ? ` reason=${content.reason}` : ''),
+            )
+            await agents.cancelSession(t.agent, t.sessionId).catch((err) => {
+              console.error(`[matrix] cancelSession(${t.agent}, ${t.sessionId}) failed:`, err)
+            })
+          }
+          continue
+        }
+        // Legacy form: explicit session_id in content.
+        if (!content.session_id) {
+          console.warn(`[matrix] eco.zoon.interrupt missing session_id (event_id=${evt.event_id})`)
+          continue
+        }
+        const ctx = sessions.get(content.session_id)
+        if (!ctx) {
+          continue
+        }
+        console.log(
+          `[matrix] interrupt session=${content.session_id} agent=${ctx.agent.name}` +
+            (content.reason ? ` reason=${content.reason}` : ''),
+        )
+        await agents.cancelSession(ctx.agent.name, content.session_id).catch((err) => {
+          console.error(`[matrix] cancelSession(${ctx.agent.name}, ${content.session_id}) failed:`, err)
+        })
+        continue
+      }
+      if (evt.type === 'eco.zoon.approval_response') {
+        const content = (evt.content ?? {}) as {
+          approval_id?: string
+          session_id?: string
+          decision?: string
+          option_id?: string
+        }
+        if (!content.session_id || !content.approval_id || !content.decision) continue
+        const decision = content.option_id
+          ? { decision: content.decision, optionId: content.option_id }
+          : { decision: content.decision }
+        const ok = approvals.resolve(
+          content.session_id,
+          content.approval_id,
+          decision as never,
+        )
+        if (!ok) console.warn(`[matrix] unknown approval ${content.approval_id}`)
+        continue
+      }
+      logInbound(evt)
+      // Agent-promotion: top-level inbound event becomes the thread root.
+      // For in-thread messages the existing root is preserved.
+      const promotedRoot = inboundThreadRoot(evt) ?? evt.event_id
+      // Self-heal: if this is a thread reply but we have no in-memory state
+      // for the root (e.g. daemon was just restarted), reconstruct it by
+      // fetching the thread root + relations from the server.
+      const inboundRel = inboundThreadRoot(evt)
+      if (
+        evt.type === 'm.room.message' &&
+        inboundRel &&
+        !threadStates.has(inboundRel) &&
+        evt.room_id
+      ) {
+        try {
+          const rebuilt = await rebuildThreadState(client, evt.room_id, inboundRel, bindings)
+          threadStates.set(inboundRel, rebuilt)
+          console.log(
+            `[matrix] rebuilt threadState for ${inboundRel}: participants=${rebuilt.participants.join(',')} rootMentions=${rebuilt.rootMentions.join(',')}`,
+          )
+        } catch (err) {
+          console.warn(`[matrix] failed to rebuild threadState for ${inboundRel}:`, err)
+        }
+      }
+      const matches = route(evt, bindings, threadStates)
+      // Suppress the no-match warning for events sent by our own bots.
+      const senderIsBot = bindings.some((b) => b.userId === evt.sender)
+      if (evt.type === 'm.room.message' && matches.length === 0 && !senderIsBot) {
+        console.warn(
+          `[matrix] no agent matched message in ${evt.room_id} from ${evt.sender}` +
+            ` (bindings: ${bindings.map((b) => `${b.name}@${b.userId}[${b.trigger}]`).join(', ')})`,
+        )
+      }
+      // Seed thread state for any agent mentions in this event.
+      if (matches.length > 0 && promotedRoot) {
+        let st = threadStates.get(promotedRoot)
+        if (!st) {
+          st = { participants: [], rootMentions: [] }
+          threadStates.set(promotedRoot, st)
+        }
+        const msgMentions = new Set(extractMentions(evt as never))
+        for (const a of bindings) {
+          if (msgMentions.has(a.userId) && !st.rootMentions.includes(a.name)) {
+            st.rootMentions.push(a.name)
+          }
+        }
+      }
+      for (const a of matches) {
+        console.log(`[matrix] → ${a.name} (${a.userId})`)
+        void runTurn(a, evt)
+          .then(() => {
+            if (!promotedRoot) return
+            let st = threadStates.get(promotedRoot)
+            if (!st) {
+              st = { participants: [], rootMentions: [] }
+              threadStates.set(promotedRoot, st)
+            }
+            if (st.participants.at(-1) !== a.name) st.participants.push(a.name)
+          })
+          .catch((err) => {
+            console.error(`[matrix] runTurn failed for ${a.name}:`, err)
+          })
+      }
+    }
+    return c.json({})
+  })
+
+  app.get('/_matrix/app/v1/users/:userId', (c) => {
+    if (!authOk(c.req.header('authorization'))) {
+      return c.json({ errcode: 'M_FORBIDDEN' }, 403)
+    }
+    return c.json({})
+  })
+  app.get('/_matrix/app/v1/rooms/:alias', (c) => {
+    if (!authOk(c.req.header('authorization'))) {
+      return c.json({ errcode: 'M_FORBIDDEN' }, 403)
+    }
+    return c.json({ errcode: 'M_NOT_FOUND' }, 404)
+  })
+  app.post('/_matrix/app/v1/ping', (c) => {
+    if (!authOk(c.req.header('authorization'))) {
+      return c.json({ errcode: 'M_FORBIDDEN' }, 403)
+    }
+    return c.json({})
+  })
+  app.get('/healthz', (c) => c.text('ok'))
+
+  async function runTurn(agent: AgentBinding, evt: MatrixEvent): Promise<void> {
+    if (!evt.room_id || !evt.event_id) return
+    const inbound = inboundThreadRoot(evt)
+    // Agent-promotion: top-level inbound becomes a thread root via the agent's
+    // first reply. sessionKey is always a thread root id, never the room id.
+    const threadRoot = inbound ?? evt.event_id
+    const sessionKey = threadRoot
+    const sessionId = await agents.ensureSession(agent.name, sessionKey, evt.room_id)
+    sessions.set(sessionId, { agent, roomId: evt.room_id, threadRoot })
+    buffers.set(sessionId, '')
+
+    const roomId = evt.room_id
+    const TYPING_TTL_MS = 30_000
+    const TYPING_REFRESH_MS = 25_000
+    const safeTyping = (typing: boolean) =>
+      client
+        .setTyping({ roomId, asUserId: agent.userId, typing, timeoutMs: TYPING_TTL_MS })
+        .catch((err) => console.warn(`[matrix:${agent.name}] setTyping(${typing}) failed:`, err))
+    const safePresence = (presence: 'online' | 'unavailable' | 'offline') =>
+      client
+        .setPresence({ asUserId: agent.userId, presence })
+        .catch((err) =>
+          console.warn(`[matrix:${agent.name}] setPresence(${presence}) failed:`, err),
+        )
+
+    await safeTyping(true)
+    await safePresence('unavailable')
+    const refresh = setInterval(() => {
+      void safeTyping(true)
+    }, TYPING_REFRESH_MS)
+
+    try {
+      const rawBody = evt.content?.body ?? ''
+      const promptText = stripMention(rawBody, agent.userId)
+      await agents.prompt(agent.name, {
+        threadId: sessionKey,
+        channelId: evt.room_id,
+        content: [{ type: 'text', text: promptText }],
+      })
+      const text = buffers.get(sessionId) ?? ''
+      if (text.length > 0) {
+        const html = toMatrixHtml(text)
+        const content: { msgtype: string; body: string; [k: string]: unknown } = {
+          msgtype: 'm.text',
+          body: text,
+        }
+        // Only attach formatted_body when it adds rich-text the plain body
+        // can't carry. marked wraps plain prose in <p>…</p>; if that's all
+        // we'd add, skip — most clients render `body` better than a stripped
+        // re-encode.
+        if (html) {
+          const escapedPlain =
+            '<p>' +
+            text
+              .replace(/&/g, '&amp;')
+              .replace(/</g, '&lt;')
+              .replace(/>/g, '&gt;') +
+            '</p>'
+          const norm = (s: string) => s.replace(/\s+/g, ' ').trim()
+          if (norm(html) !== norm(escapedPlain)) {
+            content.format = 'org.matrix.custom.html'
+            content.formatted_body = html
+          }
+        }
+        await client.sendMessage({
+          roomId: evt.room_id,
+          asUserId: agent.userId,
+          content,
+          threadRoot,                  // every reply threads, full stop
+        })
+      } else {
+        console.warn(
+          `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${evt.room_id}`,
+        )
+      }
+    } finally {
+      clearInterval(refresh)
+      await safeTyping(false)
+      await safePresence('online')
+      buffers.delete(sessionId)
+    }
+  }
+
+  return {
+    app,
+    bootstrap: async (bootstrapOpts: { spaceRoomId?: string; asUserId?: string } = {}) => {
+      await pool.bootstrap({ adminUserId, ...bootstrapOpts })
+      await Promise.allSettled(
+        bindings.map((b) =>
+          client.setPresence({ asUserId: b.userId, presence: 'online' }).catch((err) => {
+            console.warn(`[matrix:${b.name}] initial setPresence(online) failed:`, err)
+          }),
+        ),
+      )
+    },
+    pool,
+  }
+}
+
+/**
+ * Reconstruct the in-memory ThreadState for a thread root by fetching the
+ * root event + its thread relations from the server. Used to recover the
+ * implicit-routing rule from ZOD039 § Implicit triggers in threads after a
+ * daemon restart wipes the in-memory cache.
+ */
+export async function rebuildThreadState(
+  client: MatrixClient,
+  roomId: string,
+  rootEventId: string,
+  bindings: AgentBinding[],
+): Promise<ThreadState> {
+  const state: ThreadState = { participants: [], rootMentions: [] }
+  // Impersonate an agent that's actually a member of this room (AS reads
+  // require room membership). Falling through to the first binding would
+  // 403 if that agent never joined the target room.
+  const asUser = (bindings.find((b) => b.rooms.includes(roomId)) ?? bindings[0])?.userId
+  if (!asUser) return state
+
+  const root = await client.fetchEvent(roomId, rootEventId, asUser)
+  if (root) {
+    const rootMentions = new Set(extractMentions(root as never))
+    for (const a of bindings) {
+      if (rootMentions.has(a.userId) && !state.rootMentions.includes(a.name)) {
+        state.rootMentions.push(a.name)
+      }
+    }
+  }
+
+  const { chunk: thread } = await client.fetchThreadRelations({
+    roomId,
+    rootEventId,
+    asUserId: asUser,
+  })
+  // Also seed root-mentions from any subsequent agent @mentions in the thread.
+  for (const ev of thread) {
+    const mentions = new Set(extractMentions(ev as never))
+    for (const a of bindings) {
+      if (mentions.has(a.userId) && !state.rootMentions.includes(a.name)) {
+        state.rootMentions.push(a.name)
+      }
+    }
+    const sender = (ev as { sender?: string }).sender
+    const type = (ev as { type?: string }).type
+    if (type === 'm.room.message' && sender) {
+      const a = bindings.find((b) => b.userId === sender)
+      if (a && state.participants.at(-1) !== a.name) state.participants.push(a.name)
+    }
+  }
+  return state
+}
+
+function logInbound(evt: MatrixEvent): void {
+  const sender = evt.sender ?? '?'
+  const room = evt.room_id ?? '?'
+  const type = evt.type ?? '?'
+  if (type === 'm.room.message') {
+    const body = evt.content?.body ?? ''
+    const mentions = (evt.content?.['m.mentions'] as { user_ids?: string[] } | undefined)?.user_ids
+    const mentionsStr = mentions?.length ? ` mentions=${JSON.stringify(mentions)}` : ''
+    console.log(
+      `[matrix] inbound msg in ${room} from ${sender}${mentionsStr}: ${truncate(body, 200)}`,
+    )
+  } else {
+    console.log(`[matrix] inbound ${type} in ${room} from ${sender}`)
+  }
+}
+
+function truncate(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n) + '…' : s
+}

package/src/workforce-publisher.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest'
+import { MatrixClient } from './matrix-client.js'
+import { buildWorkforceRoster, publishWorkforce } from './workforce-publisher.js'
+import type { AgentBinding } from './router.js'
+
+const agents: AgentBinding[] = [
+  { name: 'planner', userId: '@planner:zoon.local', rooms: ['!eng:zoon.local'], trigger: 'mention' },
+  { name: 'reviewer', userId: '@reviewer:zoon.local', rooms: ['!eng:zoon.local', '!review:zoon.local'], trigger: 'any' },
+]
+
+describe('buildWorkforceRoster', () => {
+  it('emits version, agents list with user_id/name/rooms', () => {
+    const roster = buildWorkforceRoster(agents)
+    expect(roster).toEqual({
+      version: 1,
+      agents: [
+        { user_id: '@planner:zoon.local', name: 'planner', rooms: ['!eng:zoon.local'] },
+        { user_id: '@reviewer:zoon.local', name: 'reviewer', rooms: ['!eng:zoon.local', '!review:zoon.local'] },
+      ],
+    })
+  })
+
+  it('handles empty workforce', () => {
+    expect(buildWorkforceRoster([])).toEqual({ version: 1, agents: [] })
+  })
+})
+
+describe('publishWorkforce', () => {
+  it('PUTs eco.zoon.workforce state event on the configured space', async () => {
+    const fetch = vi.fn(async () => new Response('{}', { status: 200 }))
+    const client = new MatrixClient({
+      homeserver: 'https://hs.zoon.local',
+      asToken: 'as-tok',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+
+    await publishWorkforce({
+      client,
+      spaceRoomId: '!space:zoon.local',
+      asUserId: '@zooid:zoon.local',
+      agents,
+    })
+
+    expect(fetch).toHaveBeenCalledTimes(1)
+    const [url, init] = fetch.mock.calls[0]!
+    expect(url).toBe(
+      'https://hs.zoon.local/_matrix/client/v3/rooms/!space%3Azoon.local/state/eco.zoon.workforce/?user_id=%40zooid%3Azoon.local',
+    )
+    expect(init?.method).toBe('PUT')
+    expect(init?.headers).toMatchObject({ Authorization: 'Bearer as-tok' })
+    expect(JSON.parse(init?.body as string)).toEqual({
+      version: 1,
+      agents: [
+        { user_id: '@planner:zoon.local', name: 'planner', rooms: ['!eng:zoon.local'] },
+        { user_id: '@reviewer:zoon.local', name: 'reviewer', rooms: ['!eng:zoon.local', '!review:zoon.local'] },
+      ],
+    })
+  })
+
+  it('throws on non-2xx', async () => {
+    const fetch = vi.fn(async () => new Response('forbidden', { status: 403 }))
+    const client = new MatrixClient({
+      homeserver: 'https://hs.zoon.local',
+      asToken: 'as-tok',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await expect(
+      publishWorkforce({
+        client,
+        spaceRoomId: '!space:zoon.local',
+        asUserId: '@zooid:zoon.local',
+        agents,
+      }),
+    ).rejects.toThrow(/403/)
+  })
+})

package/src/workforce-publisher.ts

@@ -0,0 +1,53 @@
+import { MatrixClient } from './matrix-client.js'
+import type { AgentBinding } from './router.js'
+
+export interface WorkforceRoster {
+  version: 1
+  agents: { user_id: string; name: string; rooms: string[] }[]
+}
+
+export function buildWorkforceRoster(agents: AgentBinding[]): WorkforceRoster {
+  return {
+    version: 1,
+    agents: agents.map((a) => ({ user_id: a.userId, name: a.name, rooms: a.rooms })),
+  }
+}
+
+export interface PublishOpts {
+  client: MatrixClient
+  spaceRoomId: string
+  asUserId: string
+  agents: AgentBinding[]
+}
+
+export async function publishWorkforce(opts: PublishOpts): Promise<void> {
+  await opts.client.sendStateEvent({
+    roomId: opts.spaceRoomId,
+    asUserId: opts.asUserId,
+    eventType: 'eco.zoon.workforce',
+    stateKey: '',
+    content: buildWorkforceRoster(opts.agents) as unknown as Record<string, unknown>,
+  })
+}
+
+export interface PublisherHandle {
+  reload(): Promise<void>
+  stop(): Promise<void>
+}
+
+export interface StartOpts {
+  client: MatrixClient
+  spaceRoomId: string
+  asUserId: string
+  getAgents: () => AgentBinding[]
+}
+
+export async function startWorkforcePublisher(opts: StartOpts): Promise<PublisherHandle> {
+  await publishWorkforce({ ...opts, agents: opts.getAgents() })
+  return {
+    async reload() {
+      await publishWorkforce({ ...opts, agents: opts.getAgents() })
+    },
+    async stop() {},
+  }
+}