@zooid/transport-matrix 0.13.0 → 0.14.0

package/src/transport.ts

@@ -1,10 +1,28 @@
 import { Hono } from 'hono'
 import { timingSafeEqual } from 'node:crypto'
-import type { AcpRegistry, ApprovalCorrelator, RegisteredApproval } from '@zooid/core'
+import type {
+  AcpRegistry,
+  ApprovalCorrelator,
+  RegisteredApproval,
+  TaskActions,
+  PendingInputRegistry,
+  StartTaskResult,
+  StartTaskSpec,
+  ThreadCompletion,
+  ThreadStartContent,
+} from '@zooid/core'
+import { THREAD_RESULT_FIELD, THREAD_START_FIELD } from '@zooid/core'
 import type { AgentEvent, ContentBlock } from '@zooid/acp-client'
 import { MatrixClient } from './matrix-client.js'
 import { BotPool } from './bot-pool.js'
-import { route, isMediaMsgtype, type AgentBinding, type ThreadState } from './router.js'
+import {
+  route,
+  isMediaMsgtype,
+  isReturnRoute,
+  wouldCycleCallers,
+  type AgentBinding,
+  type ThreadState,
+} from './router.js'
 import { sessionKeyFor, composeHandoffKey } from './session-keys.js'
 import { stripMention, extractMentions } from './mentions.js'
 import {
@@ -17,17 +35,22 @@ import {
 } from './event-encoders.js'
 import { classify } from '@zooid/acp-client'
 import { toMatrixHtml } from './markdown-to-matrix-html.js'
-import {
-  PendingMediaStore,
-  type PendingMediaItem,
-} from './pending-media.js'
-import {
-  MediaClient,
-  MAX_INLINE_IMAGE_BYTES,
-  INLINE_IMAGE_MIMES,
-} from './media-client.js'
+import { PendingMediaStore, type PendingMediaItem } from './pending-media.js'
+import { MediaClient, MAX_INLINE_IMAGE_BYTES, INLINE_IMAGE_MIMES } from './media-client.js'
 import { writeAttachment } from './attachments.js'
 import { SyncLoop } from './sync-loop.js'
+import { NO_PENDING_INPUT } from '@zooid/core'
+import { TaskRegistry, MAX_OPEN_TASKS_PER_ROOM, type TaskJournal, type TaskRecord } from './task-registry.js'
+import { InvocationRegistry } from './invocation-registry.js'
+import { evaluateCompletion, type StopReason } from './task-completion.js'
+import {
+  buildAssignmentContent,
+  checkDelegable,
+  renderCompletionPrompt,
+  renderInvocationReturn,
+  renderAssigneeEnvelope,
+  renderDelivery,
+} from './task-dispatch.js'
 
 export interface MediaClientLike {
   download(input: {
@@ -75,6 +98,12 @@ export interface CreateMatrixTransportOptions {
   loadSince?: (agentUserId: string) => string | null
   /** Pull mode: persist the `since` cursor after each sync poll. */
   saveSince?: (agentUserId: string, since: string) => void
+  /** Durable lifecycle state; supplied by the daemon when it has a data directory. */
+  taskJournal?: TaskJournal
+  taskRunId?: string
+  pendingInput?: PendingInputRegistry
+  /** Deferred-return fallback window. Defaults to `RETURN_GRACE_MS`. */
+  returnGraceMs?: number
 }
 
 interface SessionContext {
@@ -84,6 +113,32 @@ interface SessionContext {
   threadRoot: string
 }
 
+/** A callee's return to its caller, held until the callee's turn ends. */
+interface PendingReturn {
+  roomId: string
+  threadRoot: string
+  /** Last message of the turn so far; prompts the caller when released. */
+  event: MatrixEvent
+  /** Every chunk the callee posted this turn, in order. */
+  texts: string[]
+  /** Callers to wake, by agent name. */
+  targets: Map<string, AgentBinding>
+  timer?: ReturnType<typeof setTimeout>
+}
+interface TurnInput {
+  roomId: string
+  threadRoot: string
+  sessionKey: string
+  promptText?: string
+  event?: MatrixEvent
+  /**
+   * Set only on the root turn of a task thread, for the assignee. Wraps the
+   * computed promptText with `renderAssigneeEnvelope` in runTurn — later
+   * turns in the same thread carry no envelope.
+   */
+  taskEnvelope?: { parentAgent: string }
+}
+
 interface MatrixEvent {
   type?: string
   event_id?: string
@@ -102,6 +157,15 @@ interface MatrixEvent {
 
 const STARTUP_GRACE_MS = 5_000
 
+/**
+ * How long a deferred return waits for the sending agent's `dev.zooid.turn.end`
+ * before firing anyway. The turn.end always follows the turn's messages on the
+ * wire, so this only matters when there is no turn behind them at all — the
+ * daemon restarted mid-turn, or a human posted as the agent's user from a
+ * plain Matrix client. Without it such a return would strand forever.
+ */
+const RETURN_GRACE_MS = 90_000
+
 interface MediaBlocksResult {
   blocks: ContentBlock[]
   pathLines: string[]
@@ -242,9 +306,19 @@ function inboundThreadRoot(evt: MatrixEvent): string | undefined {
 }
 
 export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
-  const { agents, approvals, client, bindings, hsToken, adminUserId, botUserId, mode = 'appservice' } = 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 returnGraceMs = opts.returnGraceMs ?? RETURN_GRACE_MS
   const mediaClient = opts.media
   const writeAttachmentFn = opts.writeAttachmentFn ?? writeAttachment
   const pendingMedia = new PendingMediaStore()
@@ -267,6 +341,91 @@ 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>()
+  const taskRegistry = new TaskRegistry({ journal: opts.taskJournal, runId: opts.taskRunId })
+  const interruptedTasks = taskRegistry.restore()
+  const invocations = new InvocationRegistry()
+  const pendingInput = opts.pendingInput ?? NO_PENDING_INPUT
+  const bindingFor = (name: string) => bindings.find((b) => b.name === name)
+  const turnQueues = new Map<string, Promise<void>>()
+  /**
+   * Returns awaiting their sender's turn boundary, keyed `<agent>::<threadRoot>`.
+   * See `isReturnRoute`: an agent turn posts one message per buffered chunk, so
+   * a return must not fire per message or the caller wakes once per chunk (and
+   * its replies then read as the two agents re-triggering each other). We stash
+   * the callee's prose instead and hand the caller the whole turn at once.
+   */
+  const pendingReturns = new Map<string, PendingReturn>()
+  const returnKey = (agentName: string, threadRoot: string) => `${agentName}::${threadRoot}`
+
+  function stashReturn(
+    sender: AgentBinding,
+    threadRoot: string,
+    roomId: string,
+    evt: MatrixEvent,
+    targets: AgentBinding[],
+  ): void {
+    const key = returnKey(sender.name, threadRoot)
+    let pending = pendingReturns.get(key)
+    if (!pending) {
+      pending = { roomId, threadRoot, event: evt, texts: [], targets: new Map() }
+      pendingReturns.set(key, pending)
+    }
+    // Prompt the caller with the last event of the turn but the text of all of
+    // it — mid-turn chunks carry content the caller would otherwise never see.
+    pending.event = evt
+    const body = evt.content?.body?.trim()
+    if (body) pending.texts.push(body)
+    for (const t of targets) pending.targets.set(t.name, t)
+    if (pending.timer) clearTimeout(pending.timer)
+    pending.timer = setTimeout(() => releaseReturn(key), returnGraceMs)
+    pending.timer.unref?.()
+    console.log(
+      `[matrix] holding return ${sender.name} → ${[...pending.targets.keys()].join(',')} ` +
+        `until turn end (thread=${threadRoot})`,
+    )
+  }
+
+  function releaseReturn(key: string): void {
+    const pending = pendingReturns.get(key)
+    if (!pending) return
+    pendingReturns.delete(key)
+    if (pending.timer) clearTimeout(pending.timer)
+    const promptText = pending.texts.join('\n\n')
+    for (const target of pending.targets.values()) {
+      console.log(`[matrix] → ${target.name} (${target.userId}) [return]`)
+      void enqueueTurn(target, {
+        roomId: pending.roomId,
+        threadRoot: pending.threadRoot,
+        sessionKey: sessionKeyFor(
+          target.name,
+          pending.threadRoot,
+          threadStates.get(pending.threadRoot),
+        ),
+        event: pending.event,
+        ...(promptText ? { promptText } : {}),
+      })
+    }
+  }
+
+  /** Cancel a held return because its target is being woken by this event anyway. */
+  function dropPendingReturn(threadRoot: string, agentName: string): void {
+    for (const [key, pending] of pendingReturns) {
+      if (pending.threadRoot !== threadRoot) continue
+      if (!pending.targets.delete(agentName)) continue
+      if (pending.targets.size === 0) {
+        if (pending.timer) clearTimeout(pending.timer)
+        pendingReturns.delete(key)
+      }
+    }
+  }
+
+  function dropThreadReturns(threadRoot: string): void {
+    for (const [key, pending] of pendingReturns) {
+      if (pending.threadRoot !== threadRoot) continue
+      if (pending.timer) clearTimeout(pending.timer)
+      pendingReturns.delete(key)
+    }
+  }
   // 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
@@ -305,9 +464,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     const html = toMatrixHtml(text)
     if (html) {
       const escapedPlain =
-        '<p>' +
-        text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;') +
-        '</p>'
+        '<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'
@@ -336,14 +493,21 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     lastFlushed.set(sessionId, text)
     flushedCounts.set(sessionId, (flushedCounts.get(sessionId) ?? 0) + 1)
     const content = buildTextContent(text)
+    const pendingInvocations = registerOutgoingHandoffs(sessionId, text)
     const tail = (sendQueue.get(sessionId) ?? Promise.resolve()).then(async () => {
       try {
-        await client.sendMessage({
+        const { event_id } = await client.sendMessage({
           roomId: ctx.roomId,
           asUserId: ctx.agent.userId,
           content,
           threadRoot: ctx.threadRoot,
         })
+        for (const invocation of pendingInvocations)
+          invocations.attachCallEvent(
+            invocation.invocationId,
+            event_id,
+            composeHandoffKey(ctx.threadRoot, event_id),
+          )
       } catch (err) {
         console.warn(`[matrix:${ctx.agent.name}] sendMessage flush failed:`, err)
       }
@@ -352,6 +516,29 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     return true
   }
 
+  function registerOutgoingHandoffs(sessionId: string, text: string) {
+    const ctx = sessions.get(sessionId)
+    if (!ctx) return []
+    const task = taskRegistry.taskForRoot(ctx.threadRoot)
+    if (!task || task.phase !== 'open') return []
+    const sessionKey = sessionKeyFor(ctx.agent.name, ctx.threadRoot, threadStates.get(ctx.threadRoot))
+    const opened = []
+    for (const userId of extractMentions({ content: { body: text } })) {
+      const callee = bindings.find((binding) => binding.userId === userId)
+      if (!callee || callee.name === ctx.agent.name) continue
+      if (invocations.isOutstandingAncestor(sessionKey, callee.name)) {
+        void client.sendCustomEvent({
+          roomId: ctx.roomId, asUserId: ctx.agent.userId, eventType: 'dev.zooid.error',
+          content: { body: `⚠ [handoff_circular] Cannot hand off to ${callee.name}: it is waiting on ${ctx.agent.name}`, code: 'handoff_circular', message: `Cannot hand off to ${callee.name}: it is waiting on ${ctx.agent.name}`, transient: false, 'm.relates_to': { rel_type: 'm.thread', event_id: ctx.threadRoot } },
+        })
+        continue
+      }
+      opened.push(invocations.open({ taskId: task.taskId, callerAgent: ctx.agent.name, callerSessionKey: sessionKey, calleeAgent: callee.name }))
+      taskRegistry.clearSummary(task.taskId)
+    }
+    return opened
+  }
+
   agents.onEvent = async (name, event: AgentEvent) => {
     const ctx = sessions.get(event.sessionId)
     if (!ctx) {
@@ -369,7 +556,12 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     }
 
     if (event.type === 'agent_message_chunk') {
-      const block = event.content as { type?: string; text?: string; data?: string; mimeType?: string }
+      const block = event.content as {
+        type?: string
+        text?: string
+        data?: string
+        mimeType?: string
+      }
       if (block.type === 'text' && typeof block.text === 'string') {
         // A change in ACP messageId marks the previous assistant message as
         // complete. opencode streams each assistant message under its own id
@@ -382,8 +574,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
           event.messageId !== undefined &&
           prevMessageId !== undefined &&
           event.messageId !== prevMessageId
-        if (event.messageId !== undefined)
-          bufferMessageIds.set(event.sessionId, event.messageId)
+        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)
@@ -407,7 +598,12 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
           const ext = (block.mimeType.split('/')[1] ?? 'png').replace(/[^a-z0-9]/gi, '')
           const filename = `image.${ext}`
           void mediaClient
-            .upload({ data: bytes, contentType: block.mimeType, filename, asUserId: ctx.agent.userId })
+            .upload({
+              data: bytes,
+              contentType: block.mimeType,
+              filename,
+              asUserId: ctx.agent.userId,
+            })
             .then(({ content_uri }) =>
               client.sendMessage({
                 roomId: ctx.roomId,
@@ -486,7 +682,10 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       tool_call_id: handle.toolCallId,
       options: handle.options,
     }
-    content['m.relates_to'] = { rel_type: 'm.thread', event_id: ctx.threadRoot }
+    content['m.relates_to'] = {
+      rel_type: 'm.thread',
+      event_id: ctx.threadRoot,
+    }
     if (handle.toolKind !== undefined) content.tool_kind = handle.toolKind
     if (handle.toolTitle !== undefined) content.tool_title = handle.toolTitle
     if (handle.toolInput !== undefined) content.tool_input = handle.toolInput
@@ -498,6 +697,58 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     })
   })
 
+  function reportTurnFailure(agent: AgentBinding, input: TurnInput, err: unknown): void {
+    console.error(`[matrix] runTurn failed for ${agent.name}:`, err)
+    const c = classify(err)
+    const body = toErrorBody(
+      {
+        kind: 'error',
+        agentId: agent.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,
+      },
+      input.threadRoot,
+    )
+    void client
+      .sendCustomEvent({
+        roomId: input.roomId,
+        asUserId: agent.userId,
+        eventType: 'dev.zooid.error',
+        content: body,
+      })
+      .catch((e) => console.warn(`[matrix:${agent.name}] dev.zooid.error send failed:`, e))
+  }
+
+  function enqueueTurn(agent: AgentBinding, input: TurnInput): Promise<void> {
+    const key = `${agent.name}::${input.sessionKey}`
+    const chained = (turnQueues.get(key) ?? Promise.resolve())
+      .then(() => runTurn(agent, input))
+      .then(() => {
+        let st = threadStates.get(input.threadRoot)
+        if (!st) {
+          st = {
+            participants: [],
+            rootMentions: [],
+            callers: {},
+            handoffs: {},
+          }
+          threadStates.set(input.threadRoot, st)
+        }
+        if (st.participants.at(-1) !== agent.name) st.participants.push(agent.name)
+      })
+      .catch((err) => reportTurnFailure(agent, input, err))
+    turnQueues.set(key, chained)
+    void chained.finally(() => {
+      if (turnQueues.get(key) === chained) turnQueues.delete(key)
+    })
+    return chained
+  }
+
   async function handleInboundEvent(evt: MatrixEvent): Promise<void> {
     if (evt.event_id) {
       if (seenEventIds.has(evt.event_id)) {
@@ -554,6 +805,9 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         return
       }
       console.log(`[matrix] inbound dev.zooid.session_reset in ${evt.room_id} thread=${threadRoot}`)
+      // /clear must not allow a pre-reset deferred return to wake an agent up
+      // later via either its old turn.end or the fallback timer.
+      dropThreadReturns(threadRoot)
       // [[ZOD071]]: a thread's sessions are the thread-level one plus one per
       // handoff arc — end them all. Reset events aren't m.room.message, so
       // the self-heal rebuild above doesn't cover them; rebuild here if the
@@ -571,8 +825,11 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       const st = threadStates.get(threadRoot)
       for (const a of bindings) {
         agents.endSession(a.name, threadRoot)
+        taskRegistry.bumpGeneration(a.name, threadRoot)
         for (const arc of st?.handoffs[a.name] ?? []) {
-          agents.endSession(a.name, composeHandoffKey(threadRoot, arc))
+          const key = composeHandoffKey(threadRoot, arc)
+          agents.endSession(a.name, key)
+          taskRegistry.bumpGeneration(a.name, key)
         }
       }
       // NB: keep threadStates intact. Per ZOD039 § /clear, only the agent's
@@ -582,7 +839,10 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       return
     }
     if (evt.type === 'dev.zooid.interrupt') {
-      const content = (evt.content ?? {}) as { session_id?: string; reason?: string }
+      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.
@@ -607,6 +867,18 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
             console.error(`[matrix] cancelSession(${t.agent}, ${t.sessionId}) failed:`, err)
           })
         }
+        // A live session will report ACP's `cancelled` stop reason and finish
+        // in its turn boundary, preserving any prose it already emitted. A
+        // restored/no-session task has no such boundary, so close it here.
+        const task = taskRegistry.taskForRoot(threadRoot)
+        if (task?.phase === 'open' && !targets.some((t) => t.agent === task.assignee)) {
+          const assignee = bindingFor(task.assignee)
+          if (assignee)
+            await finishTask(task, {
+              agent: assignee,
+              completion: { agent: assignee.name, thread_id: threadRoot, status: 'cancelled' },
+            })
+        }
         return
       }
       // Legacy form: explicit session_id in content.
@@ -623,7 +895,10 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
           (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)
+        console.error(
+          `[matrix] cancelSession(${ctx.agent.name}, ${content.session_id}) failed:`,
+          err,
+        )
       })
       return
     }
@@ -638,16 +913,28 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       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,
-      )
+      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)
 
+    // The callee's turn boundary: the daemon sends this only after that turn's
+    // whole send queue has drained, so every message it produced has already
+    // arrived above. Release the return it was holding.
+    if (evt.type === 'dev.zooid.turn.end') {
+      const agentId = evt.content?.agent_id as string | undefined
+      const endedRoot = inboundThreadRoot(evt)
+      const senderAgent = bindings.find((binding) => binding.userId === evt.sender)
+      // Bind the claimed agent_id to the Matrix sender. Besides rejecting a
+      // malformed boundary, this prevents another room member from releasing
+      // a held agent return early by forging custom-event content.
+      if (agentId && endedRoot && senderAgent?.name === agentId) {
+        releaseReturn(returnKey(agentId, endedRoot))
+      }
+      return
+    }
+
     // Capture media events in the pending store; never route them to agents.
     if (
       evt.type === 'm.room.message' &&
@@ -693,7 +980,46 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         console.warn(`[matrix] failed to rebuild threadState for ${inboundRel}:`, err)
       }
     }
-    const matches = route(evt, bindings, threadStates)
+    const startField = evt.content?.[THREAD_START_FIELD] as ThreadStartContent | undefined
+    if (startField?.attempt_id && !inboundRel && evt.event_id)
+      taskRegistry.adopt(startField.attempt_id, evt.event_id)
+    if (evt.content?.[THREAD_RESULT_FIELD] !== undefined) return
+    const taskRec = promotedRoot ? taskRegistry.taskForRoot(promotedRoot) : undefined
+    const taskCtx =
+      taskRec && taskRec.phase !== 'reserved'
+        ? {
+            assignee: taskRec.assignee,
+            isRoot: !inboundRel && evt.event_id === taskRec.threadRoot,
+          }
+        : undefined
+    let matches = route(evt, bindings, threadStates, taskCtx)
+    // In a delegated task, agent-to-agent messages dispatch only when the
+    // outgoing flush registered a matching invocation. This prevents a
+    // circular handoff that was visibly refused from still waking its target.
+    if (taskCtx && !taskCtx.isRoot && evt.event_id && bindings.some((b) => b.userId === evt.sender)) {
+      const invocation = invocations.byCallEvent(evt.event_id)
+      matches = invocation ? matches.filter((match) => match.name === invocation.calleeAgent) : []
+    }
+    // [[ZOD039]] A return fires at the callee's turn boundary, not per message.
+    // Every tool call forces a buffer flush, so one turn posts many
+    // `m.room.message`s; routing each as a return woke the caller once per
+    // chunk and the pair read as re-triggering each other. Hold them and let
+    // the sender's `dev.zooid.turn.end` release the lot as a single wake.
+    if (evt.type === 'm.room.message' && promotedRoot && evt.room_id) {
+      const senderBinding = bindings.find((b) => b.userId === evt.sender)
+      if (senderBinding) {
+        const st = threadStates.get(promotedRoot)
+        const held = matches.filter((m) => isReturnRoute(evt, m, bindings, st))
+        if (held.length > 0) {
+          matches = matches.filter((m) => !held.includes(m))
+          stashReturn(senderBinding, promotedRoot, evt.room_id, evt, held)
+        }
+      }
+      // Anything we are waking now supersedes a return it was owed: an explicit
+      // @mention (rule 1) or a human follow-up already carries the thread on.
+      for (const m of matches) dropPendingReturn(promotedRoot, m.name)
+    }
+
     // 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) {
@@ -709,65 +1035,46 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         st = { participants: [], rootMentions: [], callers: {}, handoffs: {} }
         threadStates.set(promotedRoot, st)
       }
-      const msgMentions = new Set(extractMentions(evt as never))
-      const senderAgent = bindings.find((b) => b.userId === evt.sender)
-      for (const a of bindings) {
-        if (!msgMentions.has(a.userId)) continue
-        if (!st.rootMentions.includes(a.name)) st.rootMentions.push(a.name)
-        // Call edge: the (agent) sender is the caller of every agent it @mentions.
-        if (senderAgent && a.name !== senderAgent.name) {
-          st.callers[a.name] = senderAgent.name
-          // [[ZOD071]] handoff arc: every agent→agent call opens a fresh
-          // session for the callee, keyed by this call event. Recorded before
-          // runTurn dispatch so sessionKeyFor resolves the just-minted arc.
-          // Deduped: homeservers may redeliver a transaction.
-          if (evt.event_id) {
-            const arcs = (st.handoffs[a.name] ??= [])
-            if (!arcs.includes(evt.event_id)) arcs.push(evt.event_id)
+      if (taskCtx?.isRoot) {
+        if (!st.rootMentions.includes(taskRec!.assignee)) st.rootMentions.push(taskRec!.assignee)
+      } else {
+        const msgMentions = new Set(extractMentions(evt as never))
+        const senderAgent = bindings.find((b) => b.userId === evt.sender)
+        for (const a of bindings) {
+          if (!msgMentions.has(a.userId)) continue
+          if (!st.rootMentions.includes(a.name)) st.rootMentions.push(a.name)
+          // A mention that would close a cycle is a return addressed by name,
+          // not a call: record no edge and mint no arc, or the pair bounces
+          // forever and the callee loses its session to a fresh arc.
+          if (
+            senderAgent &&
+            a.name !== senderAgent.name &&
+            !wouldCycleCallers(st.callers, a.name, senderAgent.name)
+          ) {
+            st.callers[a.name] = senderAgent.name
+            if (evt.event_id) {
+              const arcs = (st.handoffs[a.name] ??= [])
+              if (!arcs.includes(evt.event_id)) arcs.push(evt.event_id)
+            }
           }
         }
       }
     }
     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: [], callers: {}, handoffs: {} }
-            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))
-        })
+      if (!promotedRoot || !evt.room_id) continue
+      const sessionKey = sessionKeyFor(a.name, promotedRoot, threadStates.get(promotedRoot))
+      const taskEnvelope =
+        taskCtx?.isRoot && a.name === taskRec!.assignee
+          ? { parentAgent: taskRec!.parent.agent }
+          : undefined
+      void enqueueTurn(a, {
+        roomId: evt.room_id,
+        threadRoot: promotedRoot,
+        sessionKey,
+        event: evt,
+        ...(taskEnvelope ? { taskEnvelope } : {}),
+      })
     }
   }
 
