@zooid/transport-matrix 0.7.4 → 0.9.0

package/src/transport.ts

@@ -1,14 +1,38 @@
 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 type { AgentEvent, ContentBlock } 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 { route, isMediaMsgtype, type AgentBinding, type ThreadState } from './router.js'
 import { stripMention, extractMentions } from './mentions.js'
-import { toToolCallBody, toUpdateBody, toPlanBody, toErrorBody } from './event-encoders.js'
+import { toToolCallBody, toUpdateBody, toPlanBody, toAvailableCommandsBody, toErrorBody } from './event-encoders.js'
 import { classify } from '@zooid/acp-client'
 import { toMatrixHtml } from './markdown-to-matrix-html.js'
+import {
+  PendingMediaStore,
+  type PendingMediaItem,
+} from './pending-media.js'
+import {
+  MediaClient,
+  MAX_INLINE_IMAGE_BYTES,
+  INLINE_IMAGE_MIMES,
+} from './media-client.js'
+import { writeAttachment } from './attachments.js'
+
+export interface MediaClientLike {
+  download(input: {
+    mxcUri: string
+    asUserId: string
+    maxBytes?: number
+  }): Promise<{ data: Uint8Array; contentType: string }>
+  upload(input: {
+    data: Uint8Array
+    contentType: string
+    filename?: string
+    asUserId: string
+  }): Promise<{ content_uri: string }>
+}
 
 export interface CreateMatrixTransportOptions {
   agents: AcpRegistry
@@ -24,6 +48,14 @@ export interface CreateMatrixTransportOptions {
   drainQuietMs?: number
   /** Hard cap on the post-turn drain. Defaults to `DRAIN_MAX_MS`. */
   drainMaxMs?: number
+  /** Injected media client for downloading/uploading Matrix media. */
+  media?: MediaClientLike
+  /** Injected attachment writer (defaults to the real writeAttachment). */
+  writeAttachmentFn?: typeof writeAttachment
+  /** AS sender-bot MXID (@<sender_localpart>:<server>). Together with the agent
+   *  bindings this forms the set of "our bot users" whose ad-hoc invites are
+   *  declined. */
+  botUserId?: string
 }
 
 interface SessionContext {
@@ -39,14 +71,131 @@ interface MatrixEvent {
   origin_server_ts?: number
   room_id?: string
   sender?: string
+  /** Present on state events (m.room.member → the affected user). */
+  state_key?: string
   content?: Record<string, unknown> & {
     msgtype?: string
     body?: string
+    membership?: string
     'm.relates_to'?: { rel_type?: string; event_id?: string }
   }
 }
 
 const STARTUP_GRACE_MS = 5_000
+
+interface MediaBlocksResult {
+  blocks: ContentBlock[]
+  pathLines: string[]
+}
+
+async function buildMediaBlocks(
+  items: PendingMediaItem[],
+  opts: {
+    agent: AgentBinding
+    media: MediaClientLike | undefined
+    writeAttachmentFn: typeof writeAttachment
+    onError: (item: PendingMediaItem, err: unknown) => void
+  },
+): Promise<MediaBlocksResult> {
+  const blocks: ContentBlock[] = []
+  const pathLines: string[] = []
+
+  if (!opts.media || items.length === 0) return { blocks, pathLines }
+
+  for (const item of items) {
+    try {
+      const isInlineCandidate =
+        item.msgtype === 'm.image' &&
+        INLINE_IMAGE_MIMES.includes(item.info?.mimetype ?? '') &&
+        (item.info?.size === undefined || item.info.size <= MAX_INLINE_IMAGE_BYTES)
+
+      if (isInlineCandidate) {
+        const { data, contentType } = await opts.media.download({
+          mxcUri: item.url,
+          asUserId: opts.agent.userId,
+        })
+        // Double-check actual size (info can lie)
+        if (data.byteLength <= MAX_INLINE_IMAGE_BYTES) {
+          blocks.push({
+            type: 'image',
+            data: Buffer.from(data).toString('base64'),
+            mimeType: contentType,
+          })
+          continue
+        }
+        // Actual size exceeded cap — fall through to file route with the already-downloaded bytes
+        if (opts.agent.workspaceDir) {
+          const paths = opts.writeAttachmentFn({
+            workspaceDir: opts.agent.workspaceDir,
+            agentWorkspacePath: opts.agent.agentWorkspacePath ?? opts.agent.workspaceDir,
+            eventId: item.eventId,
+            filename: item.filename ?? item.body,
+            data,
+          })
+          blocks.push({
+            type: 'resource_link',
+            uri: `file://${paths.agentPath}`,
+            name: item.filename ?? item.body,
+          })
+          pathLines.push(`Attached file: ${paths.agentPath}`)
+        }
+      } else {
+        // File route (m.file, m.video, m.audio, or oversized image)
+        if (!opts.agent.workspaceDir) continue
+        const { data } = await opts.media.download({
+          mxcUri: item.url,
+          asUserId: opts.agent.userId,
+        })
+        const paths = opts.writeAttachmentFn({
+          workspaceDir: opts.agent.workspaceDir,
+          agentWorkspacePath: opts.agent.agentWorkspacePath ?? opts.agent.workspaceDir,
+          eventId: item.eventId,
+          filename: item.filename ?? item.body,
+          data,
+        })
+        blocks.push({
+          type: 'resource_link',
+          uri: `file://${paths.agentPath}`,
+          name: item.filename ?? item.body,
+          mimeType: item.info?.mimetype,
+          size: item.info?.size,
+        })
+        pathLines.push(`Attached file: ${paths.agentPath}`)
+      }
+    } catch (err) {
+      opts.onError(item, err)
+    }
+  }
+
+  return { blocks, pathLines }
+}
+
+async function sendMediaError(
+  ctx: { agent: AgentBinding; roomId: string; threadRoot: string },
+  _err: unknown,
+  message: string,
+  client: MatrixClient,
+): Promise<void> {
+  await client
+    .sendCustomEvent({
+      roomId: ctx.roomId,
+      asUserId: ctx.agent.userId,
+      eventType: 'dev.zooid.error',
+      content: toErrorBody(
+        {
+          kind: 'error' as const,
+          agentId: ctx.agent.name,
+          sessionId: null,
+          turnId: null,
+          code: 'media_failed',
+          message: message.slice(0, 250),
+          transient: false,
+        },
+        ctx.threadRoot,
+      ),
+    })
+    .catch((e) => console.warn(`[matrix:${ctx.agent.name}] dev.zooid.error send failed:`, e))
+}
 const SEEN_EVENT_CAP = 5_000
 
 // ACP only guarantees that an agent flushes pending `session/update`
@@ -74,10 +223,20 @@ function inboundThreadRoot(evt: MatrixEvent): string | undefined {
 }
 
 export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
-  const { agents, approvals, client, bindings, hsToken, adminUserId } = opts
+  const { agents, approvals, client, bindings, hsToken, adminUserId, botUserId } = opts
   const drainQuietMs = opts.drainQuietMs ?? DRAIN_QUIET_MS
   const drainMaxMs = opts.drainMaxMs ?? DRAIN_MAX_MS
+  const mediaClient = opts.media
+  const writeAttachmentFn = opts.writeAttachmentFn ?? writeAttachment
+  const pendingMedia = new PendingMediaStore()
   const pool = new BotPool(client, bindings)
+  const ourBotUserIds = new Set<string>([
+    ...(botUserId ? [botUserId] : []),
+    ...bindings.map((b) => b.userId),
+  ])
+  const DECLINE_REASON =
+    'Bots are placed in rooms only by the zooid daemon (workforce-as-code). ' +
+    'Ad-hoc invites are declined — add the bot to the room in zooid.yaml.'
   const sessions = new Map<string, SessionContext>()
   const buffers = new Map<string, string>()
   // Last messageId seen per session's buffer. opencode streams each assistant
@@ -95,56 +254,172 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
   // 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>()
+  // Messages flushed per session this turn. Lets the drain loop tell "stream
+  // not started yet" (0 flushes, empty buffer → keep waiting) from "turn done,
+  // last message already flushed mid-stream" (>0 flushes, empty buffer → stop).
+  const flushedCounts = new Map<string, number>()
+  // Commands a shim advertises during session load/new — i.e. before runTurn
+  // registers the session ctx (sessions.set). Stashed here keyed by sessionId
+  // and replayed once the ctx exists, so `available_commands_update` (which is
+  // only ever emitted at session establishment, never mid-turn) isn't dropped.
+  const pendingCommands = new Map<string, AgentEvent>()
+
+  // Build the m.text content for a chunk of assistant prose, attaching a
+  // formatted_body only when the HTML render adds rich text the plain body
+  // can't carry (marked wraps plain prose in <p>…</p>; skip that — most
+  // clients render `body` better than a stripped re-encode).
+  const buildTextContent = (
+    text: string,
+  ): { msgtype: string; body: string; [k: string]: unknown } => {
+    const content: { msgtype: string; body: string; [k: string]: unknown } = {
+      msgtype: 'm.text',
+      body: text,
+    }
+    const html = toMatrixHtml(text)
+    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
+      }
+    }
+    return content
+  }
+
+  // Flush a session's buffered assistant text as its own Matrix message and
+  // clear the buffer. No-op on an empty buffer. The send is chained onto
+  // sendQueue so it orders correctly against tool_call/plan events from the
+  // same turn. The buffer is cleared synchronously (before the first await),
+  // so a chunk for the *next* message that arrives during the send starts
+  // fresh. Returns true when a message was enqueued.
+  const flushBuffer = (sessionId: string): boolean => {
+    const ctx = sessions.get(sessionId)
+    const text = buffers.get(sessionId) ?? ''
+    if (!ctx || text.length === 0) return false
+    buffers.set(sessionId, '')
+    flushedCounts.set(sessionId, (flushedCounts.get(sessionId) ?? 0) + 1)
+    const content = buildTextContent(text)
+    const tail = (sendQueue.get(sessionId) ?? Promise.resolve()).then(async () => {
+      try {
+        await client.sendMessage({
+          roomId: ctx.roomId,
+          asUserId: ctx.agent.userId,
+          content,
+          threadRoot: ctx.threadRoot,
+        })
+      } catch (err) {
+        console.warn(`[matrix:${ctx.agent.name}] sendMessage flush failed:`, err)
+      }
+    })
+    sendQueue.set(sessionId, tail)
+    return true
+  }
 
   agents.onEvent = async (name, event: AgentEvent) => {
     const ctx = sessions.get(event.sessionId)
     if (!ctx) {
-      console.warn(`[matrix:${name}] no session ctx for ${event.sessionId}`)
+      // available_commands_update is advertised during ensureSession (session
+      // load/new), before runTurn calls sessions.set — so the ctx isn't there
+      // yet. Stash the latest roster and replay it once runTurn registers the
+      // ctx. Other event types arriving without a ctx are genuinely orphaned
+      // (e.g. replayed history for a thread we're not handling) — drop them.
+      if (event.type === 'available_commands') {
+        pendingCommands.set(event.sessionId, event)
+      } else {
+        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 }
+      const block = event.content as { type?: string; text?: string; data?: string; mimeType?: string }
       if (block.type === 'text' && typeof block.text === 'string') {
-        const current = buffers.get(event.sessionId) ?? ''
-        // Within a message, tokens carry their own leading spaces, so we
-        // concatenate raw. Two signals start a *new* message block that must not
-        // run together with the previous text:
-        //  - an empty chunk (some agents emit one between blocks, e.g. after a
-        //    tool call), or
-        //  - a change in messageId — opencode streams each assistant message
-        //    under its own id and emits no delimiter chunk between them, and the
-        //    first token of the new message has no leading space, so without
-        //    this they weld together ("…one.🅿️").
+        // A change in ACP messageId marks the previous assistant message as
+        // complete. opencode streams each assistant message under its own id
+        // with no delimiter chunk between them, so a change here is the only
+        // boundary signal. Flush the previous message as its own Matrix
+        // message — each ACP message lands separately (and interleaves with
+        // tool_call/plan events) instead of welding into one turn-end blob.
         const prevMessageId = bufferMessageIds.get(event.sessionId)
         const messageChanged =
           event.messageId !== undefined &&
           prevMessageId !== undefined &&
           event.messageId !== prevMessageId
-        const needsBreak =
-          current.length > 0 && (block.text === '' || messageChanged)
-        const prefix = needsBreak ? '\n\n' : ''
-        buffers.set(event.sessionId, current + prefix + block.text)
         if (event.messageId !== undefined)
           bufferMessageIds.set(event.sessionId, event.messageId)
+        // flushBuffer clears the buffer synchronously, so the new message's
+        // text below starts fresh.
+        if (messageChanged) flushBuffer(event.sessionId)
+        // Within a single message, tokens carry their own leading spaces, so we
+        // concatenate raw. An empty chunk (some agents emit one between blocks,
+        // e.g. after a tool call within the same message) is a paragraph break.
+        const current = buffers.get(event.sessionId) ?? ''
+        const needsBreak = current.length > 0 && block.text === ''
+        const prefix = needsBreak ? '\n\n' : ''
+        buffers.set(event.sessionId, current + prefix + block.text)
+      } else if (
+        block.type === 'image' &&
+        typeof block.data === 'string' &&
+        typeof block.mimeType === 'string' &&
+        mediaClient
+      ) {
+        // Outbound agent image: upload immediately and send as a threaded m.image.
+        const ctx = sessions.get(event.sessionId)
+        if (ctx) {
+          const bytes = Buffer.from(block.data, 'base64')
+          const ext = (block.mimeType.split('/')[1] ?? 'png').replace(/[^a-z0-9]/gi, '')
+          const filename = `image.${ext}`
+          void mediaClient
+            .upload({ data: bytes, contentType: block.mimeType, filename, asUserId: ctx.agent.userId })
+            .then(({ content_uri }) =>
+              client.sendMessage({
+                roomId: ctx.roomId,
+                asUserId: ctx.agent.userId,
+                threadRoot: ctx.threadRoot,
+                content: {
+                  msgtype: 'm.image',
+                  body: filename,
+                  url: content_uri,
+                  info: { mimetype: block.mimeType, size: bytes.length },
+                },
+              }),
+            )
+            .catch((err) => {
+              console.warn(`[matrix:${name}] outbound image upload failed:`, err)
+              void sendMediaError(ctx, err, 'agent image upload failed', client)
+            })
+        }
       } else {
         console.warn(`[matrix:${name}] dropped chunk block type=${block.type}`, block)
       }
       return
     }
 
+    // An out-of-band event (tool_call / tool_call_update / plan) after some
+    // buffered text means that assistant message is complete — flush it first
+    // so it lands before this event on the wire, preserving interleaving.
+    flushBuffer(event.sessionId)
+
     const eventType =
       event.type === 'tool_call'
-        ? 'eco.zoon.tool_call'
+        ? 'dev.zooid.tool_call'
         : event.type === 'tool_call_update'
-          ? 'eco.zoon.tool_call_update'
-          : 'eco.zoon.plan'
+          ? 'dev.zooid.tool_call_update'
+          : event.type === 'available_commands'
+            ? 'dev.zooid.available_commands_update'
+            : 'dev.zooid.plan'
     const body =
       event.type === 'tool_call'
         ? toToolCallBody(event)
         : event.type === 'tool_call_update'
           ? toUpdateBody(event)
-          : toPlanBody(event)
+          : event.type === 'available_commands'
+            ? toAvailableCommandsBody(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 {
@@ -185,7 +460,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     void client.sendCustomEvent({
       roomId: ctx.roomId,
       asUserId: ctx.agent.userId,
-      eventType: 'eco.zoon.approval_request',
+      eventType: 'dev.zooid.approval_request',
       content,
     })
   })
@@ -227,7 +502,28 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         )
         continue
       }
