@zooid/transport-matrix 0.7.1 → 0.7.3

package/src/matrix-client.ts

@@ -80,6 +80,20 @@ export class MatrixClient {
     /** Optional `m.room.name`. When set, sent in the createRoom body so the
      *  room has a display name from the moment it exists. */
     name?: string
+    /** When set, the room is created with a `restricted` join rule whose allow
+     *  condition references this space room ID — i.e. joinable by space members
+     *  only, rather than the whole homeserver. */
+    restrictedToSpaceId?: string
+    /** Explicit room version. Restricted join rules require v8+; omit to use the
+     *  homeserver default (modern Tuwunel defaults to v10/v11). */
+    roomVersion?: string
+    /**
+     * Seeds `m.room.power_levels.users` at creation via
+     * `power_level_content_override.users`. The caller owns the full map —
+     * typically the AS bot at 100, plus operator and any agents with
+     * declared PLs. Empty/absent → no override (the preset's defaults apply).
+     */
+    userPowerLevels?: Record<string, number>
   }): Promise<string> {
     const body: Record<string, unknown> = {
       room_alias_name: opts.roomAliasName,
@@ -87,6 +101,22 @@ export class MatrixClient {
       preset: opts.preset ?? 'public_chat',
     }
     if (opts.name !== undefined) body.name = opts.name
+    if (opts.roomVersion !== undefined) body.room_version = opts.roomVersion
+    if (opts.restrictedToSpaceId !== undefined) {
+      body.initial_state = [
+        {
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: {
+            join_rule: 'restricted',
+            allow: [{ type: 'm.room_membership', room_id: opts.restrictedToSpaceId }],
+          },
+        },
+      ]
+    }
+    if (opts.userPowerLevels && Object.keys(opts.userPowerLevels).length > 0) {
+      body.power_level_content_override = { users: opts.userPowerLevels }
+    }
     const r = await this.fetch(
       `${this.homeserver}/_matrix/client/v3/createRoom?user_id=${encodeURIComponent(opts.senderUserId)}`,
       {
@@ -147,6 +177,51 @@ export class MatrixClient {
     return (await r.json()) as { event_id: string }
   }
 
+  /**
+   * Invite a user to a room. Sent as the inviter (`asUserId`) — that user
+   * needs invite power in the room. Tolerates the "already in room /
+   * already invited" responses idempotently so bootstrap can run on a
+   * fresh AND a populated homeserver without branching.
+   */
+  async invite(opts: {
+    roomId: string
+    asUserId: string
+    targetUserId: string
+  }): Promise<void> {
+    const url =
+      `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(opts.roomId)}/invite` +
+      `?user_id=${encodeURIComponent(opts.asUserId)}`
+    const r = await this.fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.asToken}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ user_id: opts.targetUserId }),
+    })
+    if (r.ok) return
+    if (r.status === 403) {
+      // Tuwunel/Synapse use M_FORBIDDEN both for permission errors AND for
+      // "already a member / already invited". Inspect the body so we only
+      // swallow the idempotent case.
+      //
+      // Phrasings seen in the wild:
+      //   - Synapse: "is already in the room", "is already invited"
+      //   - Tuwunel: "cannot invite user that is joined or banned" (one
+      //     string for both "joined" and "banned" — we can't tell which
+      //     from the body; the bot-pool's outer try-catch surfaces a real
+      //     ban via the subsequent joinRoom failure)
+      //   - Generic: "X is already a member of the room"
+      const body = await r.text()
+      const idempotent =
+        /already (in the room|invited|a member|joined)/i.test(body) ||
+        /user that is joined/i.test(body)
+      if (idempotent) return
+      throw new Error(`invite(${opts.targetUserId}) failed: 403 ${body}`)
+    }
+    throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`)
+  }
+
   async joinRoom(roomIdOrAlias: string, asUserId: string): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/join/${encodeURIComponent(roomIdOrAlias)}` +

