@zooid/transport-matrix 0.8.0 → 0.9.0

package/src/transport.ts

@@ -6,7 +6,7 @@ import { MatrixClient } from './matrix-client.js'
 import { BotPool } from './bot-pool.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 {
@@ -52,6 +52,10 @@ export interface CreateMatrixTransportOptions {
   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 {
@@ -67,9 +71,12 @@ 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 }
   }
 }
@@ -173,7 +180,7 @@ async function sendMediaError(
     .sendCustomEvent({
       roomId: ctx.roomId,
       asUserId: ctx.agent.userId,
-      eventType: 'eco.zoon.error',
+      eventType: 'dev.zooid.error',
       content: toErrorBody(
         {
           kind: 'error' as const,
@@ -187,7 +194,7 @@ async function sendMediaError(
         ctx.threadRoot,
       ),
     })
-    .catch((e) => console.warn(`[matrix:${ctx.agent.name}] eco.zoon.error send failed:`, e))
+    .catch((e) => console.warn(`[matrix:${ctx.agent.name}] dev.zooid.error send failed:`, e))
 }
 const SEEN_EVENT_CAP = 5_000
 
@@ -216,13 +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
@@ -240,38 +254,113 @@ 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; 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' &&
@@ -310,18 +399,27 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       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 {
@@ -362,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,
     })
   })
@@ -404,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
@@ -413,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)
         }
@@ -426,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
@@ -456,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)
@@ -472,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
@@ -596,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))
           })
       }
     }
@@ -637,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
@@ -704,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}`,
         )
@@ -752,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>,
   })