-      if (evt.type === 'eco.zoon.session_reset') {
+      if (evt.type === 'm.room.member' && evt.content?.membership === 'invite') {
+        const target = evt.state_key
+        const inviter = evt.sender
+        if (
+          target &&
+          evt.room_id &&
+          ourBotUserIds.has(target) &&
+          (!inviter || !ourBotUserIds.has(inviter))
+        ) {
+          console.log(
+            `[matrix] declining ad-hoc invite for ${target} in ${evt.room_id} ` +
+              `from ${inviter ?? 'unknown'}`,
+          )
+          await client
+            .leaveRoom(evt.room_id, target, { reason: DECLINE_REASON })
+            .catch((err) =>
+              console.warn(`[matrix] leaveRoom(${evt.room_id}, ${target}) failed:`, err),
+            )
+        }
+        continue
+      }
+      if (evt.type === 'dev.zooid.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
@@ -236,10 +532,10 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         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')
+          console.log('[matrix] dropping dev.zooid.session_reset without thread relation')
           continue
         }
-        console.log(`[matrix] inbound eco.zoon.session_reset in ${evt.room_id} thread=${threadRoot}`)
+        console.log(`[matrix] inbound dev.zooid.session_reset in ${evt.room_id} thread=${threadRoot}`)
         for (const a of bindings) {
           agents.endSession(a.name, threadRoot)
         }
@@ -249,7 +545,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         // the most-recently-posting agent under the same sessionKey.
         continue
       }
