@zooid/transport-matrix 0.8.0 → 0.9.1

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 {
@@ -19,6 +19,7 @@ import {
   INLINE_IMAGE_MIMES,
 } from './media-client.js'
 import { writeAttachment } from './attachments.js'
+import { SyncLoop } from './sync-loop.js'
 
 export interface MediaClientLike {
   download(input: {
@@ -52,6 +53,20 @@ 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
+  /**
+   * Transport ingestion mode.
+   * - `'appservice'` (default): Tuwunel pushes events to the HTTP transaction endpoint.
+   * - `'client'`: daemon polls via impersonated `/sync` per agent (pull mode).
+   */
+  mode?: 'appservice' | 'client'
+  /** Pull mode: load the persisted `since` cursor for an agent user ID. */
+  loadSince?: (agentUserId: string) => string | null
+  /** Pull mode: persist the `since` cursor after each sync poll. */
+  saveSince?: (agentUserId: string, since: string) => void
 }
 
 interface SessionContext {
@@ -67,9 +82,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 +191,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 +205,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 +234,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, mode = 'appservice' } = 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
@@ -234,44 +259,123 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
   const sendQueue = new Map<string, Promise<void>>()
   // Thread participation index: keyed by thread root event_id.
   const threadStates = new Map<string, ThreadState>()
-  // Drop events older than this — Tuwunel may replay a backlog after the
-  // daemon was offline, and we don't want yesterday's "@docs hi" to fire now.
-  const cutoffTs = Date.now() - STARTUP_GRACE_MS
+  // Drop events older than this — in push (appservice) mode Tuwunel may replay
+  // a backlog after the daemon was offline, and we don't want yesterday's
+  // "@docs hi" to fire now. In pull (client) mode the persisted `since` cursor
+  // is the authoritative replay boundary (process everything after it — that's
+  // exactly the offline-resume feature), so the timestamp guard must NOT apply:
+  // the missed-while-offline mention is older than startup by design.
+  const cutoffTs = mode === 'client' ? Number.NEGATIVE_INFINITY : Date.now() - STARTUP_GRACE_MS
   // 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 +414,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,247 +475,272 @@ 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,
     })
   })
 
