@zooid/transport-matrix 0.7.4 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/transport-matrix",
-  "version": "0.7.4",
+  "version": "0.9.0",
   "description": "Matrix Application Service transport for zooid. Routes inbound Matrix messages to ACP agents and posts replies plus approval custom events back to threads.",
   "type": "module",
   "license": "MIT",
@@ -28,8 +28,8 @@
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "yaml": "^2.5.0",
-    "@zooid/core": "^0.7.4",
-    "@zooid/acp-client": "^0.7.4"
+    "@zooid/core": "^0.9.0",
+    "@zooid/acp-client": "^0.9.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.0",

package/src/attachments.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeAttachment } from './attachments.js'
+
+describe('writeAttachment', () => {
+  it('writes under .zooid/attachments/<event-id>/<filename> and returns both path views', () => {
+    const ws = mkdtempSync(join(tmpdir(), 'zooid-att-'))
+    try {
+      const out = writeAttachment({
+        workspaceDir: ws,
+        agentWorkspacePath: '/workspace',
+        eventId: '$abc123:localhost',
+        filename: 'report.pdf',
+        data: Buffer.from('hello'),
+      })
+      expect(out.hostPath).toBe(join(ws, '.zooid', 'attachments', 'abc123localhost', 'report.pdf'))
+      expect(out.agentPath).toBe('/workspace/.zooid/attachments/abc123localhost/report.pdf')
+      expect(readFileSync(out.hostPath, 'utf8')).toBe('hello')
+    } finally {
+      rmSync(ws, { recursive: true, force: true })
+    }
+  })
+
+  it('sanitizes path-traversal and separator characters in filenames', () => {
+    const ws = mkdtempSync(join(tmpdir(), 'zooid-att-'))
+    try {
+      const out = writeAttachment({
+        workspaceDir: ws,
+        agentWorkspacePath: '/workspace',
+        eventId: '$e1',
+        filename: '../../etc/passwd',
+        data: Buffer.from('x'),
+      })
+      expect(out.hostPath.startsWith(join(ws, '.zooid', 'attachments'))).toBe(true)
+      expect(out.hostPath).not.toContain('..')
+    } finally {
+      rmSync(ws, { recursive: true, force: true })
+    }
+  })
+
+  it('falls back to a default filename when body is empty', () => {
+    const ws = mkdtempSync(join(tmpdir(), 'zooid-att-'))
+    try {
+      const out = writeAttachment({
+        workspaceDir: ws,
+        agentWorkspacePath: '/workspace',
+        eventId: '$e2',
+        filename: '',
+        data: Buffer.from('x'),
+      })
+      expect(out.agentPath).toMatch(/\/file$/)
+    } finally {
+      rmSync(ws, { recursive: true, force: true })
+    }
+  })
+})

package/src/attachments.ts

@@ -0,0 +1,30 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { posix } from 'node:path'
+
+function sanitize(s: string, fallback: string): string {
+  const cleaned = s.replace(/[^A-Za-z0-9._-]/g, '').replace(/^\.+/, '')
+  return cleaned || fallback
+}
+
+export interface WriteAttachmentInput {
+  workspaceDir: string
+  agentWorkspacePath: string
+  eventId: string
+  filename: string
+  data: Uint8Array
+}
+
+export function writeAttachment(input: WriteAttachmentInput): {
+  hostPath: string
+  agentPath: string
+} {
+  const dir = sanitize(input.eventId, 'event')
+  const name = sanitize(input.filename, 'file')
+  const hostDir = join(input.workspaceDir, '.zooid', 'attachments', dir)
+  mkdirSync(hostDir, { recursive: true })
+  const hostPath = join(hostDir, name)
+  writeFileSync(hostPath, input.data)
+  const agentPath = posix.join(input.agentWorkspacePath, '.zooid', 'attachments', dir, name)
+  return { hostPath, agentPath }
+}

package/src/bot-pool.ts

@@ -48,7 +48,7 @@ export class BotPool {
         console.warn(`[matrix] setDisplayName(${a.userId}) failed: ${(err as Error).message}`)
       }
       // Make each agent a member of the workforce space. That covers two
-      // things at once: the eco.zoon.workforce roster is now backed by
+      // things at once: the dev.zooid.workforce roster is now backed by
       // actual space membership (so the Zoon client's member autocomplete
       // works across rooms), and every restricted child room's allow rule
       // is satisfied without per-room invites.

