@zooid/transport-matrix 0.12.0 → 0.14.0

package/src/matrix-client.ts

@@ -11,6 +11,7 @@ export interface SendMessageInput {
   asUserId: string
   content: { msgtype: string; body: string; [k: string]: unknown }
   threadRoot?: string
+  txnId?: string
 }
 
 export interface SendCustomEventInput {
@@ -18,6 +19,7 @@ export interface SendCustomEventInput {
   asUserId: string
   eventType: string
   content: Record<string, unknown>
+  txnId?: string
 }
 
 export interface SetTypingInput {
@@ -51,7 +53,10 @@ export class MatrixClient {
     const r = await this.fetch(`${this.homeserver}/_matrix/client/v3/register`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${this.asToken}` },
-      body: JSON.stringify({ type: 'm.login.application_service', username: localpart }),
+      body: JSON.stringify({
+        type: 'm.login.application_service',
+        username: localpart,
+      }),
     })
     if (r.status === 200) return (await r.json()) as { user_id: string; device_id: string }
     if (r.status === 400) {
@@ -143,10 +148,7 @@ export class MatrixClient {
     return j.room_id
   }
 
-  async createRoomRaw(opts: {
-    asUserId: string
-    body: Record<string, unknown>
-  }): Promise<string> {
+  async createRoomRaw(opts: { asUserId: string; body: Record<string, unknown> }): Promise<string> {
     const url = `${this.homeserver}/_matrix/client/v3/createRoom?user_id=${encodeURIComponent(opts.asUserId)}`
     const r = await this.fetch(url, {
       method: 'POST',
@@ -190,11 +192,7 @@ export class MatrixClient {
    * already invited" responses idempotently so bootstrap can run on a
    * fresh AND a populated homeserver without branching.
    */
-  async invite(opts: {
-    roomId: string
-    asUserId: string
-    targetUserId: string
-  }): Promise<void> {
+  async invite(opts: { roomId: string; asUserId: string; targetUserId: string }): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(opts.roomId)}/invite` +
       `?user_id=${encodeURIComponent(opts.asUserId)}`
@@ -229,11 +227,7 @@ export class MatrixClient {
     throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`)
   }
 
-  async leaveRoom(
-    roomId: string,
-    asUserId: string,
-    opts?: { reason?: string },
-  ): Promise<void> {
+  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)}`
@@ -263,13 +257,16 @@ export class MatrixClient {
   async sendMessage(input: SendMessageInput): Promise<{ event_id: string }> {
     const content: Record<string, unknown> = { ...input.content }
     if (input.threadRoot) {
-      content['m.relates_to'] = { rel_type: 'm.thread', event_id: input.threadRoot }
+      content['m.relates_to'] = {
+        rel_type: 'm.thread',
+        event_id: input.threadRoot,
+      }
     }
-    return this.sendEvent(input.roomId, input.asUserId, 'm.room.message', content)
+    return this.sendEvent(input.roomId, input.asUserId, 'm.room.message', content, input.txnId)
   }
 
   async sendCustomEvent(input: SendCustomEventInput): Promise<{ event_id: string }> {
-    return this.sendEvent(input.roomId, input.asUserId, input.eventType, input.content)
+    return this.sendEvent(input.roomId, input.asUserId, input.eventType, input.content, input.txnId)
   }
 
   async setTyping(input: SetTypingInput): Promise<void> {
@@ -356,9 +353,14 @@ export class MatrixClient {
       user_id: opts.asUserId,
     })
     if (opts.from) params.set('from', opts.from)
+    // The 3-segment relations endpoint (rel_type + event_type) scopes both the
+    // returned chunk AND the next_batch cursor to m.room.message server-side —
+    // without it we'd paginate over every m.thread relation (edits, reactions,
+    // redactions) and toMessage()'s client-side filtering would desync from
+    // has_more/next_before (zooid-ai/zooid#21).
     const url =
       `${this.homeserver}/_matrix/client/v1/rooms/${encodeURIComponent(opts.roomId)}` +
-      `/relations/${encodeURIComponent(opts.rootEventId)}/m.thread?${params.toString()}`
+      `/relations/${encodeURIComponent(opts.rootEventId)}/m.thread/m.room.message?${params.toString()}`
     const r = await this.fetch(url, {
       method: 'GET',
       headers: { Authorization: `Bearer ${this.asToken}` },
@@ -409,7 +411,10 @@ export class MatrixClient {
       headers: { Authorization: `Bearer ${this.asToken}` },
     })
     if (!r.ok) throw new Error(`fetchRoomMessages(${opts.roomId}) failed: ${r.status}`)
-    return (await r.json()) as { chunk: Array<Record<string, unknown>>; end?: string }
+    return (await r.json()) as {
+      chunk: Array<Record<string, unknown>>
+      end?: string
+    }
   }
 
   async getJoinedMembers(
@@ -424,19 +429,24 @@ export class MatrixClient {
       headers: { Authorization: `Bearer ${this.asToken}` },
     })
     if (!r.ok) throw new Error(`getJoinedMembers(${roomId}) failed: ${r.status}`)
-    return (await r.json()) as { joined: Record<string, { display_name?: string }> }
+    return (await r.json()) as {
+      joined: Record<string, { display_name?: string }>
+    }
   }
 
-  async sync(opts: {
-    asUserId: string
-    since?: string | null
-    timeoutMs?: number
-  }): Promise<{
+  async sync(opts: { asUserId: string; since?: string | null; timeoutMs?: number }): Promise<{
     next_batch: string
     rooms: {
-      join: Record<string, {
-        timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
-      }>
+      join: Record<
+        string,
+        {
+          timeline: {
+            events: Record<string, unknown>[]
+            prev_batch?: string
+            limited?: boolean
+          }
+        }
+      >
     }
   }> {
     const params = new URLSearchParams({
@@ -452,9 +462,16 @@ export class MatrixClient {
     return r.json() as Promise<{
       next_batch: string
       rooms: {
-        join: Record<string, {
-          timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
-        }>
+        join: Record<
+          string,
+          {
+            timeline: {
+              events: Record<string, unknown>[]
+              prev_batch?: string
+              limited?: boolean
+            }
+          }
+        >
       }
     }>
   }
@@ -478,8 +495,9 @@ export class MatrixClient {
     asUserId: string,
     eventType: string,
     content: Record<string, unknown>,
+    txnId?: string,
   ): Promise<{ event_id: string }> {
-    const txn = randomUUID()
+    const txn = txnId ?? randomUUID()
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}` +
       `/send/${eventType}/${txn}?user_id=${encodeURIComponent(asUserId)}`
@@ -488,7 +506,13 @@ export class MatrixClient {
       headers: { Authorization: `Bearer ${this.asToken}` },
       body: JSON.stringify(content),
     })
-    if (!r.ok) throw new Error(`sendEvent(${eventType}) failed: ${r.status}`)
+    if (!r.ok) {
+      const err = new Error(`sendEvent(${eventType}) failed: ${r.status}`) as Error & {
+        status?: number
+      }
+      err.status = r.status
+      throw err
+    }
     return (await r.json()) as { event_id: string }
   }
 }

package/src/router.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { route, isMediaMsgtype, type AgentBinding, type ThreadState } from './router.js'
+import {
+  route,
+  isMediaMsgtype,
+  wouldCycleCallers,
+  type AgentBinding,
+  type ThreadState,
+} from './router.js'
 
 const agents: AgentBinding[] = [
   {
@@ -17,7 +23,12 @@ const agents: AgentBinding[] = [
 ]
 
 function msg(
-  overrides: Partial<{ room: string; sender: string; body: string; mentions: string[] }> = {},
+  overrides: Partial<{
+    room: string
+    sender: string
+    body: string
+    mentions: string[]
+  }> = {},
 ) {
   return {
     type: 'm.room.message',
@@ -55,7 +66,10 @@ describe('route', () => {
 
   it('skips events whose sender is the matched agent itself', () => {
     const matches = route(
-      msg({ sender: '@architect:example.com', mentions: ['@architect:example.com'] }),
+      msg({
+        sender: '@architect:example.com',
+        mentions: ['@architect:example.com'],
+      }),
       agents,
     )
     expect(matches).toEqual([])
@@ -71,10 +85,7 @@ describe('route', () => {
         trigger: 'mention',
       },
     ]
-    const matches = route(
-      msg({ mentions: ['@architect:example.com', '@qa:example.com'] }),
-      both,
-    )
+    const matches = route(msg({ mentions: ['@architect:example.com', '@qa:example.com'] }), both)
     expect(matches.map((m) => m.name).sort()).toEqual(['architect', 'qa'])
   })
 
@@ -89,6 +100,86 @@ describe('route', () => {
   })
 })
 
+describe('directed task routing', () => {
+  const agents: AgentBinding[] = [
+    {
+      name: 'supervisor',
+      userId: '@supervisor:hs',
+      rooms: [{ alias: '!r:hs' }],
+      trigger: 'mention',
+    },
+    {
+      name: 'worker',
+      userId: '@worker:hs',
+      rooms: [{ alias: '!r:hs' }],
+      trigger: 'mention',
+    },
+    {
+      name: 'eager',
+      userId: '@eager:hs',
+      rooms: [{ alias: '!r:hs' }],
+      trigger: 'any',
+    },
+  ]
+  const root = {
+    type: 'm.room.message',
+    room_id: '!r:hs',
+    sender: '@supervisor:hs',
+    content: {
+      msgtype: 'm.notice',
+      body: '@worker:hs task',
+      'm.mentions': { user_ids: ['@worker:hs'] },
+    },
+  }
+  it('routes a task root solely to its assignee, including self assignment', () => {
+    expect(
+      route(root, agents, new Map(), { assignee: 'worker', isRoot: true }).map((x) => x.name),
+    ).toEqual(['worker'])
+    expect(
+      route(root, agents, new Map(), {
+        assignee: 'supervisor',
+        isRoot: true,
+      }).map((x) => x.name),
+    ).toEqual(['supervisor'])
+  })
+  it('keeps trigger:any out of a task thread while allowing human steering and explicit mentions', () => {
+    const state = new Map([
+      [
+        '$task',
+        {
+          participants: ['worker'],
+          rootMentions: ['worker'],
+          callers: {},
+          handoffs: {},
+        },
+      ],
+    ])
+    const human = {
+      ...root,
+      sender: '@alice:hs',
+      content: {
+        msgtype: 'm.text',
+        body: 'continue',
+        'm.relates_to': { rel_type: 'm.thread', event_id: '$task' },
+      },
+    }
+    expect(
+      route(human, agents, state, { assignee: 'worker', isRoot: false }).map((x) => x.name),
+    ).toEqual(['worker'])
+    const mention = {
+      ...human,
+      sender: '@worker:hs',
+      content: {
+        ...human.content,
+        'm.mentions': { user_ids: ['@supervisor:hs'] },
+      },
+    }
+    expect(
+      route(mention, agents, state, { assignee: 'worker', isRoot: false }).map((x) => x.name),
+    ).toEqual(['supervisor'])
+  })
+})
+
 describe('media events', () => {
   it('classifies media msgtypes', () => {
     for (const t of ['m.image', 'm.file', 'm.video', 'm.audio']) {
@@ -103,7 +194,11 @@ describe('media events', () => {
     const monitorRoom = msg({ room: '!alerts:example.com', body: 'dog.jpg' })
     const mediaEvent = {
       ...monitorRoom,
-      content: { msgtype: 'm.image', body: 'dog.jpg', url: 'mxc://localhost/abc' },
+      content: {
+        msgtype: 'm.image',
+        body: 'dog.jpg',
+        url: 'mxc://localhost/abc',
+      },
     }
     const matches = route(mediaEvent, agents)
     expect(matches).toEqual([])
@@ -169,7 +264,10 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
 
   it('an explicit @mention still re-engages the sub (rule 1 wins)', () => {
     const matches = route(
-      threadMsg({ sender: '@parent:example.com', mentions: ['@sub:example.com'] }),
+      threadMsg({
+        sender: '@parent:example.com',
+        mentions: ['@sub:example.com'],
+      }),
       pair,
       states({ participants: ['parent', 'sub'], callers: { sub: 'parent' } }),
     )
@@ -178,7 +276,10 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
 
   it('dedupes: a sub reply that also @mentions its caller triggers the caller once', () => {
     const matches = route(
-      threadMsg({ sender: '@sub:example.com', mentions: ['@parent:example.com'] }),
+      threadMsg({
+        sender: '@sub:example.com',
+        mentions: ['@parent:example.com'],
+      }),
       pair,
       states({ participants: ['parent'], callers: { sub: 'parent' } }),
     )
@@ -228,6 +329,24 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
   })
 })
 
+describe('caller graph cycle guard', () => {
+  it('rejects a reverse edge back to an existing caller', () => {
+    expect(wouldCycleCallers({ sub: 'parent' }, 'parent', 'sub')).toBe(true)
+  })
+
+  it('rejects a cycle through a deeper ancestor', () => {
+    expect(
+      wouldCycleCallers({ child: 'parent', grandchild: 'child' }, 'parent', 'grandchild'),
+    ).toBe(true)
+  })
+
+  it('allows a new downward or sibling edge', () => {
+    const callers = { child: 'parent' }
+    expect(wouldCycleCallers(callers, 'grandchild', 'child')).toBe(false)
+    expect(wouldCycleCallers(callers, 'sibling', 'parent')).toBe(false)
+  })
+})
+
 describe('fan-out: two subs called in one message ([[ZOD071]] acceptance)', () => {
   const mk = (name: string): AgentBinding => ({
     name,

package/src/router.ts

@@ -50,6 +50,11 @@ export interface ThreadState {
   handoffs: Record<string, string[]>
 }
 
+export interface TaskThreadContext {
+  assignee: string
+  isRoot: boolean
+}
+
 interface MaybeEvent {
   type?: string
   room_id?: string
@@ -71,6 +76,7 @@ export function route(
   event: MaybeEvent,
   agents: AgentBinding[],
   threadStates?: Map<string, ThreadState>,
+  task?: TaskThreadContext,
 ): RouteMatch[] {
   if (event.type !== 'm.room.message') return []
   if (!event.content?.msgtype) return []
@@ -81,8 +87,27 @@ export function route(
   const threadState = threadRoot ? threadStates?.get(threadRoot) : undefined
 
   for (const a of agents) {
-    if (event.sender === a.userId) continue
     if (!a.rooms.some((r) => r.alias === event.room_id)) continue
+    if (task?.isRoot) {
+      if (a.name === task.assignee) matches.push(a)
+      continue
+    }
+    if (event.sender === a.userId) continue
+    if (task) {
+      if (mentions.has(a.userId)) {
+        matches.push(a)
+        continue
+      }
+      const senderAgent = agents.find((x) => x.userId === event.sender)
+      if (senderAgent) {
+        // A delegated task returns at an invocation terminal boundary, never
+        // because a callee happened to post progress prose.
+        continue
+      } else if (a.name === task.assignee) {
+        matches.push(a)
+      }
+      continue
+    }
     if (a.trigger === 'any') {
       matches.push(a)
       continue
@@ -100,7 +125,7 @@ export function route(
         // sender (its caller), never to a callee. Directional continuation
         // keeps agent↔agent handoffs from looping — the call graph is a tree
         // rooted at the human, so returns only ever walk up.
-        if (threadState.callers[senderAgent.name] === a.name) matches.push(a)
+        if (isReturnRoute(event, a, agents, threadState)) matches.push(a)
       } else {
         // Human (or non-agent) follow-up: continue with the most-recent-posting
         // agent, or inherit the root mention if no agent has posted yet.
@@ -115,3 +140,54 @@ export function route(
   }
   return matches
 }
+
+/**
+ * True when routing `event` to `agent` is a *return* — a callee's reply
+ * bubbling up to the agent that called it — rather than a fresh call or a
+ * human follow-up. A callee may address its existing caller explicitly and it
+ * is still a return.
+ *
+ * The transport defers returns to the sender's turn boundary. An agent turn
+ * posts one `m.room.message` per buffered chunk (every tool call forces a
+ * flush), so treating each chunk as a return woke the caller once per chunk
+ * and the two agents read as re-triggering each other. See [[ZOD039]]
+ * § Implicit triggers → Directional continuation.
+ */
+export function isReturnRoute(
+  event: MaybeEvent,
+  agent: AgentBinding,
+  agents: AgentBinding[],
+  threadState: ThreadState | undefined,
+): boolean {
+  if (!threadState || agent.trigger !== 'mention') return false
+  const sender = agents.find((x) => x.userId === event.sender)
+  if (!sender || sender.name === agent.name) return false
+  // Addressing the existing caller explicitly does not reverse the call edge:
+  // it is still the callee returning control. This matters for agents that
+  // naturally prefix their final answer with `@caller`; treating that as a new
+  // call creates the exact A ↔ B cycle directional continuation prevents.
+  return threadState.callers[sender.name] === agent.name
+}
+
+/**
+ * True when recording `callee`’s caller as `caller` would put a cycle in the
+ * call graph — i.e. `callee` is already an ancestor of `caller`. The graph has
+ * to stay a tree rooted at the human, because `route` walks it upward on every
+ * return; a 2-cycle (A calls B, B @mentions A back) would bounce forever.
+ * A mention that would close a cycle is a return, not a call, so it routes but
+ * records no edge.
+ */
+export function wouldCycleCallers(
+  callers: Record<string, string>,
+  callee: string,
+  caller: string,
+): boolean {
+  const seen = new Set<string>()
+  let cursor: string | undefined = caller
+  while (cursor !== undefined) {
+    if (cursor === callee || seen.has(cursor)) return true
+    seen.add(cursor)
+    cursor = callers[cursor]
+  }
+  return false
+}

package/src/task-completion.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { evaluateCompletion } from './task-completion.js'
+
+const base = { agent: 'worker', threadId: '$root', outstanding: 0, awaitingHuman: 0 } as const
+
+describe('evaluateCompletion', () => {
+  it('uses a summary only after all work has returned', () => {
+    expect(evaluateCompletion({ ...base, stopReason: 'end_turn', summary: 'done', outstanding: 1 }))
+      .toEqual({ decision: 'stay_open', reason: 'outstanding_handoff' })
+    expect(evaluateCompletion({ ...base, stopReason: 'end_turn', summary: 'done' }))
+      .toMatchObject({ decision: 'finish', completion: { status: 'complete', output: { text: 'done' } } })
+  })
+  it('makes cancellation and limits terminal even with outstanding work', () => {
+    expect(evaluateCompletion({ ...base, stopReason: 'cancelled', outstanding: 1 }))
+      .toMatchObject({ decision: 'finish', completion: { status: 'cancelled' } })
+    expect(evaluateCompletion({ ...base, stopReason: 'max_tokens', outstanding: 1 }))
+      .toMatchObject({ decision: 'finish', completion: { status: 'partial', reason: 'max_tokens' } })
+  })
+  it('does not report an empty successful result', () => {
+    expect(evaluateCompletion({ ...base, stopReason: 'end_turn' }))
+      .toMatchObject({ decision: 'finish', completion: { status: 'failed', reason: 'no_result' } })
+  })
+})

package/src/task-completion.ts

@@ -0,0 +1,37 @@
+import type { ThreadCompletion } from '@zooid/core'
+
+/** ACP's stable prompt termination values (kept local to avoid an SDK runtime dep). */
+export type StopReason = 'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled'
+
+export interface CompletionInputs {
+  agent: string
+  threadId: string
+  stopReason?: StopReason
+  error?: unknown
+  summary?: string
+  prose?: string
+  outstanding: number
+  awaitingHuman: number
+}
+export type CompletionDecision =
+  | { decision: 'stay_open'; reason: 'outstanding_handoff' | 'awaiting_human' }
+  | { decision: 'finish'; completion: ThreadCompletion }
+
+export function evaluateCompletion(input: CompletionInputs): CompletionDecision {
+  const prose = input.prose?.trim()
+  const output = prose ? { type: 'message' as const, text: prose } : undefined
+  const finish = (completion: Omit<ThreadCompletion, 'agent' | 'thread_id'>): CompletionDecision => ({
+    decision: 'finish', completion: { agent: input.agent, thread_id: input.threadId, ...completion },
+  })
+  if (input.error !== undefined)
+    return finish({ status: 'failed', error: input.error instanceof Error ? input.error.message : String(input.error), ...(output ? { output } : {}) })
+  if (input.stopReason === 'cancelled') return finish({ status: 'cancelled', ...(output ? { output } : {}) })
+  if (input.stopReason === 'max_tokens' || input.stopReason === 'max_turn_requests')
+    return finish({ status: 'partial', reason: input.stopReason, ...(output ? { output } : {}) })
+  if (input.stopReason === 'refusal') return finish({ status: 'failed', reason: 'refusal', ...(output ? { output } : {}) })
+  if (input.awaitingHuman > 0) return { decision: 'stay_open', reason: 'awaiting_human' }
+  if (input.outstanding > 0) return { decision: 'stay_open', reason: 'outstanding_handoff' }
+  if (input.summary) return finish({ status: 'complete', output: { type: 'message', text: input.summary } })
+  if (output) return finish({ status: 'complete', output })
+  return finish({ status: 'failed', reason: 'no_result', error: 'No result produced' })
+}

package/src/task-dispatch.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { buildAssignmentContent, checkDelegable, renderCompletionPrompt } from './task-dispatch.js'
+import type { AgentBinding } from './router.js'
+const agents: AgentBinding[] = [
+  {
+    name: 'supervisor',
+    userId: '@supervisor:hs',
+    rooms: [{ alias: '!r:hs' }],
+    trigger: 'mention',
+  },
+  {
+    name: 'worker',
+    userId: '@worker:hs',
+    rooms: [{ alias: '!r:hs' }],
+    trigger: 'mention',
+  },
+]
+describe('task dispatch', () => {
+  it('admits only local room agents', () => {
+    expect(checkDelegable('worker', '!r:hs', agents)).toEqual({ ok: true })
+    expect(checkDelegable('ghost', '!r:hs', agents)).toMatchObject({
+      ok: false,
+      reason: expect.stringContaining('unknown_agent'),
+    })
+  })
+  it('makes a visible, unthreaded signed root and renders a return', () => {
+    const content = buildAssignmentContent({
+      assigneeUserId: '@worker:hs',
+      prompt: 'audit',
+      start: {
+        version: 1,
+        assignee: 'worker',
+        attempt_id: 'a1',
+        parent: { agent: 'supervisor', thread_root: '$p', session_key: '$p' },
+        notify: 'caller',
+      },
+    })
+    expect(content).toMatchObject({
+      msgtype: 'm.notice',
+      body: '@worker:hs audit',
+      'm.mentions': { user_ids: ['@worker:hs'] },
+    })
+    expect(content['m.relates_to']).toBeUndefined()
+    expect(
+      renderCompletionPrompt({
+        agent: 'worker',
+        thread_id: '$task',
+        status: 'complete',
+        output: { type: 'message', text: 'done' },
+      }),
+    ).toContain('done')
+  })
+})

package/src/task-dispatch.ts

@@ -0,0 +1,68 @@
+import { THREAD_START_FIELD, type ThreadCompletion, type ThreadStartContent } from '@zooid/core'
+import type { AgentBinding } from './router.js'
+export type Admission = { ok: true } | { ok: false; reason: string }
+export function checkDelegable(
+  agentName: string,
+  roomId: string,
+  bindings: AgentBinding[],
+): Admission {
+  const target = bindings.find((b) => b.name === agentName)
+  if (!target)
+    return {
+      ok: false,
+      reason: `unknown_agent: no agent named "${agentName}" is configured here`,
+    }
+  if (!target.rooms.some((r) => r.alias === roomId))
+    return {
+      ok: false,
+      reason: `not_in_room: "${agentName}" is not a member of this room`,
+    }
+  return { ok: true }
+}
+export function buildAssignmentContent(input: {
+  assigneeUserId: string
+  prompt: string
+  start: ThreadStartContent
+}): { msgtype: string; body: string; [key: string]: unknown } {
+  const escaped = input.prompt.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  const body = `${input.assigneeUserId} ${input.prompt}`.trim()
+  return {
+    msgtype: 'm.notice',
+    body,
+    format: 'org.matrix.custom.html',
+    formatted_body: `<a href="https://matrix.to/#/${encodeURIComponent(input.assigneeUserId)}">${input.assigneeUserId}</a> ${escaped}`,
+    'm.mentions': { user_ids: [input.assigneeUserId] },
+    [THREAD_START_FIELD]: input.start,
+  }
+}
+export function renderCompletionPrompt(c: ThreadCompletion) {
+  return [
+    `[task result] ${c.agent} — status: ${c.status} (thread ${c.thread_id})`,
+    ...(c.reason ? [`reason: ${c.reason}`] : []),
+    ...(c.error ? [`error: ${c.error}`] : []),
+    ...(c.output?.text ? ['', c.output.text] : []),
+  ].join('\n')
+}
+export function renderInvocationReturn(c: ThreadCompletion) {
+  return [
+    `[handoff result] ${c.agent} — status: ${c.status}`,
+    ...(c.reason ? [`reason: ${c.reason}`] : []),
+    ...(c.error ? [`error: ${c.error}`] : []),
+    ...(c.output?.text ? ['', c.output.text] : []),
+  ].join('\n')
+}
+export function renderDelivery(notify: 'caller' | 'none'): string {
+  return notify === 'caller'
+    ? 'Each result returns to you as a new turn when that task completes. End your turn now — do not read the task thread to wait for it.'
+    : 'No result returns to you. The task thread is the result surface; thread_id is for later reference, not something to wait on.'
+}
+export function renderAssigneeEnvelope(input: { parentAgent: string; prompt: string }): string {
+  return [
+    `[task] from ${input.parentAgent} — you are the assignee of this thread.`,
+    'Call zooid_complete_task with a self-contained summary when you are done;',
+    'ending your turn without one publishes your last message as the result.',
+    'Sibling task threads are refused here — @mention an agent in this thread to hand off.',
+    '',
+    input.prompt,
+  ].join('\n')
+}