@zooid/transport-matrix 0.7.0 → 0.7.2

package/src/bot-pool.test.ts

@@ -5,6 +5,7 @@ import type { AgentBinding } from './router.js'
 function fakeClient() {
   return {
     registerBot: vi.fn(async () => undefined),
+    invite: vi.fn(async () => undefined),
     joinRoom: vi.fn(async () => undefined),
     resolveAlias: vi.fn(async (_a: string) => '!existing:example.com' as string | null),
     createRoom: vi.fn(async () => '!new:example.com'),
@@ -18,13 +19,13 @@ const agents: AgentBinding[] = [
   {
     name: 'architect',
     userId: '@architect:example.com',
-    rooms: ['!r1:example.com', '!r2:example.com'],
+    rooms: [{ alias: '!r1:example.com' }, { alias: '!r2:example.com' }],
     trigger: 'mention',
   },
   {
     name: 'monitor',
     userId: '@monitor:example.com',
-    rooms: ['!alerts:example.com'],
+    rooms: [{ alias: '!alerts:example.com' }],
     trigger: 'any',
   },
 ]
@@ -90,7 +91,12 @@ describe('BotPool.bootstrap — create-if-missing rooms', () => {
       },
     }
     const pool = new BotPool(client as never, [
-      { name: 'echo', userId: '@echo:localhost', rooms: ['#welcome:localhost'], trigger: 'mention' },
+      {
+        name: 'echo',
+        userId: '@echo:localhost',
+        rooms: [{ alias: '#welcome:localhost' }],
+        trigger: 'mention',
+      },
     ])
     await pool.bootstrap({ adminUserId: '@admin:localhost' })
 
@@ -115,13 +121,18 @@ describe('BotPool.bootstrap — create-if-missing rooms', () => {
       },
     }
     const pool = new BotPool(client as never, [
-      { name: 'echo', userId: '@echo:localhost', rooms: ['#welcome:localhost'], trigger: 'mention' },
+      {
+        name: 'echo',
+        userId: '@echo:localhost',
+        rooms: [{ alias: '#welcome:localhost' }],
+        trigger: 'mention',
+      },
     ])
     await pool.bootstrap({ adminUserId: '@admin:localhost' })
     expect(calls).toEqual(['join:@echo:localhost->!existing:localhost'])
   })
 