package/src/context-provider.test.ts

@@ -314,4 +314,37 @@ describe('MatrixContextProvider', () => {
     const info = await provider.getChannelInfo('!room:hs')
     expect(info.name).toBe('!room:hs')
   })
+
+  it('renders media events as placeholders instead of skipping them', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$img',
+            sender: '@alice:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.image', body: 'dog.jpg', url: 'mxc://hs/a' },
+          },
+          {
+            event_id: '$file',
+            sender: '@alice:hs',
+            origin_server_ts: 2000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.file', body: 'report.pdf', url: 'mxc://hs/b' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const page = await provider.getRoomHistory('!room:hs', {})
+    const byId = new Map(page.messages.map((m) => [m.id, m]))
+    expect(byId.get('$img')?.text).toBe('[image: dog.jpg]')
+    expect(byId.get('$file')?.text).toBe('[file: report.pdf]')
+  })
 })

package/src/context-provider.ts

@@ -43,7 +43,7 @@ export class MatrixContextProvider implements TransportContextProvider {
 
   async getRoomHistory(channelId: string, hopts: HistoryOptions): Promise<HistoryPage> {
     // Server-side filter: only `m.room.message` events. Without this we'd
-    // burn the page budget on reactions, `eco.zoon.*` custom events, typing
+    // burn the page budget on reactions, `dev.zooid.*` custom events, typing
     // notifications, etc., and routinely return empty pages with a stale
     // `has_more` cursor.
     const { chunk, end } = await this.opts.client.fetchRoomMessages({
@@ -147,15 +147,33 @@ export class MatrixContextProvider implements TransportContextProvider {
 
   private toMessage(ev: MatrixMessageEvent): Message | null {
     if (ev.type !== 'm.room.message') return null
-    if (ev.content?.msgtype !== 'm.text' || typeof ev.content.body !== 'string') return null
+    const msgtype = ev.content?.msgtype
+    const body = ev.content?.body
     const agent = this.opts.agentBots.get(ev.sender)
-    const relatesTo = ev.content['m.relates_to']
+    const relatesTo = ev.content?.['m.relates_to']
     const threadId =
       relatesTo?.rel_type === 'm.thread' && relatesTo.event_id ? relatesTo.event_id : undefined
+
+    // Media events render as context placeholders
+    if (msgtype === 'm.image' || msgtype === 'm.file' || msgtype === 'm.video' || msgtype === 'm.audio') {
+      const kind = msgtype.slice(2) // 'image', 'file', 'video', 'audio'
+      const name = typeof body === 'string' && body ? body : 'untitled'
+      return {
+        id: ev.event_id,
+        sender: ev.sender,
+        text: `[${kind}: ${name}]`,
+        timestamp: new Date(ev.origin_server_ts).toISOString(),
+        is_agent: agent !== undefined,
+        ...(agent !== undefined ? { agent_name: agent } : {}),
+        ...(threadId !== undefined ? { thread_id: threadId } : {}),
+      }
+    }
+
+    if (msgtype !== 'm.text' || typeof body !== 'string') return null
     return {
       id: ev.event_id,
       sender: ev.sender,
-      text: ev.content.body,
+      text: body,
       timestamp: new Date(ev.origin_server_ts).toISOString(),
       is_agent: agent !== undefined,
       ...(agent !== undefined ? { agent_name: agent } : {}),

package/src/event-encoders.test.ts

@@ -9,6 +9,7 @@ import {
   toUpdateBody,
   toPlanBody,
   toErrorBody,
+  toAvailableCommandsBody,
 } from './event-encoders.js'
 
 describe('toToolCallBody', () => {
@@ -124,6 +125,27 @@ describe('toPlanBody', () => {
   })
 })
 
+describe('toAvailableCommandsBody', () => {
+  it('encodes available_commands into the body ZNC021 decodes', () => {
+    expect(
+      toAvailableCommandsBody({
+        type: 'available_commands',
+        sessionId: 's-1',
+        commands: [
+          { name: 'plan', description: 'Switch to plan mode' },
+          { name: 'compact', description: 'Compact the context' },
+        ],
+      }),
+    ).toEqual({
+      session_id: 's-1',
+      available_commands: [
+        { name: 'plan', description: 'Switch to plan mode' },
+        { name: 'compact', description: 'Compact the context' },
+      ],
+    })
+  })
+})
+
 describe('toErrorBody', () => {
   const threadRoot = '$root-event-id'
 

package/src/event-encoders.ts

@@ -1,4 +1,5 @@
 import type {
+  AvailableCommandsEvent,
   PlanEvent,
   TapEvent,
   ToolCallEvent,
@@ -66,6 +67,18 @@ export function toPlanBody(evt: PlanEvent): Record<string, unknown> {
   }
 }
 
+export function toAvailableCommandsBody(
+  evt: AvailableCommandsEvent,
+): Record<string, unknown> {
+  return {
+    session_id: evt.sessionId,
+    available_commands: evt.commands.map((c) => ({
+      name: c.name,
+      description: c.description,
+    })),
+  }
+}
+
 const RECOVERY_URLS: Partial<Record<string, string>> = {
   auth_missing: 'https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over',
   auth_invalid: 'https://zooid.dev/docs/guides/run-in-container#authentication-that-carries-over',

package/src/index.ts

@@ -6,11 +6,11 @@ export { renderRegistration } from './registration.js'
 export type { MatrixTransportConfig } from './registration.js'
 export { extractMentions } from './mentions.js'
 export type { MaybeMessage } from './mentions.js'
-export { route } from './router.js'
+export { route, isMediaMsgtype, MEDIA_MSGTYPES } from './router.js'
 export type { AgentBinding, RouteMatch } from './router.js'
 export { BotPool } from './bot-pool.js'
 export { createMatrixTransport } from './transport.js'
-export type { CreateMatrixTransportOptions } from './transport.js'
+export type { CreateMatrixTransportOptions, MediaClientLike } from './transport.js'
 export { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
 export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {
@@ -24,3 +24,9 @@ export type {
   PublisherHandle,
   StartOpts as StartWorkforcePublisherOpts,
 } from './workforce-publisher.js'
+export { MediaClient, parseMxcUri, MAX_INLINE_IMAGE_BYTES, INLINE_IMAGE_MIMES, MAX_DOWNLOAD_BYTES } from './media-client.js'
+export type { MediaClientOptions } from './media-client.js'
+export { PendingMediaStore, MAX_MEDIA_PER_TURN } from './pending-media.js'
+export type { PendingMediaItem } from './pending-media.js'
+export { writeAttachment } from './attachments.js'
+export type { WriteAttachmentInput } from './attachments.js'

package/src/matrix-client.test.ts

@@ -287,7 +287,7 @@ describe('MatrixClient', () => {
 
   it('sends a custom event type when content type is set', async () => {
     const fetch = fakeFetch(async ({ url, init }) => {
-      expect(url).toMatch(/\/send\/eco\.zoon\.approval_request\//)
+      expect(url).toMatch(/\/send\/dev\.zooid\.approval_request\//)
       const body = JSON.parse(init.body as string)
       expect(body.approval_id).toBe('a1')
       return new Response(JSON.stringify({ event_id: '$x' }), { status: 200 })
@@ -300,7 +300,7 @@ describe('MatrixClient', () => {
     await client.sendCustomEvent({
       roomId: '!r:example.com',
       asUserId: '@architect:example.com',
-      eventType: 'eco.zoon.approval_request',
+      eventType: 'dev.zooid.approval_request',
       content: { approval_id: 'a1', description: 'Run: git push' },
     })
   })
@@ -445,6 +445,39 @@ describe('MatrixClient.createRoom userPowerLevels', () => {
   })
 })
 
+describe('MatrixClient.leaveRoom', () => {
+  it('leaves (rejects) a room as the impersonated user, with a reason', async () => {
+    const fetch = fakeFetch(async ({ url, init }) => {
+      expect(url).toBe(
+        'https://hs.example.com/_matrix/client/v3/rooms/!r%3Aexample.com/leave' +
+          '?user_id=%40zooid%3Aexample.com',
+      )
+      expect(init.method).toBe('POST')
+      expect(JSON.parse(init.body as string)).toEqual({ reason: 'no thanks' })
+      return new Response('{}', { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.leaveRoom('!r:example.com', '@zooid:example.com', { reason: 'no thanks' })
+  })
+
+  it('sends an empty body when no reason is given', async () => {
+    const fetch = fakeFetch(async ({ init }) => {
+      expect(JSON.parse(init.body as string)).toEqual({})
+      return new Response('{}', { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.leaveRoom('!r:example.com', '@zooid:example.com')
+  })
+})
+
 describe('MatrixClient.createRoom restricted', () => {
   it('injects a restricted join rule referencing the space when restrictedToSpaceId is set', async () => {
     const fetch = fakeFetch(async ({ url, init }) => {

package/src/matrix-client.ts

@@ -222,6 +222,25 @@ export class MatrixClient {
     throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`)
   }
 
+  async leaveRoom(
+    roomId: string,
+    asUserId: string,
+    opts?: { reason?: string },
+  ): Promise<void> {
+    const url =
+      `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/leave` +
+      `?user_id=${encodeURIComponent(asUserId)}`
+    const r = await this.fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.asToken}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(opts?.reason ? { reason: opts.reason } : {}),
+    })
+    if (!r.ok) throw new Error(`leaveRoom(${roomId}, ${asUserId}) failed: ${r.status}`)
+  }
+
   async joinRoom(roomIdOrAlias: string, asUserId: string): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/join/${encodeURIComponent(roomIdOrAlias)}` +

package/src/media-client.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  MediaClient,
+  parseMxcUri,
+  MAX_INLINE_IMAGE_BYTES,
+  INLINE_IMAGE_MIMES,
+} from './media-client.js'
+
+const TINY_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  'base64',
+)
+
+function fakeFetch(response: Partial<Response> & { body?: Uint8Array; json?: unknown }) {
+  return vi.fn(async () => ({
+    ok: response.ok ?? true,
+    status: response.status ?? 200,
+    headers: new Headers(response.headers ?? { 'content-type': 'image/png' }),
+    arrayBuffer: async () => {
+      const buf = response.body ?? TINY_PNG
+      // Use byteOffset/byteLength so the slice covers exactly the bytes the Buffer references.
+      return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
+    },
+    json: async () => response.json ?? {},
+    text: async () => '',
+  })) as unknown as typeof fetch
+}
+
+describe('parseMxcUri', () => {
+  it('splits server name and media id', () => {
+    expect(parseMxcUri('mxc://localhost/AbCd1234')).toEqual({
+      serverName: 'localhost',
+      mediaId: 'AbCd1234',
+    })
+  })
+
+  it('returns null for non-mxc uris', () => {
+    expect(parseMxcUri('https://example.com/x.png')).toBeNull()
+    expect(parseMxcUri('mxc://missing-id')).toBeNull()
+  })
+})
+
+describe('MediaClient.download', () => {
+  it('GETs the authenticated v1 endpoint with AS token and user_id', async () => {
+    const f = fakeFetch({ body: TINY_PNG })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    const out = await media.download({ mxcUri: 'mxc://localhost/abc', asUserId: '@dev:localhost' })
+
+    const [url, init] = (f as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit]
+    expect(url).toBe(
+      'http://hs/_matrix/client/v1/media/download/localhost/abc?user_id=%40dev%3Alocalhost',
+    )
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer tok')
+    expect(Buffer.from(out.data).equals(TINY_PNG)).toBe(true)
+    expect(out.contentType).toBe('image/png')
+  })
+
+  it('rejects bodies larger than maxBytes', async () => {
+    const big = new Uint8Array(64)
+    const f = fakeFetch({ body: big })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    await expect(
+      media.download({ mxcUri: 'mxc://localhost/abc', asUserId: '@dev:localhost', maxBytes: 16 }),
+    ).rejects.toThrow(/too large/i)
+  })
+
+  it('throws on non-OK responses with status in the message', async () => {
+    const f = fakeFetch({ ok: false, status: 404 })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    await expect(
+      media.download({ mxcUri: 'mxc://localhost/gone', asUserId: '@dev:localhost' }),
+    ).rejects.toThrow(/404/)
+  })
+})
+
+describe('MediaClient.upload', () => {
+  it('POSTs raw bytes to /_matrix/media/v3/upload with filename and user_id', async () => {
+    const f = fakeFetch({ json: { content_uri: 'mxc://localhost/up1' } })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    const out = await media.upload({
+      data: TINY_PNG,
+      contentType: 'image/png',
+      filename: 'shot.png',
+      asUserId: '@dev:localhost',
+    })
+
+    const [url, init] = (f as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('http://hs/_matrix/media/v3/upload?filename=shot.png&user_id=%40dev%3Alocalhost')
+    expect(init.method).toBe('POST')
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe('image/png')
+    expect(out.content_uri).toBe('mxc://localhost/up1')
+  })
+})
+
+describe('inline routing constants', () => {
+  it('caps inline images at 0.5 MB and allowlists model-consumable mimes', () => {
+    expect(MAX_INLINE_IMAGE_BYTES).toBe(524_288)
+    expect(INLINE_IMAGE_MIMES).toContain('image/png')
+    expect(INLINE_IMAGE_MIMES).toContain('image/jpeg')
+    expect(INLINE_IMAGE_MIMES).not.toContain('image/svg+xml')
+  })
+})

package/src/media-client.ts

@@ -0,0 +1,69 @@
+/** Limits are routing policy, not enforcement — see ZOD057 (enforcement lives
+ *  in Tuwunel config + the Zoon composer). */
+export const MAX_INLINE_IMAGE_BYTES = 524_288
+export const INLINE_IMAGE_MIMES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
+export const MAX_DOWNLOAD_BYTES = 33_554_432
+
+export interface MediaClientOptions {
+  homeserver: string
+  asToken: string
+  fetch?: typeof globalThis.fetch
+}
+
+export function parseMxcUri(uri: string): { serverName: string; mediaId: string } | null {
+  const m = /^mxc:\/\/([^/]+)\/(.+)$/.exec(uri)
+  return m ? { serverName: m[1], mediaId: m[2] } : null
+}
+
+export class MediaClient {
+  private readonly homeserver: string
+  private readonly asToken: string
+  private readonly fetch: typeof globalThis.fetch
+
+  constructor(opts: MediaClientOptions) {
+    this.homeserver = opts.homeserver.replace(/\/$/, '')
+    this.asToken = opts.asToken
+    this.fetch = opts.fetch ?? globalThis.fetch
+  }
+
+  async download(input: {
+    mxcUri: string
+    asUserId: string
+    maxBytes?: number
+  }): Promise<{ data: Uint8Array; contentType: string }> {
+    const parsed = parseMxcUri(input.mxcUri)
+    if (!parsed) throw new Error(`not an mxc uri: ${input.mxcUri}`)
+    const url =
+      `${this.homeserver}/_matrix/client/v1/media/download/` +
+      `${encodeURIComponent(parsed.serverName)}/${encodeURIComponent(parsed.mediaId)}` +
+      `?user_id=${encodeURIComponent(input.asUserId)}`
+    const r = await this.fetch(url, {
+      headers: { Authorization: `Bearer ${this.asToken}` },
+    })
+    if (!r.ok) throw new Error(`media download failed: ${r.status}`)
+    const buf = new Uint8Array(await r.arrayBuffer())
+    const max = input.maxBytes ?? MAX_DOWNLOAD_BYTES
+    if (buf.byteLength > max) {
+      throw new Error(`media too large: ${buf.byteLength} > ${max}`)
+    }
+    return { data: buf, contentType: r.headers.get('content-type') ?? 'application/octet-stream' }
+  }
+
+  async upload(input: {
+    data: Uint8Array
+    contentType: string
+    filename?: string
+    asUserId: string
+  }): Promise<{ content_uri: string }> {
+    const params = new URLSearchParams()
+    if (input.filename) params.set('filename', input.filename)
+    params.set('user_id', input.asUserId)
+    const r = await this.fetch(`${this.homeserver}/_matrix/media/v3/upload?${params}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.asToken}`, 'Content-Type': input.contentType },
+      body: input.data,
+    })
+    if (!r.ok) throw new Error(`media upload failed: ${r.status}`)
+    return (await r.json()) as { content_uri: string }
+  }
+}

package/src/pending-media.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { PendingMediaStore, MAX_MEDIA_PER_TURN } from './pending-media.js'
+
+function item(over: Partial<{ eventId: string; sender: string; msgtype: string }> = {}) {
+  return {
+    eventId: over.eventId ?? '$m1',
+    sender: over.sender ?? '@alice:localhost',
+    msgtype: over.msgtype ?? 'm.image',
+    body: 'dog.jpg',
+    filename: 'dog.jpg',
+    url: 'mxc://localhost/abc',
+    info: { mimetype: 'image/jpeg', size: 1000 },
+  }
+}
+
+describe('PendingMediaStore', () => {
+  it('drains items for the same room+thread+sender and clears them', () => {
+    const s = new PendingMediaStore()
+    s.add('!r:hs', '$root', item({ eventId: '$m1' }))
+    s.add('!r:hs', '$root', item({ eventId: '$m2' }))
+    const drained = s.drain('!r:hs', '$root', '@alice:localhost')
+    expect(drained.map((i) => i.eventId)).toEqual(['$m1', '$m2'])
+    expect(s.drain('!r:hs', '$root', '@alice:localhost')).toEqual([])
+  })
+
+  it('does not leak across threads, rooms, or senders', () => {
+    const s = new PendingMediaStore()
+    s.add('!r:hs', '$rootA', item())
+    expect(s.drain('!r:hs', '$rootB', '@alice:localhost')).toEqual([])
+    expect(s.drain('!other:hs', '$rootA', '@alice:localhost')).toEqual([])
+    expect(s.drain('!r:hs', '$rootA', '@bob:localhost')).toEqual([])
+    // alice's item is still there after bob's miss
+    expect(s.drain('!r:hs', '$rootA', '@alice:localhost')).toHaveLength(1)
+  })
+
+  it('caps the queue at MAX_MEDIA_PER_TURN, dropping oldest first', () => {
+    const s = new PendingMediaStore()
+    for (let i = 0; i < MAX_MEDIA_PER_TURN + 3; i++) {
+      s.add('!r:hs', '$root', item({ eventId: `$m${i}` }))
+    }
+    const drained = s.drain('!r:hs', '$root', '@alice:localhost')
+    expect(drained).toHaveLength(MAX_MEDIA_PER_TURN)
+    expect(drained[0].eventId).toBe('$m3') // 0,1,2 dropped
+  })
+
+  it('uses a room-level key when the media event is unthreaded', () => {
+    const s = new PendingMediaStore()
+    s.add('!r:hs', undefined, item())
+    expect(s.drain('!r:hs', undefined, '@alice:localhost')).toHaveLength(1)
+  })
+})

package/src/pending-media.ts

@@ -0,0 +1,37 @@
+export const MAX_MEDIA_PER_TURN = 8
+
+export interface PendingMediaItem {
+  eventId: string
+  sender: string
+  msgtype: string
+  body: string
+  filename?: string
+  url: string
+  info?: { mimetype?: string; size?: number; w?: number; h?: number }
+}
+
+export class PendingMediaStore {
+  private readonly queues = new Map<string, PendingMediaItem[]>()
+
+  private key(roomId: string, threadKey: string | undefined): string {
+    return `${roomId} ${threadKey ?? 'main'}`
+  }
+
+  add(roomId: string, threadKey: string | undefined, item: PendingMediaItem): void {
+    const k = this.key(roomId, threadKey)
+    const q = this.queues.get(k) ?? []
+    q.push(item)
+    while (q.length > MAX_MEDIA_PER_TURN) q.shift()
+    this.queues.set(k, q)
+  }
+
+  drain(roomId: string, threadKey: string | undefined, sender: string): PendingMediaItem[] {
+    const k = this.key(roomId, threadKey)
+    const q = this.queues.get(k) ?? []
+    const mine = q.filter((i) => i.sender === sender)
+    const rest = q.filter((i) => i.sender !== sender)
+    if (rest.length) this.queues.set(k, rest)
+    else this.queues.delete(k)
+    return mine
+  }
+}

package/src/router.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { route, type AgentBinding } from './router.js'
+import { route, isMediaMsgtype, type AgentBinding } from './router.js'
 
 const agents: AgentBinding[] = [
   {
@@ -88,3 +88,24 @@ describe('route', () => {
     expect(route(stateEvent as never, agents)).toEqual([])
   })
 })
+
+describe('media events', () => {
+  it('classifies media msgtypes', () => {
+    for (const t of ['m.image', 'm.file', 'm.video', 'm.audio']) {
+      expect(isMediaMsgtype(t)).toBe(true)
+    }
+    expect(isMediaMsgtype('m.text')).toBe(false)
+    expect(isMediaMsgtype('m.notice')).toBe(false)
+    expect(isMediaMsgtype(undefined)).toBe(false)
+  })
+
+  it('never routes media events to agents, even trigger=any', () => {
+    const monitorRoom = msg({ room: '!alerts:example.com', body: 'dog.jpg' })
+    const mediaEvent = {
+      ...monitorRoom,
+      content: { msgtype: 'm.image', body: 'dog.jpg', url: 'mxc://localhost/abc' },
+    }
+    const matches = route(mediaEvent, agents)
+    expect(matches).toEqual([])
+  })
+})