package/src/router.test.ts

@@ -5,13 +5,13 @@ const agents: AgentBinding[] = [
   {
     name: 'architect',
     userId: '@architect:example.com',
-    rooms: ['!room1:example.com'],
+    rooms: [{ alias: '!room1:example.com' }],
     trigger: 'mention',
   },
   {
     name: 'monitor',
     userId: '@monitor:example.com',
-    rooms: ['!alerts:example.com'],
+    rooms: [{ alias: '!alerts:example.com' }],
     trigger: 'any',
   },
 ]
@@ -67,7 +67,7 @@ describe('route', () => {
       {
         name: 'qa',
         userId: '@qa:example.com',
-        rooms: ['!room1:example.com'],
+        rooms: [{ alias: '!room1:example.com' }],
         trigger: 'mention',
       },
     ]

package/src/router.ts

@@ -1,11 +1,20 @@
+import type { RoomBinding } from '@zooid/core'
 import { extractMentions } from './mentions.js'
 
+export type { RoomBinding }
+
 export interface AgentBinding {
   name: string
   userId: string
   /** Optional human-readable display name. Falls back to the user_id localpart. */
   displayName?: string
-  rooms: string[]
+  /**
+   * Rooms this agent is bound to. Each entry's `alias` starts out as the
+   * configured `#alias` (or `!id`) and is rewritten to the canonical room
+   * ID by `BotPool.bootstrap`. Optional `powerLevel` is seeded into the
+   * room's `m.room.power_levels.users` at room creation only.
+   */
+  rooms: RoomBinding[]
   trigger: 'mention' | 'any'
 }
 
@@ -47,7 +56,7 @@ export function route(
 
   for (const a of agents) {
     if (event.sender === a.userId) continue
-    if (!a.rooms.includes(event.room_id ?? '')) continue
+    if (!a.rooms.some((r) => r.alias === event.room_id)) continue
     if (a.trigger === 'any') {
       matches.push(a)
       continue

package/src/space-provisioner.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { MatrixClient } from './matrix-client.js'
-import { ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
+import { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
 
 function clientWithFetches(...handlers: Array<(url: string, init?: RequestInit) => Response>) {
   let i = 0
@@ -74,6 +74,196 @@ describe('ensureWorkforceSpace', () => {
   })
 })
 
+describe('ensureWorkforceSpace privacy', () => {
+  it('creates the space invite-only (overriding any public preset)', async () => {
+    const { client } = 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.creation_content).toEqual({ type: 'm.space' })
+        expect(body.initial_state).toContainEqual({
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: { join_rule: 'invite' },
+        })
+        return new Response(JSON.stringify({ room_id: '!space: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('!space:hs.zoon.local')
+  })
+})
+
+describe('ensureWorkforceSpace admins', () => {
+  it('emits power_level_content_override with bot + admins at 100 on creation', async () => {
+    const { client } = 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.power_level_content_override).toEqual({
+          users: {
+            '@zooid:hs.zoon.local': 100,
+            '@admin:hs.zoon.local': 100,
+          },
+        })
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+      admins: ['@admin:hs.zoon.local'],
+    })
+  })
+
+  it('invites the admins so they can actually enter the invite-only space', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (_url, init) => {
+        const body = JSON.parse(init!.body as string)
+        expect(body.invite).toEqual(['@admin:hs.zoon.local'])
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+      admins: ['@admin:hs.zoon.local'],
+    })
+  })
+
+  it('omits the override when admins is empty/absent', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (_url, init) => {
+        const body = JSON.parse(init!.body as string)
+        expect(body.power_level_content_override).toBeUndefined()
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+    })
+  })
+})
+
+describe('ensureDefaultChannel', () => {
+  it('returns the existing #general room when its alias resolves', async () => {
+    const { client, fetch } = clientWithFetches((url) => {
+      expect(url).toContain('/_matrix/client/v3/directory/room/%23general%3Ahs.zoon.local')
+      return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+    })
+    const id = await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+      channelLocalpart: 'general',
+    })
+    expect(id).toBe('!gen:hs.zoon.local')
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('creates a restricted #general and attaches it to the space when absent', 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.room_alias_name).toBe('general')
+        expect(body.initial_state).toContainEqual({
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: {
+            join_rule: 'restricted',
+            allow: [{ type: 'm.room_membership', room_id: '!space:hs.zoon.local' }],
+          },
+        })
+        return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+      },
+      (url, init) => {
+        expect(url).toContain(
+          '/_matrix/client/v3/rooms/!space%3Ahs.zoon.local/state/m.space.child/!gen%3Ahs.zoon.local',
+        )
+        expect(JSON.parse(init!.body as string)).toMatchObject({ via: ['hs.zoon.local'] })
+        return new Response(JSON.stringify({ event_id: '$e' }), { status: 200 })
+      },
+    )
+    const id = await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+      channelLocalpart: 'general',
+    })
+    expect(id).toBe('!gen:hs.zoon.local')
+    expect(fetch).toHaveBeenCalledTimes(3)
+  })
+})
+
+describe('ensureDefaultChannel admins', () => {
+  it('seeds operator + bot at PL 100 in the default channel on creation', async () => {
+    const { client } = 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.power_level_content_override).toEqual({
+          users: {
+            '@zooid:hs.zoon.local': 100,
+            '@admin:hs.zoon.local': 100,
+          },
+        })
+        return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+      },
+      () => new Response(JSON.stringify({ event_id: '$e' }), { status: 200 }),
+    )
+    await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+      admins: ['@admin:hs.zoon.local'],
+    })
+  })
+
+  it('omits the override when admins is empty/absent', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (_url, init) => {
+        const body = JSON.parse(init!.body as string)
+        expect(body.power_level_content_override).toBeUndefined()
+        return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+      },
+      () => new Response(JSON.stringify({ event_id: '$e' }), { status: 200 }),
+    )
+    await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+    })
+  })
+})
+
 describe('serverNameFromMxid', () => {
   it('returns the part after the first colon', () => {
     expect(serverNameFromMxid('@zooid:zoon.local')).toBe('zoon.local')

package/src/space-provisioner.ts

@@ -6,6 +6,13 @@ export interface EnsureSpaceOpts {
   serverName: string
   spaceLocalpart: string
   preset: 'public_chat' | 'private_chat'
+  /**
+   * Operator MXIDs to seed at PL 100 in the space's `m.room.power_levels`
+   * at creation. The AS bot is always included. Empty/absent → no override
+   * (the preset's PL defaults apply). Only consulted on first creation —
+   * if the alias already resolves we return the existing room untouched.
+   */
+  admins?: string[]
 }
 
 export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<string> {
@@ -14,15 +21,78 @@ export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<strin
   if (existing) return existing
 
   const display = opts.spaceLocalpart.charAt(0).toUpperCase() + opts.spaceLocalpart.slice(1)
-  return opts.client.createRoomRaw({
+  const body: Record<string, unknown> = {
+    room_alias_name: opts.spaceLocalpart,
+    name: display,
+    preset: opts.preset,
+    creation_content: { type: 'm.space' },
+    // A workspace is joined by invitation, not self-service. Pin the space's
+    // join rule to invite regardless of preset so it can't be walked into
+    // (which would otherwise satisfy every restricted child room's allow).
+    initial_state: [{ type: 'm.room.join_rules', state_key: '', content: { join_rule: 'invite' } }],
+  }
+  if (opts.admins && opts.admins.length > 0) {
+    // Invite each admin so they actually become members — PL 100 alone does
+    // not grant membership in an invite-only space.
+    body.invite = opts.admins
+    const users: Record<string, number> = { [opts.asUserId]: 100 }
+    for (const a of opts.admins) users[a] = 100
+    body.power_level_content_override = { users }
+  }
+  return opts.client.createRoomRaw({ asUserId: opts.asUserId, body })
+}
+
+export interface EnsureDefaultChannelOpts {
+  client: MatrixClient
+  asUserId: string
+  serverName: string
+  spaceId: string
+  /** Localpart of the default channel; defaults to `general`. */
+  channelLocalpart?: string
+  /**
+   * Operator MXIDs to seed at PL 100 in the channel's `m.room.power_levels`
+   * at creation. The AS bot is always included. Empty/absent → no override
+   * (the preset's PL defaults apply). Only consulted on first creation —
+   * if the alias already resolves we return the existing room untouched.
+   */
+  admins?: string[]
+}
+
+/**
+ * Ensure a space has a default channel (`#general` by default), restricted to
+ * the space's members and attached as an `m.space.child`. Idempotent: returns
+ * the existing room if the alias already resolves. Has no agent — it's the
+ * human landing room, so it is created here at provisioning time rather than
+ * via the agent-room path.
+ */
+export async function ensureDefaultChannel(opts: EnsureDefaultChannelOpts): Promise<string> {
+  const localpart = opts.channelLocalpart ?? 'general'
+  const alias = `#${localpart}:${opts.serverName}`
+  const existing = await opts.client.resolveAlias(alias)
+  if (existing) return existing
+
+  let userPowerLevels: Record<string, number> | undefined
+  if (opts.admins && opts.admins.length > 0) {
+    userPowerLevels = { [opts.asUserId]: 100 }
+    for (const a of opts.admins) userPowerLevels[a] = 100
+  }
+
+  const roomId = await opts.client.createRoom({
+    roomAliasName: localpart,
+    invite: [],
+    senderUserId: opts.asUserId,
+    name: localpart.charAt(0).toUpperCase() + localpart.slice(1),
+    restrictedToSpaceId: opts.spaceId,
+    ...(userPowerLevels ? { userPowerLevels } : {}),
+  })
+  await opts.client.sendStateEvent({
+    roomId: opts.spaceId,
     asUserId: opts.asUserId,
-    body: {
-      room_alias_name: opts.spaceLocalpart,
-      name: display,
-      preset: opts.preset,
-      creation_content: { type: 'm.space' },
-    },
+    eventType: 'm.space.child',
+    stateKey: roomId,
+    content: { via: [opts.serverName] },
   })
+  return roomId
 }
 
 export function serverNameFromMxid(mxid: string): string {

package/src/transport.test.ts

@@ -51,12 +51,12 @@ const baseAgents = [
   {
     name: 'architect',
     userId: '@architect:example.com',
-    rooms: ['!r:example.com'],
+    rooms: [{ alias: '!r:example.com' }],
     trigger: 'mention' as const,
   },
 ]
 
-function makeTransport() {
+function makeTransport(drain?: { drainQuietMs?: number; drainMaxMs?: number }) {
   const { reg, finishPrompt } = fakeRegistry()
   const approvals = fakeApprovals()
   const client = fakeClient()
@@ -66,6 +66,10 @@ function makeTransport() {
     client: client as never,
     bindings: baseAgents,
     hsToken: 'hs-secret',
+    // Disable post-turn drain by default so settleTurn (microtasks) suffices.
+    // Tests covering trailing-chunk behavior pass an explicit window.
+    drainQuietMs: drain?.drainQuietMs ?? 0,
+    drainMaxMs: drain?.drainMaxMs,
   })
   return { transport, agents: reg, approvals, client, finishPrompt }
 }
@@ -145,6 +149,58 @@ describe('matrix transport /transactions', () => {
     )
   })
 
+  it('drains trailing agent_message_chunks that arrive after prompt() resolves', async () => {
+    // ACP doesn't guarantee all session/update chunks precede the prompt
+    // response for a normal turn; opencode flushes a trailing chunk just after
+    // the stopReason. The post-turn drain must wait for it instead of sending
+    // the truncated buffer.
+    const { transport, agents, client } = makeTransport({ drainQuietMs: 20, drainMaxMs: 500 })
+    const events = [
+      {
+        type: 'm.room.message',
+        event_id: '$root',
+        room_id: '!r:example.com',
+        sender: '@alice:example.com',
+        content: {
+          msgtype: 'm.text',
+          body: 'hi',
+          'm.mentions': { user_ids: ['@architect:example.com'] },
+        },
+      },
+    ]
+    agents.prompt.mockImplementation(async (_name: string, p: { threadId: string }) => {
+      const sessionId = 'sess-' + p.threadId
+      // First chunk arrives during the turn…
+      agents.onEvent('architect', {
+        type: 'agent_message_chunk',
+        sessionId,
+        content: { type: 'text', text: 'Hi.' },
+      })
+      // …a second chunk lands shortly AFTER the prompt response resolves.
+      setTimeout(() => {
+        agents.onEvent('architect', {
+          type: 'agent_message_chunk',
+          sessionId,
+          content: { type: 'text', text: ' How can I help?' },
+        })
+      }, 5)
+      return { stopReason: 'end_turn' as const }
+    })
+
+    const res = await postTxn(transport.app, { events })
+    expect(res.status).toBe(200)
+    // Wait past the drain window for the turn to finalize.
+    await new Promise((r) => setTimeout(r, 150))
+
+    // Exactly one message, containing BOTH the early and the late chunk.
+    expect(client.sendMessage).toHaveBeenCalledTimes(1)
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: expect.objectContaining({ body: 'Hi. How can I help?' }),
+      }),
+    )
+  })
+
   it('uses an in-thread message event_id as the thread root when one is set', async () => {
     const { transport, agents, client } = makeTransport()
     const events = [

package/src/transport.ts

@@ -18,6 +18,12 @@ export interface CreateMatrixTransportOptions {
   hsToken: string
   /** Admin Matrix user ID. When set, BotPool.bootstrap invites this user into rooms it creates. */
   adminUserId?: string
+  /** Post-turn drain: keep collecting trailing `agent_message_chunk`s until the
+   *  buffer is quiet for this long before flushing. Defaults to `DRAIN_QUIET_MS`.
+   *  Set to 0 to disable the drain (e.g. in tests). */
+  drainQuietMs?: number
+  /** Hard cap on the post-turn drain. Defaults to `DRAIN_MAX_MS`. */
+  drainMaxMs?: number
 }
 
 interface SessionContext {
@@ -43,6 +49,25 @@ interface MatrixEvent {
 const STARTUP_GRACE_MS = 5_000
 const SEEN_EVENT_CAP = 5_000
 
+// ACP only guarantees that an agent flushes pending `session/update`
+// notifications before the `session/prompt` response in the *cancellation*
+// path; for a normal turn the ordering is unspecified. Some agents (e.g.
+// opencode) emit trailing `agent_message_chunk`s a few ms after the stopReason
+// response, so finalizing the moment `prompt()` resolves truncates the reply.
+// After the turn resolves we wait for the buffer to stay unchanged for
+// DRAIN_QUIET_MS (debounce — re-arms on each late chunk) before flushing,
+// capped at DRAIN_MAX_MS so a misbehaving stream can't hang the turn.
+const DRAIN_QUIET_MS = 300
+// 30s upper bound on how long we wait after `session/prompt` resolves before
+// flushing whatever we have (or declaring an empty turn). Set high because
+// some agents — opencode especially — resolve the prompt promise *before*
+// the agent_message_chunk stream starts, and the chunk burst can be 5–15s
+// after that. The drain still short-circuits via DRAIN_QUIET_MS once any
+// content has settled, so this cap only kicks in for genuinely-stuck turns.
+const DRAIN_MAX_MS = 30_000
+
+const delay = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
 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
@@ -50,6 +75,8 @@ function inboundThreadRoot(evt: MatrixEvent): string | undefined {
 
 export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
   const { agents, approvals, client, bindings, hsToken, adminUserId } = opts
+  const drainQuietMs = opts.drainQuietMs ?? DRAIN_QUIET_MS
+  const drainMaxMs = opts.drainMaxMs ?? DRAIN_MAX_MS
   const pool = new BotPool(client, bindings)
   const sessions = new Map<string, SessionContext>()
   const buffers = new Map<string, string>()
@@ -418,6 +445,27 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         channelId: evt.room_id,
         content: [{ type: 'text', text: promptText }],
       })
+      // Drain: the prompt promise resolves on the stopReason response, but
+      // trailing chunks may still arrive (see DRAIN_* above). Wait until the
+      // buffer is quiet for DRAIN_QUIET_MS, re-arming on each new chunk.
+      //
+      // Subtlety: some agents (opencode in particular) resolve `session/prompt`
+      // *before* the agent_message_chunk stream starts. So the buffer can be
+      // empty for several seconds after prompt resolves, and only then do the
+      // chunks arrive. We can't break the drain just because the buffer is
+      // empty — we have to wait up to drainMaxMs for chunks to *start*. Once
+      // any content arrives, the "quiet for drainQuietMs" rule kicks in.
+      const drainStart = Date.now()
+      let drained = buffers.get(sessionId) ?? ''
+      while (drainQuietMs > 0 && Date.now() - drainStart < drainMaxMs) {
+        await delay(drainQuietMs)
+        const next = buffers.get(sessionId) ?? ''
+        // Stop only when we have content AND it hasn't grown — i.e. the
+        // generation has actually started and is now done. An unchanged
+        // empty buffer means the stream hasn't started yet; keep waiting.
+        if (next === drained && next.length > 0) break
+        drained = next
+      }
       const text = buffers.get(sessionId) ?? ''
       if (text.length > 0) {
         const html = toMatrixHtml(text)
@@ -464,7 +512,13 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
 
   return {
     app,
-    bootstrap: async (bootstrapOpts: { spaceRoomId?: string; asUserId?: string } = {}) => {
+    bootstrap: async (
+      bootstrapOpts: {
+        spaceRoomId?: string
+        asUserId?: string
+        adminUserIds?: string[]
+      } = {},
+    ) => {
       await pool.bootstrap({ adminUserId, ...bootstrapOpts })
       await Promise.allSettled(
         bindings.map((b) =>
@@ -494,7 +548,7 @@ export async function rebuildThreadState(
   // 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
+  const asUser = (bindings.find((b) => b.rooms.some((r) => r.alias === roomId)) ?? bindings[0])?.userId
   if (!asUser) return state
 
   const root = await client.fetchEvent(roomId, rootEventId, asUser)

package/src/workforce-publisher.test.ts

@@ -4,8 +4,18 @@ 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' },
+  {
+    name: 'planner',
+    userId: '@planner:zoon.local',
+    rooms: [{ alias: '!eng:zoon.local' }],
+    trigger: 'mention',
+  },
+  {
+    name: 'reviewer',
+    userId: '@reviewer:zoon.local',
+    rooms: [{ alias: '!eng:zoon.local' }, { alias: '!review:zoon.local' }],
+    trigger: 'any',
+  },
 ]
 
 describe('buildWorkforceRoster', () => {

package/src/workforce-publisher.ts

@@ -9,7 +9,11 @@ export interface WorkforceRoster {
 export function buildWorkforceRoster(agents: AgentBinding[]): WorkforceRoster {
   return {
     version: 1,
-    agents: agents.map((a) => ({ user_id: a.userId, name: a.name, rooms: a.rooms })),
+    agents: agents.map((a) => ({
+      user_id: a.userId,
+      name: a.name,
+      rooms: a.rooms.map((r) => r.alias),
+    })),
   }
 }