@zooid/transport-matrix 0.7.0 → 0.7.2

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

@@ -6,7 +6,8 @@ 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 { toToolCallBody, toUpdateBody, toPlanBody, toErrorBody } from './event-encoders.js'
+import { classify } from '@zooid/acp-client'
 import { toMatrixHtml } from './markdown-to-matrix-html.js'
 
 export interface CreateMatrixTransportOptions {
@@ -17,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 {
@@ -42,6 +49,19 @@ 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
+const DRAIN_MAX_MS = 3_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
@@ -49,6 +69,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>()
@@ -74,7 +96,11 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     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)
+        const current = buffers.get(event.sessionId) ?? ''
+        // An empty chunk signals a new text block starting (e.g. after a tool call).
+        // Insert a paragraph break so consecutive blocks don't run together.
+        const prefix = block.text === '' && current.length > 0 ? '\n\n' : ''
+        buffers.set(event.sessionId, current + prefix + block.text)
       } else {
         console.warn(`[matrix:${name}] dropped chunk block type=${block.type}`, block)
       }
@@ -323,6 +349,31 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
           })
           .catch((err) => {
             console.error(`[matrix] runTurn failed for ${a.name}:`, err)
+            const c = classify(err)
+            const threadRoot = inboundThreadRoot(evt) ?? evt.event_id
+            if (!threadRoot || !evt.room_id) return
+            const body = toErrorBody(
+              {
+                kind: 'error',
+                agentId: a.name,
+                sessionId: null,
+                turnId: null,
+                code: c.code,
+                message: err instanceof Error ? err.message : String(err),
+                detail: err instanceof Error && err.stack ? err.stack.slice(0, 2000) : undefined,
+                transient: c.transient,
+                acp_error: c.acp_error,
+              },
+              threadRoot,
+            )
+            void client
+              .sendCustomEvent({
+                roomId: evt.room_id,
+                asUserId: a.userId,
+                eventType: 'eco.zoon.error',
+                content: body,
+              })
+              .catch((e) => console.warn(`[matrix:${a.name}] eco.zoon.error send failed:`, e))
           })
       }
     }
@@ -388,6 +439,17 @@ 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.
+      const drainStart = Date.now()
+      let drained = buffers.get(sessionId) ?? ''
+      while (drainQuietMs > 0 && Date.now() - drainStart < drainMaxMs) {
+        await delay(drainQuietMs)
+        const next = buffers.get(sessionId) ?? ''
+        if (next === drained) break
+        drained = next
+      }
       const text = buffers.get(sessionId) ?? ''
       if (text.length > 0) {
         const html = toMatrixHtml(text)
@@ -434,7 +496,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) =>
@@ -464,7 +532,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),
+    })),
   }
 }