-      if (evt.type === 'eco.zoon.interrupt') {
+      if (evt.type === 'dev.zooid.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
@@ -279,7 +575,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         }
         // 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})`)
+          console.warn(`[matrix] dev.zooid.interrupt missing session_id (event_id=${evt.event_id})`)
           continue
         }
         const ctx = sessions.get(content.session_id)
@@ -295,7 +591,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         })
         continue
       }
-      if (evt.type === 'eco.zoon.approval_response') {
+      if (evt.type === 'dev.zooid.approval_response') {
         const content = (evt.content ?? {}) as {
           approval_id?: string
           session_id?: string
@@ -315,6 +611,29 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         continue
       }
       logInbound(evt)
+
+      // Capture media events in the pending store; never route them to agents.
+      if (
+        evt.type === 'm.room.message' &&
+        isMediaMsgtype(evt.content?.msgtype) &&
+        evt.room_id &&
+        evt.event_id &&
+        evt.sender &&
+        evt.content?.url &&
+        !bindings.some((b) => b.userId === evt.sender)
+      ) {
+        pendingMedia.add(evt.room_id, inboundThreadRoot(evt), {
+          eventId: evt.event_id,
+          sender: evt.sender,
+          msgtype: evt.content.msgtype as string,
+          body: (evt.content.body as string | undefined) ?? '',
+          filename: evt.content.filename as string | undefined,
+          url: evt.content.url as string,
+          info: evt.content.info as PendingMediaItem['info'],
+        })
+        continue
+      }
+
       // 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
@@ -396,10 +715,10 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
               .sendCustomEvent({
                 roomId: evt.room_id,
                 asUserId: a.userId,
-                eventType: 'eco.zoon.error',
+                eventType: 'dev.zooid.error',
                 content: body,
               })
-              .catch((e) => console.warn(`[matrix:${a.name}] eco.zoon.error send failed:`, e))
+              .catch((e) => console.warn(`[matrix:${a.name}] dev.zooid.error send failed:`, e))
           })
       }
     }