@@ -785,7 +1092,9 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     if (!authOk(c.req.header('authorization'))) {
       return c.json({ errcode: 'M_FORBIDDEN' }, 403)
     }
-    const body = (await c.req.json().catch(() => ({}))) as { events?: MatrixEvent[] }
+    const body = (await c.req.json().catch(() => ({}))) as {
+      events?: MatrixEvent[]
+    }
     for (const evt of body.events ?? []) {
       await handleInboundEvent(evt)
     }
@@ -812,19 +1121,16 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
   })
   app.get('/healthz', (c) => c.text('ok'))
 
-  async function runTurn(agent: AgentBinding, evt: MatrixEvent): Promise<void> {
-    if (!evt.room_id || !evt.event_id) return
-    const inbound = inboundThreadRoot(evt)
+  async function runTurn(agent: AgentBinding, input: TurnInput): Promise<void> {
+    const { roomId, threadRoot, sessionKey } = input
     // Agent-promotion: top-level inbound becomes a thread root via the agent's
     // first reply.
-    const threadRoot = inbound ?? evt.event_id
     // [[ZOD071]]: the session key is the agent's current handoff arc when it
     // has one, else the thread-level key. The raw threadRoot still travels
     // separately: outbound events relate to it, and it is the context ref so
     // zooid_get_history reads the real thread.
-    const sessionKey = sessionKeyFor(agent.name, threadRoot, threadStates.get(threadRoot))
-    const sessionId = await agents.ensureSession(agent.name, sessionKey, evt.room_id, threadRoot)
-    sessions.set(sessionId, { agent, roomId: evt.room_id, threadRoot })
+    const sessionId = await agents.ensureSession(agent.name, sessionKey, roomId, threadRoot)
+    sessions.set(sessionId, { agent, roomId, threadRoot })
     buffers.set(sessionId, '')
     bufferMessageIds.delete(sessionId)
     flushedCounts.set(sessionId, 0)
@@ -837,12 +1143,16 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       void agents.onEvent?.(agent.name, stashedCommands)
     }
 
-    const roomId = evt.room_id
     const TYPING_TTL_MS = 30_000
     const TYPING_REFRESH_MS = 25_000
     const safeTyping = (typing: boolean) =>
       client
-        .setTyping({ roomId, asUserId: agent.userId, typing, timeoutMs: TYPING_TTL_MS })
+        .setTyping({
+          roomId,
+          asUserId: agent.userId,
+          typing,
+          timeoutMs: TYPING_TTL_MS,
+        })
         .catch((err) => console.warn(`[matrix:${agent.name}] setTyping(${typing}) failed:`, err))
     const safePresence = (presence: 'online' | 'unavailable' | 'offline') =>
       client
@@ -857,15 +1167,23 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       void safeTyping(true)
     }, TYPING_REFRESH_MS)
 