-  it('rewrites the binding\'s rooms array with resolved IDs so the router can match', async () => {
+  it("rewrites the binding's rooms array with resolved IDs so the router can match", async () => {
     const client = {
       registerBot: async () => {},
       setDisplayName: async () => {},
@@ -132,12 +143,12 @@ describe('BotPool.bootstrap — create-if-missing rooms', () => {
     const binding: AgentBinding = {
       name: 'echo',
       userId: '@echo:localhost',
-      rooms: ['#welcome:localhost'],
+      rooms: [{ alias: '#welcome:localhost' }],
       trigger: 'mention',
     }
     const pool = new BotPool(client as never, [binding])
     await pool.bootstrap({ adminUserId: '@admin:localhost' })
-    expect(binding.rooms).toEqual(['!resolved:localhost'])
+    expect(binding.rooms).toEqual([{ alias: '!resolved:localhost' }])
   })
 
   it('passes through room IDs (starting with !) without resolving or creating', async () => {
@@ -156,7 +167,12 @@ describe('BotPool.bootstrap — create-if-missing rooms', () => {
       },
     }
     const pool = new BotPool(client as never, [
-      { name: 'echo', userId: '@echo:localhost', rooms: ['!abc:localhost'], trigger: 'mention' },
+      {
+        name: 'echo',
+        userId: '@echo:localhost',
+        rooms: [{ alias: '!abc:localhost' }],
+        trigger: 'mention',
+      },
     ])
     await pool.bootstrap({ adminUserId: '@admin:localhost' })
     expect(calls).toEqual(['join:@echo:localhost->!abc:localhost'])
@@ -176,6 +192,7 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
     const pool = new BotPool(
       {
         registerBot,
+        invite: vi.fn(async () => undefined),
         joinRoom,
         resolveAlias,
         createRoom,
@@ -186,7 +203,7 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
         {
           name: 'planner',
           userId: '@planner:zoon.local',
-          rooms: ['#welcome:zoon.local'],
+          rooms: [{ alias: '#welcome:zoon.local' }],
           trigger: 'mention',
         },
       ],
@@ -209,11 +226,39 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
     )
   })
 
+  it('creates agent rooms restricted to the workforce space when spaceRoomId is set', async () => {
+    const createRoom = vi.fn(async () => '!created:zoon.local')
+    const pool = new BotPool(
+      {
+        registerBot: vi.fn(async () => undefined),
+        invite: vi.fn(async () => undefined),
+        joinRoom: vi.fn(async () => undefined),
+        resolveAlias: vi.fn(async () => null), // alias unknown → must create
+        createRoom,
+        sendStateEvent: vi.fn(async () => ({ event_id: '$ev' })),
+        setDisplayName: vi.fn(async () => undefined),
+      } as never,
+      [
+        {
+          name: 'planner',
+          userId: '@planner:zoon.local',
+          rooms: [{ alias: '#design:zoon.local' }],
+          trigger: 'mention',
+        },
+      ],
+    )
+    await pool.bootstrap({ spaceRoomId: '!space:zoon.local', asUserId: '@zooid:zoon.local' })
+    expect(createRoom).toHaveBeenCalledWith(
+      expect.objectContaining({ roomAliasName: 'design', restrictedToSpaceId: '!space:zoon.local' }),
+    )
+  })
+
   it('does nothing extra when spaceRoomId is omitted', async () => {
     const sendStateEvent = vi.fn(async () => ({ event_id: '$ev' }))
     const pool = new BotPool(
       {
         registerBot: vi.fn(async () => undefined),
+        invite: vi.fn(async () => undefined),
         joinRoom: vi.fn(async () => undefined),
         resolveAlias: vi.fn(async () => '!r:zoon.local'),
         createRoom: vi.fn(async () => '!r:zoon.local'),
@@ -224,7 +269,7 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
         {
           name: 'planner',
           userId: '@planner:zoon.local',
-          rooms: ['#r:zoon.local'],
+          rooms: [{ alias: '#r:zoon.local' }],
           trigger: 'mention',
         },
       ],
@@ -238,6 +283,7 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
     const pool = new BotPool(
       {
         registerBot: vi.fn(async () => undefined),
+        invite: vi.fn(async () => undefined),
         joinRoom: vi.fn(async () => undefined),
         resolveAlias: vi.fn(async () => '!shared:zoon.local'),
         createRoom: vi.fn(async () => '!shared:zoon.local'),
@@ -245,8 +291,8 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
         setDisplayName: vi.fn(async () => undefined),
       } as never,
       [
-        { name: 'a', userId: '@a:zoon.local', rooms: ['#shared:zoon.local'], trigger: 'any' },
-        { name: 'b', userId: '@b:zoon.local', rooms: ['#shared:zoon.local'], trigger: 'any' },
+        { name: 'a', userId: '@a:zoon.local', rooms: [{ alias: '#shared:zoon.local' }], trigger: 'any' },
+        { name: 'b', userId: '@b:zoon.local', rooms: [{ alias: '#shared:zoon.local' }], trigger: 'any' },
       ],
     )
     await pool.bootstrap({ spaceRoomId: '!space:zoon.local', asUserId: '@zooid:zoon.local' })
@@ -257,6 +303,142 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
   })
 })
 
+describe('BotPool.bootstrap agent space membership', () => {
+  it('invites the agent to the space (via the AS bot) then joins it as the agent', async () => {
+    const invite = vi.fn(async () => undefined)
+    const joinRoom = vi.fn(async () => undefined)
+    const pool = new BotPool(
+      {
+        registerBot: vi.fn(async () => undefined),
+        invite,
+        joinRoom,
+        resolveAlias: vi.fn(async () => '!r:zoon.local'),
+        createRoom: vi.fn(async () => '!r:zoon.local'),
+        sendStateEvent: vi.fn(async () => ({ event_id: '$ev' })),
+        setDisplayName: vi.fn(async () => undefined),
+      } as never,
+      [
+        {
+          name: 'planner',
+          userId: '@planner:zoon.local',
+          rooms: [{ alias: '#r:zoon.local' }],
+          trigger: 'mention',
+        },
+      ],
+    )
+    await pool.bootstrap({
+      spaceRoomId: '!space:zoon.local',
+      asUserId: '@zooid:zoon.local',
+    })
+    expect(invite).toHaveBeenCalledWith({
+      roomId: '!space:zoon.local',
+      asUserId: '@zooid:zoon.local',
+      targetUserId: '@planner:zoon.local',
+    })
+    expect(joinRoom).toHaveBeenCalledWith('!space:zoon.local', '@planner:zoon.local')
+  })
+
+  it('skips space invite+join when spaceRoomId is not provided', async () => {
+    const invite = vi.fn(async () => undefined)
+    const pool = new BotPool(
+      {
+        registerBot: vi.fn(async () => undefined),
+        invite,
+        joinRoom: vi.fn(async () => undefined),
+        resolveAlias: vi.fn(async () => '!r:zoon.local'),
+        createRoom: vi.fn(async () => '!r:zoon.local'),
+        sendStateEvent: vi.fn(async () => ({ event_id: '$ev' })),
+        setDisplayName: vi.fn(async () => undefined),
+      } as never,
+      [
+        {
+          name: 'planner',
+          userId: '@planner:zoon.local',
+          rooms: [{ alias: '#r:zoon.local' }],
+          trigger: 'mention',
+        },
+      ],
+    )
+    await pool.bootstrap({})
+    expect(invite).not.toHaveBeenCalled()
+  })
+})
+
+describe('BotPool.bootstrap creation-time power levels', () => {
+  it('merges admin (PL 100) and per-agent declared PLs into createRoom userPowerLevels', async () => {
+    const createRoom = vi.fn(async () => '!created:zoon.local')
+    const pool = new BotPool(
+      {
+        registerBot: vi.fn(async () => undefined),
+        invite: vi.fn(async () => undefined),
+        joinRoom: vi.fn(async () => undefined),
+        resolveAlias: vi.fn(async () => null), // force create
+        createRoom,
+        sendStateEvent: vi.fn(async () => ({ event_id: '$ev' })),
+        setDisplayName: vi.fn(async () => undefined),
+      } as never,
+      [
+        {
+          name: 'planner',
+          userId: '@planner:zoon.local',
+          rooms: [{ alias: '#design:zoon.local' }], // default PL
+          trigger: 'mention',
+        },
+        {
+          name: 'mod',
+          userId: '@mod:zoon.local',
+          rooms: [{ alias: '#design:zoon.local', powerLevel: 50 }], // moderator
+          trigger: 'mention',
+        },
+      ],
+    )
+    await pool.bootstrap({
+      asUserId: '@zooid:zoon.local',
+      spaceRoomId: '!space:zoon.local',
+      adminUserIds: ['@admin:zoon.local'],
+    })
+
+    // First createRoom carries the merged map:
+    //   bot @ 100, admin @ 100, mod @ 50 (planner has no declared PL → absent)
+    const firstCall = createRoom.mock.calls[0]?.[0] as {
+      userPowerLevels?: Record<string, number>
+    }
+    expect(firstCall.userPowerLevels).toEqual({
+      '@zooid:zoon.local': 100,
+      '@admin:zoon.local': 100,
+      '@mod:zoon.local': 50,
+    })
+  })
+
+  it('omits userPowerLevels when no admin and no agent declares a PL for the room', async () => {
+    const createRoom = vi.fn(async () => '!r:zoon.local')
+    const pool = new BotPool(
+      {
+        registerBot: vi.fn(async () => undefined),
+        invite: vi.fn(async () => undefined),
+        joinRoom: vi.fn(async () => undefined),
+        resolveAlias: vi.fn(async () => null),
+        createRoom,
+        sendStateEvent: vi.fn(async () => ({ event_id: '$ev' })),
+        setDisplayName: vi.fn(async () => undefined),
+      } as never,
+      [
+        {
+          name: 'plain',
+          userId: '@plain:zoon.local',
+          rooms: [{ alias: '#plain:zoon.local' }],
+          trigger: 'mention',
+        },
+      ],
+    )
+    await pool.bootstrap({ spaceRoomId: '!space:zoon.local' })
+    const opts = createRoom.mock.calls[0]?.[0] as {
+      userPowerLevels?: Record<string, number>
+    }
+    expect(opts.userPowerLevels).toBeUndefined()
+  })
+})
+
 describe('BotPool.bootstrap — display name', () => {
   it('falls back to the user_id localpart when no displayName is supplied', async () => {
     const client = fakeClient()
@@ -297,7 +479,12 @@ describe('BotPool.bootstrap — display name', () => {
       setDisplayName: vi.fn(async () => undefined),
     }
     const pool = new BotPool(client as never, [
-      { name: 'echo', userId: '@echo:localhost', rooms: ['#welcome:localhost'], trigger: 'mention' },
+      {
+        name: 'echo',
+        userId: '@echo:localhost',
+        rooms: [{ alias: '#welcome:localhost' }],
+        trigger: 'mention',
+      },
     ])
     await pool.bootstrap({ adminUserId: '@admin:localhost' })
     expect(createRoom).toHaveBeenCalledWith(

package/src/bot-pool.ts

@@ -9,13 +9,25 @@ export interface BootstrapOpts {
   spaceRoomId?: string
   /** AS bot user ID. Required when spaceRoomId is set; sender of the m.space.child write. */
   asUserId?: string
+  /**
+   * Operator MXIDs seeded at PL 100 in every agent room this pool creates.
+   * Applied via `power_level_content_override.users` at room creation only —
+   * never reconciled. Empty/absent = no operator entries.
+   */
+  adminUserIds?: string[]
 }
 
 export class BotPool {
   constructor(
     private readonly client: Pick<
       MatrixClient,
-      'registerBot' | 'joinRoom' | 'resolveAlias' | 'createRoom' | 'sendStateEvent' | 'setDisplayName'
+      | 'registerBot'
+      | 'invite'
+      | 'joinRoom'
+      | 'resolveAlias'
+      | 'createRoom'
+      | 'sendStateEvent'
+      | 'setDisplayName'
     >,
     private readonly agents: AgentBinding[],
   ) {}
@@ -35,8 +47,28 @@ export class BotPool {
       } catch (err) {
         console.warn(`[matrix] setDisplayName(${a.userId}) failed: ${(err as Error).message}`)
       }
+      // Make each agent a member of the workforce space. That covers two
+      // things at once: the eco.zoon.workforce roster is now backed by
+      // actual space membership (so the Zoon client's member autocomplete
+      // works across rooms), and every restricted child room's allow rule
+      // is satisfied without per-room invites.
+      if (opts.spaceRoomId && opts.asUserId) {
+        try {
+          await this.client.invite({
+            roomId: opts.spaceRoomId,
+            asUserId: opts.asUserId,
+            targetUserId: a.userId,
+          })
+          await this.client.joinRoom(opts.spaceRoomId, a.userId)
+        } catch (err) {
+          console.warn(
+            `[matrix] space membership for ${a.userId} failed: ${(err as Error).message}`,
+          )
+        }
+      }
       for (let i = 0; i < a.rooms.length; i++) {
-        const room = a.rooms[i]
+        const binding = a.rooms[i]!
+        const room = binding.alias
         try {
           let resolved = room
           if (room.startsWith('#')) {
@@ -51,19 +83,29 @@ export class BotPool {
                 const colon = room.indexOf(':')
                 const aliasLocalpart = colon > 1 ? room.slice(1, colon) : room.slice(1)
                 const sender = opts.adminUserId ?? a.userId
+                const userPowerLevels = buildUserPowerLevels(
+                  opts.asUserId,
+                  opts.adminUserIds,
+                  this.agents,
+                  room,
+                )
                 resolved = await this.client.createRoom({
                   roomAliasName: aliasLocalpart,
                   invite: opts.adminUserId ? [opts.adminUserId] : [],
                   senderUserId: sender,
                   name: aliasLocalpart,
+                  ...(opts.spaceRoomId ? { restrictedToSpaceId: opts.spaceRoomId } : {}),
+                  ...(userPowerLevels ? { userPowerLevels } : {}),
                 })
               }
               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
+          // Rewrite the binding's alias to the canonical room ID so the
+          // router (which matches on event.room_id) sees a hit when Tuwunel
+          // pushes events. The declared powerLevel was a creation-time
+          // seed — it has no role after bootstrap.
+          binding.alias = resolved
           await this.client.joinRoom(resolved, a.userId)
 
           if (
@@ -110,3 +152,29 @@ function localpart(userId: string): string {
   if (!m) throw new Error(`bad user id: ${userId}`)
   return m[1]
 }
+
+/**
+ * Build the `userPowerLevels` map for a room about to be created. Always
+ * seeds the AS bot (when known) and any operator admins at PL 100; layers
+ * per-agent declared PLs on top so agents land at moderator (or whatever
+ * they declared) without a follow-up state write. Returns undefined when
+ * the map would be empty — `createRoom` then omits the override entirely
+ * and the preset's defaults apply.
+ */
+function buildUserPowerLevels(
+  asUserId: string | undefined,
+  admins: string[] | undefined,
+  agents: AgentBinding[],
+  roomAlias: string,
+): Record<string, number> | undefined {
+  const users: Record<string, number> = {}
+  if (asUserId) users[asUserId] = 100
+  if (admins) for (const a of admins) users[a] = 100
+  for (const a of agents) {
+    for (const r of a.rooms) {
+      if (r.alias !== roomAlias) continue
+      if (r.powerLevel !== undefined) users[a.userId] = r.powerLevel
+    }
+  }
+  return Object.keys(users).length > 0 ? users : undefined
+}

package/src/event-encoders.test.ts

@@ -8,6 +8,7 @@ import {
   toToolCallBody,
   toUpdateBody,
   toPlanBody,
+  toErrorBody,
 } from './event-encoders.js'
 
 describe('toToolCallBody', () => {
@@ -122,3 +123,88 @@ describe('toPlanBody', () => {
     })
   })
 })
+
+describe('toErrorBody', () => {
+  const threadRoot = '$root-event-id'
+
+  it('encodes a full error TapEvent including acp_error and recovery URL', () => {
+    const body = toErrorBody(
+      {
+        kind: 'error',
+        agentId: 'alice',
+        sessionId: 'sess-1',
+        turnId: 'turn-1',
+        code: 'auth_missing',
+        message: 'Authentication required',
+        detail: 'claude-agent-acp returned RequestError on session/prompt',
+        transient: false,
+        acp_error: { code: -32000, message: 'Authentication required' },
+      },
+      threadRoot,
+    )
+    expect(body).toMatchObject({
+      msgtype: 'm.notice',
+      body: '⚠ [auth_missing] Authentication required',
+      session_id: 'sess-1',
+      turn_id: 'turn-1',
+      code: 'auth_missing',
+      message: 'Authentication required',
+      detail: 'claude-agent-acp returned RequestError on session/prompt',
+      transient: false,
+      acp_error: { code: -32000, message: 'Authentication required' },
+      'm.relates_to': { rel_type: 'm.thread', event_id: '$root-event-id' },
+    })
+    expect(body.recovery).toMatch(/^https:\/\/zooid\.dev\/docs\//)
+  })
+
+  it('truncates message to 250 chars and detail to 2000 chars', () => {
+    const body = toErrorBody(
+      {
+        kind: 'error',
+        agentId: 'a',
+        sessionId: 's',
+        turnId: 't',
+        code: 'internal',
+        message: 'x'.repeat(500),
+        detail: 'y'.repeat(5000),
+        transient: false,
+      },
+      threadRoot,
+    )
+    expect((body.message as string).length).toBe(250)
+    expect((body.detail as string).length).toBe(2000)
+  })
+
+  it('omits turn_id when null and omits acp_error when undefined', () => {
+    const body = toErrorBody(
+      {
+        kind: 'error',
+        agentId: 'a',
+        sessionId: 's',
+        turnId: null,
+        code: 'container_exit',
+        message: 'Container exited',
+        transient: true,
+      },
+      threadRoot,
+    )
+    expect(body.turn_id).toBeUndefined()
+    expect(body.acp_error).toBeUndefined()
+  })
+
+  it('omits session_id when null (failure preceded session/new)', () => {
+    const body = toErrorBody(
+      {
+        kind: 'error',
+        agentId: 'a',
+        sessionId: null,
+        turnId: null,
+        code: 'image_pull_failed',
+        message: 'pull failed',
+        transient: true,
+      },
+      threadRoot,
+    )
+    expect(body.session_id).toBeUndefined()
+  })
+})

package/src/event-encoders.ts

@@ -1,5 +1,6 @@
 import type {
   PlanEvent,
+  TapEvent,
   ToolCallEvent,
   ToolCallUpdateEvent,
 } from '@zooid/acp-client'
@@ -64,3 +65,31 @@ export function toPlanBody(evt: PlanEvent): Record<string, unknown> {
     entries: evt.entries,
   }
 }
+
+const RECOVERY_URLS: Partial<Record<string, string>> = {
+  auth_missing: 'https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over',
+  auth_invalid: 'https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over',
+  mount_failed: 'https://zooid.dev/docs/guides/run-in-container#what-you-get-for-free',
+  image_pull_failed: 'https://zooid.dev/docs/guides/run-in-container#skipping-the-image-prepull',
+}
+
+type ErrorTap = Extract<TapEvent, { kind: 'error' }>
+
+export function toErrorBody(evt: ErrorTap, threadRoot: string): Record<string, unknown> {
+  const msg = evt.message.slice(0, 250)
+  const out: Record<string, unknown> = {
+    msgtype: 'm.notice',
+    body: `⚠ [${evt.code}] ${msg}`,
+    code: evt.code,
+    message: msg,
+    transient: evt.transient,
+    'm.relates_to': { rel_type: 'm.thread', event_id: threadRoot },
+  }
+  if (evt.sessionId) out.session_id = evt.sessionId
+  if (evt.turnId) out.turn_id = evt.turnId
+  if (evt.detail) out.detail = evt.detail.slice(0, 2000)
+  if (evt.acp_error) out.acp_error = evt.acp_error
+  const recovery = RECOVERY_URLS[evt.code]
+  if (recovery) out.recovery = recovery
+  return out
+}

package/src/index.ts

@@ -11,8 +11,8 @@ export type { AgentBinding, RouteMatch } from './router.js'
 export { BotPool } from './bot-pool.js'
 export { createMatrixTransport } from './transport.js'
 export type { CreateMatrixTransportOptions } from './transport.js'
-export { ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
-export type { EnsureSpaceOpts } from './space-provisioner.js'
+export { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
+export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {
   buildWorkforceRoster,
   publishWorkforce,