@@ -437,6 +756,15 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     sessions.set(sessionId, { agent, roomId: evt.room_id, threadRoot })
     buffers.set(sessionId, '')
     bufferMessageIds.delete(sessionId)
+    flushedCounts.set(sessionId, 0)
+    // Commands the shim advertised during ensureSession (session load/new)
+    // arrived before the ctx above existed and were stashed — replay the latest
+    // now that the session is fully registered, so the palette actually fills.
+    const stashedCommands = pendingCommands.get(sessionId)
+    if (stashedCommands) {
+      pendingCommands.delete(sessionId)
+      void agents.onEvent?.(agent.name, stashedCommands)
+    }
 
     const roomId = evt.room_id
     const TYPING_TTL_MS = 30_000
@@ -461,10 +789,33 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     try {
       const rawBody = evt.content?.body ?? ''
       const promptText = stripMention(rawBody, agent.userId)
+
+      // Drain pending media for this sender+thread and prepend as ACP content blocks.
+      const pendingItems = pendingMedia.drain(
+        evt.room_id,
+        inboundThreadRoot(evt),
+        evt.sender ?? '',
+      )
+      const { blocks, pathLines } = await buildMediaBlocks(pendingItems, {
+        agent,
+        media: mediaClient,
+        writeAttachmentFn,
+        onError: (item, err) => {
+          console.warn(`[matrix:${agent.name}] media_failed for ${item.body}:`, err)
+          void sendMediaError(
+            { agent, roomId: evt.room_id!, threadRoot },
+            err,
+            `Could not process attachment: ${item.body}`,
+            client,
+          )
+        },
+      })
+
+      const fullPromptText = [promptText, ...pathLines].filter(Boolean).join('\n')
       await agents.prompt(agent.name, {
         threadId: sessionKey,
         channelId: evt.room_id,
-        content: [{ type: 'text', text: promptText }],
+        content: [...blocks, { type: 'text', text: fullPromptText }],
       })
       // Drain: the prompt promise resolves on the stopReason response, but
       // trailing chunks may still arrive (see DRAIN_* above). Wait until the
@@ -481,44 +832,23 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       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
+        // Stop when the buffer is quiet (unchanged) and either it holds the
+        // final message to flush, or we already flushed a message this turn
+        // (so an empty, quiet buffer means the turn is genuinely done — the
+        // last message was flushed mid-stream). An unchanged *empty* buffer
+        // with nothing flushed yet means the stream hasn't started; keep
+        // waiting up to drainMaxMs.
+        if (next === drained && (next.length > 0 || (flushedCounts.get(sessionId) ?? 0) > 0))
+          break
         drained = next
       }