+    let turnError: unknown
+    let stopReason: StopReason | undefined
     try {
-      const rawBody = evt.content?.body ?? ''
-      const promptText = stripMention(rawBody, agent.userId)
+      const rawBody = input.event?.content?.body ?? ''
+      const strippedPromptText = input.promptText ?? stripMention(rawBody, agent.userId)
+      const promptText = input.taskEnvelope
+        ? renderAssigneeEnvelope({
+            parentAgent: input.taskEnvelope.parentAgent,
+            prompt: strippedPromptText,
+          })
+        : strippedPromptText
 
       // Drain pending media for this sender+thread and prepend as ACP content blocks.
       const pendingItems = pendingMedia.drain(
-        evt.room_id,
-        inboundThreadRoot(evt),
-        evt.sender ?? '',
+        roomId,
+        input.event ? inboundThreadRoot(input.event) : undefined,
+        input.event?.sender ?? '',
       )
       const { blocks, pathLines } = await buildMediaBlocks(pendingItems, {
         agent,
@@ -874,7 +1192,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         onError: (item, err) => {
           console.warn(`[matrix:${agent.name}] media_failed for ${item.body}:`, err)
           void sendMediaError(
-            { agent, roomId: evt.room_id!, threadRoot },
+            { agent, roomId, threadRoot },
             err,
             `Could not process attachment: ${item.body}`,
             client,
@@ -883,12 +1201,13 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       })
 
       const fullPromptText = [promptText, ...pathLines].filter(Boolean).join('\n')
-      await agents.prompt(agent.name, {
+      const promptResult = await agents.prompt(agent.name, {
         threadId: sessionKey,
-        channelId: evt.room_id,
+        channelId: roomId,
         contextThreadId: threadRoot,
         content: [...blocks, { type: 'text', text: fullPromptText }],
       })
+      stopReason = promptResult.stopReason as StopReason
       // Drain: the prompt promise resolves on the stopReason response, but
       // trailing chunks may still arrive (see DRAIN_* above). Wait until the
       // buffer is quiet for DRAIN_QUIET_MS, re-arming on each new chunk.
@@ -910,13 +1229,15 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
         // 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
+        if (next === drained && (next.length > 0 || (flushedCounts.get(sessionId) ?? 0) > 0)) break
         drained = next
       }
       // 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)
+    } catch (err) {
+      turnError = err
+      throw err
     } finally {
       clearInterval(refresh)
       await safeTyping(false)
@@ -928,7 +1249,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       const producedOutput = (flushedCounts.get(sessionId) ?? 0) > 0
       if (!producedOutput) {
         console.warn(
-          `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${evt.room_id}`,
+          `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${roomId}`,
         )
       }
       // Turn boundary for [[ZOD076]] and push notifications. Sent after the
@@ -937,15 +1258,39 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
       // has nothing in it yet.
       await client
         .sendCustomEvent({
-          roomId: evt.room_id,
+          roomId,
           asUserId: agent.userId,
           eventType: 'dev.zooid.turn.end',
           content: toTurnEndBody(
-            { agentId: agent.name, sessionId, producedOutput, lastMessage: lastFlushed.get(sessionId) },
+            {
+              agentId: agent.name,
+              sessionId,
+              producedOutput,
+              lastMessage: lastFlushed.get(sessionId),
+            },
             threadRoot,
           ),
         })
         .catch((e) => console.warn(`[matrix:${agent.name}] turn.end send failed:`, e))
+      const task = taskRegistry.taskForRoot(threadRoot)
+      const invocation = invocations.forCalleeSession(sessionKey)
+      const isAssignee = task?.phase === 'open' && task.assignee === agent.name && task.threadRoot === sessionKey
+      if (task?.phase === 'open' && (isAssignee || invocation?.state === 'outstanding')) {
+        const decision = evaluateCompletion({
+          agent: agent.name,
+          threadId: isAssignee ? threadRoot : (invocation?.calleeSessionKey ?? sessionKey),
+          stopReason,
+          error: turnError,
+          summary: isAssignee ? task.summary : undefined,
+          prose: lastFlushed.get(sessionId),
+          outstanding: invocations.outstandingFor(sessionKey).length,
+          awaitingHuman: pendingInput.countFor(sessionKey),
+        })
+        if (decision.decision === 'finish') {
+          if (isAssignee) await finishTask(task, { agent, completion: decision.completion })
+          else if (invocation) returnInvocation(invocation, decision.completion, task)
+        }
+      }
       buffers.delete(sessionId)
       bufferMessageIds.delete(sessionId)
       flushedCounts.delete(sessionId)
@@ -954,6 +1299,255 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
     }
   }
 
+  async function finishTask(
+    task: TaskRecord,
+    ctx: { agent: AgentBinding; completion: ThreadCompletion },
+  ): Promise<void> {
+    const threadId = task.threadRoot!
+    const completion = ctx.completion
+    if (!taskRegistry.close(task.taskId)) return
+    const cancelled = invocations.cancelForTask(task.taskId)
+    pendingInput.cancelFor([threadId, ...cancelled.map((i) => i.calleeSessionKey).filter((x): x is string => Boolean(x))])
+    await client.sendCustomEvent({
+      roomId: task.roomId,
+      asUserId: ctx.agent.userId,
+      eventType: THREAD_RESULT_FIELD,
+      content: {
+        ...completion,
+        'm.relates_to': { rel_type: 'm.thread', event_id: threadId },
+      },
+    })
+    if (task.summary && task.summary !== completion.output?.text)
+      await client.sendMessage({
+        roomId: task.roomId,
+        asUserId: ctx.agent.userId,
+        threadRoot: threadId,
+        content: buildTextContent(task.summary),
+      })
+    if (task.notify === 'none') return
+    const parent = bindingFor(task.parent.agent)
+    await client.sendMessage({
+      roomId: task.roomId,
+      asUserId: ctx.agent.userId,
+      threadRoot: task.parent.threadRoot,
+      content: {
+        msgtype: 'm.notice',
+        body: renderCompletionPrompt(completion),
+        [THREAD_RESULT_FIELD]: completion,
+      },
+    })
+    if (
+      !parent ||
+      taskRegistry.generationOf(task.parent.agent, task.parent.sessionKey) !==
+        task.parent.generation
+    )
+      return
+    void enqueueTurn(parent, {
+      roomId: task.roomId,
+      threadRoot: task.parent.threadRoot,
+      sessionKey: task.parent.sessionKey,
+      promptText: renderCompletionPrompt(completion),
+    })
+  }
+
+  function returnInvocation(invocation: import('@zooid/core').InvocationRecord, completion: ThreadCompletion, task: TaskRecord): void {
+    const resolved = invocations.resolve(invocation.invocationId)
+    if (!resolved || task.phase !== 'open') return
+    const caller = bindingFor(resolved.callerAgent)
+    if (!caller || !task.threadRoot) return
+    void enqueueTurn(caller, {
+      roomId: task.roomId,
+      threadRoot: task.threadRoot,
+      sessionKey: resolved.callerSessionKey,
+      promptText: renderInvocationReturn(completion),
+    })
+  }
+
+  const taskActions: TaskActions = {
+    async startTasks(caller, input) {
+      const notify = input.notify ?? 'caller'
+      const results: StartTaskResult[] = new Array(input.tasks.length)
+      const callerBinding = bindingFor(caller.agentName)
+      const enclosing = taskRegistry.taskForRoot(caller.threadRoot)
+      const admitted: Array<{
+        index: number
+        spec: StartTaskSpec
+        rec: TaskRecord
+      }> = []
+      for (const [index, spec] of input.tasks.entries()) {
+        if (!callerBinding) {
+          results[index] = {
+            agent: spec.agent,
+            status: 'refused',
+            reason: 'unknown_caller',
+          }
+          continue
+        }
+        if (enclosing) {
+          results[index] = {
+            agent: spec.agent,
+            status: 'refused',
+            reason:
+              'depth_limit: this thread is itself a delegated task. Do the work here, or @mention another agent in this thread to hand off.',
+          }
+          continue
+        }
+        const admission = checkDelegable(spec.agent, caller.channelId, bindings)
+        if (!admission.ok) {
+          results[index] = {
+            agent: spec.agent,
+            status: 'refused',
+            reason: admission.reason,
+          }
+          continue
+        }
+        const rec = taskRegistry.reserve({
+          roomId: caller.channelId,
+          assignee: spec.agent,
+          notify,
+          parent: {
+            agent: caller.agentName,
+            threadRoot: caller.threadRoot,
+            sessionKey: caller.sessionKey,
+            generation: taskRegistry.generationOf(caller.agentName, caller.sessionKey),
+          },
+        })
+        if (!rec) {
+          results[index] = {
+            agent: spec.agent,
+            status: 'refused',
+            reason: `at_capacity: ${MAX_OPEN_TASKS_PER_ROOM} tasks are already open in this room. Wait for one to finish.`,
+          }
+          continue
+        }
+        admitted.push({ index, spec, rec })
+      }
+      await Promise.all(
+        admitted.map(async ({ index, spec, rec }) => {
+          const assignee = bindingFor(spec.agent)!
+          const content = buildAssignmentContent({
+            assigneeUserId: assignee.userId,
+            prompt: spec.prompt,
+            start: {
+              version: 1,
+              assignee: spec.agent,
+              attempt_id: rec.attemptId,
+              parent: {
+                agent: rec.parent.agent,
+                thread_root: rec.parent.threadRoot,
+                session_key: rec.parent.sessionKey,
+              },
+              notify,
+            },
+          })
+          const post = () =>
+            client.sendMessage({
+              roomId: caller.channelId,
+              asUserId: callerBinding!.userId,
+              content,
+              txnId: rec.attemptId,
+            })
+          try {
+            const { event_id } = await post()
+            taskRegistry.activate(rec.taskId, event_id)
+            results[index] = {
+              agent: spec.agent,
+              status: 'started',
+              thread_id: event_id,
+            }
+          } catch {
+            try {
+              const { event_id } = await post()
+              taskRegistry.activate(rec.taskId, event_id)
+              results[index] = {
+                agent: spec.agent,
+                status: 'started',
+                thread_id: event_id,
+              }
+            } catch (second) {
+              const status = (second as { status?: number }).status
+              if (status !== undefined && status >= 400 && status < 500 && status !== 429) {
+                taskRegistry.abandon(rec.taskId)
+                results[index] = {
+                  agent: spec.agent,
+                  status: 'failed',
+                  reason: `post_failed: ${String((second as Error).message)}`,
+                }
+              } else {
+                taskRegistry.markUncertain(rec.taskId)
+                results[index] = {
+                  agent: spec.agent,
+                  status: 'failed',
+                  reason: `post_uncertain: ${String((second as Error).message)}`,
+                  attempt_id: rec.attemptId,
+                }
+              }
+            }
+          }
+        }),
+      )
+      return { results, notify, delivery: renderDelivery(notify) }
+    },
+    async completeTask(caller, input) {
+      const summary = input.summary.trim()
+      if (!summary) return { status: 'refused', reason: 'summary must be non-empty' }
+      const rec = taskRegistry.openTaskFor(caller.agentName, caller.threadRoot)
+      if (!rec || rec.threadRoot !== caller.sessionKey)
+        return {
+          status: 'refused',
+          reason: 'no_open_task: this session is not the assignee of an open task',
+        }
+      if (invocations.outstandingFor(caller.sessionKey).length)
+        return { status: 'refused', reason: 'outstanding_handoff: wait for delegated work to return' }
+      return { status: taskRegistry.recordSummary(rec.taskId, summary) }
+    },
+    async describeRole(caller) {
+      const enclosing = taskRegistry.taskForRoot(caller.threadRoot)
+      const openTask = taskRegistry.openTaskFor(caller.agentName, caller.threadRoot)
+      return {
+        is_task_assignee: openTask !== undefined && openTask.threadRoot === caller.sessionKey,
+        can_start_task_threads: enclosing === undefined,
+      }
+    },
+  }
+
+  // Journal reconciliation happens after functions are initialized, but before
+  // the daemon starts accepting work. A prior run has no ACP turn to supply a
+  // terminal boundary, so publish its durable cancellation directly.
+  queueMicrotask(() => {
+    for (const task of interruptedTasks) {
+      if (!task.threadRoot) continue
+      const assignee = bindingFor(task.assignee)
+      if (!assignee) continue
+      const completion: ThreadCompletion = {
+        agent: task.assignee, thread_id: task.threadRoot, status: 'cancelled', reason: 'interrupted_by_restart',
+      }
+      void client.sendCustomEvent({
+        roomId: task.roomId, asUserId: assignee.userId, eventType: THREAD_RESULT_FIELD,
+        content: { ...completion, 'm.relates_to': { rel_type: 'm.thread', event_id: task.threadRoot } },
+      })
+      if (task.notify !== 'none') {
+        const parent = bindingFor(task.parent.agent)
+        if (
+          parent &&
+          taskRegistry.generationOf(task.parent.agent, task.parent.sessionKey) === task.parent.generation
+        ) {
+          void client.sendMessage({
+            roomId: task.roomId,
+            asUserId: assignee.userId,
+            threadRoot: task.parent.threadRoot,
+            content: {
+              msgtype: 'm.notice',
+              body: renderCompletionPrompt(completion),
+              [THREAD_RESULT_FIELD]: completion,
+            },
+          })
+          void enqueueTurn(parent, { roomId: task.roomId, threadRoot: task.parent.threadRoot, sessionKey: task.parent.sessionKey, promptText: renderCompletionPrompt(completion) })
+        }
+      }
+    }
+  })
+
   const syncLoops: SyncLoop[] | undefined =
     mode === 'client'
       ? bindings.map(
@@ -970,6 +1564,7 @@ export function createMatrixTransport(opts: CreateMatrixTransportOptions) {
 
   return {
     app,
+    taskActions,
     syncLoops,
     bootstrap: async (
       bootstrapOpts: {
@@ -1003,11 +1598,17 @@ export async function rebuildThreadState(
   rootEventId: string,
   bindings: AgentBinding[],
 ): Promise<ThreadState> {
-  const state: ThreadState = { participants: [], rootMentions: [], callers: {}, handoffs: {} }
+  const state: ThreadState = {
+    participants: [],
+    rootMentions: [],
+    callers: {},
+    handoffs: {},
+  }
   // Impersonate an agent that's actually a member of this room (AS reads
   // require room membership). Falling through to the first binding would
   // 403 if that agent never joined the target room.
-  const asUser = (bindings.find((b) => b.rooms.some((r) => r.alias === roomId)) ?? bindings[0])?.userId
+  const asUser = (bindings.find((b) => b.rooms.some((r) => r.alias === roomId)) ?? bindings[0])
+    ?.userId
   if (!asUser) return state
 
   const root = await client.fetchEvent(roomId, rootEventId, asUser)
@@ -1018,7 +1619,11 @@ export async function rebuildThreadState(
     for (const a of bindings) {
       if (!rootMentions.has(a.userId)) continue
       if (!state.rootMentions.includes(a.name)) state.rootMentions.push(a.name)
-      if (rootSenderAgent && a.name !== rootSenderAgent.name) {
+      if (
+        rootSenderAgent &&
+        a.name !== rootSenderAgent.name &&
+        !wouldCycleCallers(state.callers, a.name, rootSenderAgent.name)
+      ) {
         state.callers[a.name] = rootSenderAgent.name
         const arcs = (state.handoffs[a.name] ??= [])
         if (!arcs.includes(rootEventId)) arcs.push(rootEventId)
@@ -1040,7 +1645,11 @@ export async function rebuildThreadState(
     for (const a of bindings) {
       if (!mentions.has(a.userId)) continue
       if (!state.rootMentions.includes(a.name)) state.rootMentions.push(a.name)
-      if (evSenderAgent && a.name !== evSenderAgent.name) {
+      if (
+        evSenderAgent &&
+        a.name !== evSenderAgent.name &&
+        !wouldCycleCallers(state.callers, a.name, evSenderAgent.name)
+      ) {
         state.callers[a.name] = evSenderAgent.name
         if (evId) {
           const arcs = (state.handoffs[a.name] ??= [])