-  const app = new Hono()
-
-  function authOk(authHeader: string | undefined): boolean {
-    const h = authHeader ?? ''
-    if (!h.startsWith('Bearer ')) return false
-    const got = h.slice(7)
-    if (got.length !== hsToken.length) return false
-    return timingSafeEqual(Buffer.from(got), Buffer.from(hsToken))
-  }
-
-  app.put('/_matrix/app/v1/transactions/:txnId', async (c) => {
-    if (!authOk(c.req.header('authorization'))) {
-      return c.json({ errcode: 'M_FORBIDDEN' }, 403)
-    }
-    const body = (await c.req.json().catch(() => ({}))) as { events?: MatrixEvent[] }
-    for (const evt of body.events ?? []) {
-      if (evt.event_id) {
-        if (seenEventIds.has(evt.event_id)) {
-          continue
-        }
-        seenEventIds.add(evt.event_id)
-        if (seenEventIds.size > SEEN_EVENT_CAP) {
-          const first = seenEventIds.values().next().value
-          if (first !== undefined) seenEventIds.delete(first)
-        }
+  async function handleInboundEvent(evt: MatrixEvent): Promise<void> {
+    if (evt.event_id) {
+      if (seenEventIds.has(evt.event_id)) {
+        return
       }
+      seenEventIds.add(evt.event_id)
+      if (seenEventIds.size > SEEN_EVENT_CAP) {
+        const first = seenEventIds.values().next().value
+        if (first !== undefined) seenEventIds.delete(first)
+      }
+    }
+    if (
+      evt.origin_server_ts !== undefined &&
+      evt.origin_server_ts < cutoffTs &&
+      evt.type === 'm.room.message'
+    ) {
+      console.log(
+        `[matrix] dropping stale message event ${evt.event_id} ` +
+          `(ts=${evt.origin_server_ts}, daemon started at ${cutoffTs + STARTUP_GRACE_MS})`,
+      )
+      return
+    }
+    if (evt.type === 'm.room.member' && evt.content?.membership === 'invite') {
+      const target = evt.state_key
+      const inviter = evt.sender
       if (
-        evt.origin_server_ts !== undefined &&
-        evt.origin_server_ts < cutoffTs &&
-        evt.type === 'm.room.message'
+        target &&
+        evt.room_id &&
+        ourBotUserIds.has(target) &&
+        (!inviter || !ourBotUserIds.has(inviter))
       ) {
         console.log(
-          `[matrix] dropping stale message event ${evt.event_id} ` +
-            `(ts=${evt.origin_server_ts}, daemon started at ${cutoffTs + STARTUP_GRACE_MS})`,
+          `[matrix] declining ad-hoc invite for ${target} in ${evt.room_id} ` +
+            `from ${inviter ?? 'unknown'}`,
         )
-        continue
+        await client
+          .leaveRoom(evt.room_id, target, { reason: DECLINE_REASON })
+          .catch((err) =>
+            console.warn(`[matrix] leaveRoom(${evt.room_id}, ${target}) failed:`, err),
+          )
       }
-      if (evt.type === 'eco.zoon.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
-          | { rel_type?: string; event_id?: string }
-          | undefined
-        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')
-          continue
-        }
-        console.log(`[matrix] inbound eco.zoon.session_reset in ${evt.room_id} thread=${threadRoot}`)
-        for (const a of bindings) {
-          agents.endSession(a.name, threadRoot)
-        }
-        // NB: keep threadStates intact. Per ZOD039 § /clear, only the agent's
-        // session memory is wiped — thread-routing state (participants /
-        // root-mentions) must survive so the next bare reply still routes to
-        // the most-recently-posting agent under the same sessionKey.
-        continue
+      return
+    }
+    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
+        | { rel_type?: string; event_id?: string }
+        | undefined
+      const threadRoot =
+        relates?.rel_type === 'm.thread' && relates.event_id ? relates.event_id : undefined
+      if (!threadRoot) {
+        console.log('[matrix] dropping dev.zooid.session_reset without thread relation')
+        return
       }
-      if (evt.type === 'eco.zoon.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
-        // session whose threadRoot matches.
-        const relates = evt.content?.['m.relates_to'] as
-          | { rel_type?: string; event_id?: string }
-          | undefined
-        const threadRoot =
-          relates?.rel_type === 'm.thread' && relates.event_id ? relates.event_id : undefined
-        if (threadRoot) {
-          const targets: Array<{ sessionId: string; agent: string }> = []
-          for (const [sessionId, ctx] of sessions) {
-            if (ctx.threadRoot === threadRoot) {
-              targets.push({ sessionId, agent: ctx.agent.name })
-            }
-          }
-          for (const t of targets) {
-            console.log(
-              `[matrix] interrupt session=${t.sessionId} agent=${t.agent} thread=${threadRoot}` +
-                (content.reason ? ` reason=${content.reason}` : ''),
-            )
-            await agents.cancelSession(t.agent, t.sessionId).catch((err) => {
-              console.error(`[matrix] cancelSession(${t.agent}, ${t.sessionId}) failed:`, err)
-            })
+      console.log(`[matrix] inbound dev.zooid.session_reset in ${evt.room_id} thread=${threadRoot}`)
+      for (const a of bindings) {
+        agents.endSession(a.name, threadRoot)
+      }
+      // NB: keep threadStates intact. Per ZOD039 § /clear, only the agent's
+      // session memory is wiped — thread-routing state (participants /
+      // root-mentions) must survive so the next bare reply still routes to
+      // the most-recently-posting agent under the same sessionKey.
+      return
+    }
+    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
+      // session whose threadRoot matches.
+      const relates = evt.content?.['m.relates_to'] as
+        | { rel_type?: string; event_id?: string }
+        | undefined
+      const threadRoot =
+        relates?.rel_type === 'm.thread' && relates.event_id ? relates.event_id : undefined
+      if (threadRoot) {
+        const targets: Array<{ sessionId: string; agent: string }> = []
+        for (const [sessionId, ctx] of sessions) {
+          if (ctx.threadRoot === threadRoot) {
+            targets.push({ sessionId, agent: ctx.agent.name })
           }
-          continue
-        }
-        // 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})`)
-          continue
         }
-        const ctx = sessions.get(content.session_id)
-        if (!ctx) {
-          continue
+        for (const t of targets) {
+          console.log(
+            `[matrix] interrupt session=${t.sessionId} agent=${t.agent} thread=${threadRoot}` +
+              (content.reason ? ` reason=${content.reason}` : ''),
+          )
+          await agents.cancelSession(t.agent, t.sessionId).catch((err) => {
+            console.error(`[matrix] cancelSession(${t.agent}, ${t.sessionId}) failed:`, err)
+          })
         }
-        console.log(
-          `[matrix] interrupt session=${content.session_id} agent=${ctx.agent.name}` +
-            (content.reason ? ` reason=${content.reason}` : ''),
-        )
-        await agents.cancelSession(ctx.agent.name, content.session_id).catch((err) => {
-          console.error(`[matrix] cancelSession(${ctx.agent.name}, ${content.session_id}) failed:`, err)
-        })
-        continue
+        return
       }
-      if (evt.type === 'eco.zoon.approval_response') {
-        const content = (evt.content ?? {}) as {
-          approval_id?: string
-          session_id?: string
-          decision?: string
-          option_id?: string
-        }
-        if (!content.session_id || !content.approval_id || !content.decision) continue
-        const decision = content.option_id
-          ? { decision: content.decision, optionId: content.option_id }
-          : { decision: content.decision }
-        const ok = approvals.resolve(
-          content.session_id,
-          content.approval_id,
-          decision as never,
-        )
-        if (!ok) console.warn(`[matrix] unknown approval ${content.approval_id}`)
-        continue
+      // Legacy form: explicit session_id in content.
+      if (!content.session_id) {
+        console.warn(`[matrix] dev.zooid.interrupt missing session_id (event_id=${evt.event_id})`)
+        return
       }
-      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
+      const ctx = sessions.get(content.session_id)
+      if (!ctx) {
+        return
       }
-
-      // 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
-      // Self-heal: if this is a thread reply but we have no in-memory state
-      // for the root (e.g. daemon was just restarted), reconstruct it by
-      // fetching the thread root + relations from the server.
-      const inboundRel = inboundThreadRoot(evt)
-      if (
-        evt.type === 'm.room.message' &&
-        inboundRel &&
-        !threadStates.has(inboundRel) &&
-        evt.room_id
-      ) {
-        try {
-          const rebuilt = await rebuildThreadState(client, evt.room_id, inboundRel, bindings)
-          threadStates.set(inboundRel, rebuilt)
-          console.log(
-            `[matrix] rebuilt threadState for ${inboundRel}: participants=${rebuilt.participants.join(',')} rootMentions=${rebuilt.rootMentions.join(',')}`,
-          )
-        } catch (err) {
-          console.warn(`[matrix] failed to rebuild threadState for ${inboundRel}:`, err)
-        }
+      console.log(
+        `[matrix] interrupt session=${content.session_id} agent=${ctx.agent.name}` +
+          (content.reason ? ` reason=${content.reason}` : ''),
+      )
+      await agents.cancelSession(ctx.agent.name, content.session_id).catch((err) => {
+        console.error(`[matrix] cancelSession(${ctx.agent.name}, ${content.session_id}) failed:`, err)
+      })
+      return
+    }
+    if (evt.type === 'dev.zooid.approval_response') {
+      const content = (evt.content ?? {}) as {
+        approval_id?: string
+        session_id?: string
+        decision?: string
+        option_id?: string
       }
-      const matches = route(evt, bindings, threadStates)
-      // Suppress the no-match warning for events sent by our own bots.
-      const senderIsBot = bindings.some((b) => b.userId === evt.sender)
-      if (evt.type === 'm.room.message' && matches.length === 0 && !senderIsBot) {
-        console.warn(
-          `[matrix] no agent matched message in ${evt.room_id} from ${evt.sender}` +
-            ` (bindings: ${bindings.map((b) => `${b.name}@${b.userId}[${b.trigger}]`).join(', ')})`,
+      if (!content.session_id || !content.approval_id || !content.decision) return
+      const decision = content.option_id
+        ? { decision: content.decision, optionId: content.option_id }
+        : { decision: content.decision }
+      const ok = approvals.resolve(
+        content.session_id,
+        content.approval_id,
+        decision as never,
+      )
+      if (!ok) console.warn(`[matrix] unknown approval ${content.approval_id}`)
+      return
+    }
+    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'],
+      })
+      return
+    }
+
+    // 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
+    // Self-heal: if this is a thread reply but we have no in-memory state
+    // for the root (e.g. daemon was just restarted), reconstruct it by
+    // fetching the thread root + relations from the server.
+    const inboundRel = inboundThreadRoot(evt)
+    if (
+      evt.type === 'm.room.message' &&
+      inboundRel &&
+      !threadStates.has(inboundRel) &&
+      evt.room_id
+    ) {
+      try {
+        const rebuilt = await rebuildThreadState(client, evt.room_id, inboundRel, bindings)
+        threadStates.set(inboundRel, rebuilt)
+        console.log(
+          `[matrix] rebuilt threadState for ${inboundRel}: participants=${rebuilt.participants.join(',')} rootMentions=${rebuilt.rootMentions.join(',')}`,
         )
+      } catch (err) {
+        console.warn(`[matrix] failed to rebuild threadState for ${inboundRel}:`, err)
       }
-      // Seed thread state for any agent mentions in this event.
-      if (matches.length > 0 && promotedRoot) {
-        let st = threadStates.get(promotedRoot)
-        if (!st) {
-          st = { participants: [], rootMentions: [] }
-          threadStates.set(promotedRoot, st)
-        }
-        const msgMentions = new Set(extractMentions(evt as never))
-        for (const a of bindings) {
-          if (msgMentions.has(a.userId) && !st.rootMentions.includes(a.name)) {
-            st.rootMentions.push(a.name)
-          }
-        }
+    }
+    const matches = route(evt, bindings, threadStates)
+    // Suppress the no-match warning for events sent by our own bots.
+    const senderIsBot = bindings.some((b) => b.userId === evt.sender)
+    if (evt.type === 'm.room.message' && matches.length === 0 && !senderIsBot) {
+      console.warn(
+        `[matrix] no agent matched message in ${evt.room_id} from ${evt.sender}` +
+          ` (bindings: ${bindings.map((b) => `${b.name}@${b.userId}[${b.trigger}]`).join(', ')})`,
+      )
+    }
+    // Seed thread state for any agent mentions in this event.
+    if (matches.length > 0 && promotedRoot) {
+      let st = threadStates.get(promotedRoot)
+      if (!st) {
+        st = { participants: [], rootMentions: [] }
+        threadStates.set(promotedRoot, st)
       }
-      for (const a of matches) {
-        console.log(`[matrix] → ${a.name} (${a.userId})`)
-        void runTurn(a, evt)
-          .then(() => {
-            if (!promotedRoot) return
-            let st = threadStates.get(promotedRoot)
-            if (!st) {
-              st = { participants: [], rootMentions: [] }
-              threadStates.set(promotedRoot, st)
-            }
-            if (st.participants.at(-1) !== a.name) st.participants.push(a.name)
-          })
-          .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))
-          })
+      const msgMentions = new Set(extractMentions(evt as never))
+      for (const a of bindings) {
+        if (msgMentions.has(a.userId) && !st.rootMentions.includes(a.name)) {
+          st.rootMentions.push(a.name)
+        }
       }
     }
+    for (const a of matches) {
+      console.log(`[matrix] → ${a.name} (${a.userId})`)
+      void runTurn(a, evt)
+        .then(() => {
+          if (!promotedRoot) return
+          let st = threadStates.get(promotedRoot)
+          if (!st) {
+            st = { participants: [], rootMentions: [] }
+            threadStates.set(promotedRoot, st)
+          }
+          if (st.participants.at(-1) !== a.name) st.participants.push(a.name)
+        })
+        .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: 'dev.zooid.error',
+              content: body,
+            })
+            .catch((e) => console.warn(`[matrix:${a.name}] dev.zooid.error send failed:`, e))
+        })
+    }
+  }
+
+  const app = new Hono()
+
+  function authOk(authHeader: string | undefined): boolean {
+    const h = authHeader ?? ''
+    if (!h.startsWith('Bearer ')) return false
+    const got = h.slice(7)
+    if (got.length !== hsToken.length) return false
+    return timingSafeEqual(Buffer.from(got), Buffer.from(hsToken))
+  }
+
+  app.put('/_matrix/app/v1/transactions/:txnId', async (c) => {
+    if (!authOk(c.req.header('authorization'))) {
+      return c.json({ errcode: 'M_FORBIDDEN' }, 403)
+    }
+    const body = (await c.req.json().catch(() => ({}))) as { events?: MatrixEvent[] }
+    for (const evt of body.events ?? []) {
+      await handleInboundEvent(evt)
+    }
     return c.json({})
   })
 
@@ -637,6 +775,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 +851,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,11 +878,28 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       await safePresence('online')
       buffers.delete(sessionId)
       bufferMessageIds.delete(sessionId)
+      flushedCounts.delete(sessionId)
+      sendQueue.delete(sessionId)
     }
   }
 
+  const syncLoops: SyncLoop[] | undefined =
+    mode === 'client'
+      ? bindings.map(
+          (b) =>
+            new SyncLoop({
+              client: client as never,
+              asUserId: b.userId,
+              loadSince: () => opts.loadSince?.(b.userId) ?? null,
+              saveSince: (since) => opts.saveSince?.(b.userId, since),
+              onEvent: (evt) => handleInboundEvent(evt as MatrixEvent),
+            }),
+        )
+      : undefined
+
   return {
     app,
+    syncLoops,
     bootstrap: async (
       bootstrapOpts: {
         spaceRoomId?: string