-      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 {
+      // Flush the final assistant message — the one with no following messageId
+      // change or out-of-band event to have triggered an earlier flush.
+      flushBuffer(sessionId)
+      // Wait for every queued send (mid-turn flushes, tool/plan events, final
+      // flush) to settle before tearing the session down.
+      await (sendQueue.get(sessionId) ?? Promise.resolve())
+      if ((flushedCounts.get(sessionId) ?? 0) === 0) {
         console.warn(
           `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${evt.room_id}`,
         )
@@ -529,6 +859,8 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       await safePresence('online')
       buffers.delete(sessionId)
       bufferMessageIds.delete(sessionId)
+      flushedCounts.delete(sessionId)
+      sendQueue.delete(sessionId)
     }
   }
 

package/src/workforce-publisher.test.ts

@@ -36,7 +36,7 @@ describe('buildWorkforceRoster', () => {
 })
 
 describe('publishWorkforce', () => {
-  it('PUTs eco.zoon.workforce state event on the configured space', async () => {
+  it('PUTs dev.zooid.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',
@@ -54,7 +54,7 @@ describe('publishWorkforce', () => {
     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',
+      'https://hs.zoon.local/_matrix/client/v3/rooms/!space%3Azoon.local/state/dev.zooid.workforce/?user_id=%40zooid%3Azoon.local',
     )
     expect(init?.method).toBe('PUT')
     expect(init?.headers).toMatchObject({ Authorization: 'Bearer as-tok' })

package/src/workforce-publisher.ts

@@ -28,7 +28,7 @@ export async function publishWorkforce(opts: PublishOpts): Promise<void> {
   await opts.client.sendStateEvent({
     roomId: opts.spaceRoomId,
     asUserId: opts.asUserId,
-    eventType: 'eco.zoon.workforce',
+    eventType: 'dev.zooid.workforce',
     stateKey: '',
     content: buildWorkforceRoster(opts.agents) as unknown as Record<string, unknown>,
   })