@zooid/transport-matrix 0.12.0 → 0.14.0

package/dist/index.js

@@ -13,7 +13,10 @@ var MatrixClient = class {
     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: localpart2 })
+      body: JSON.stringify({
+        type: "m.login.application_service",
+        username: localpart2
+      })
     });
     if (r.status === 200) return await r.json();
     if (r.status === 400) {
@@ -151,12 +154,15 @@ var MatrixClient = class {
   async sendMessage(input) {
     const content = { ...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) {
-    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) {
     const url = `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(input.roomId)}/typing/${encodeURIComponent(input.asUserId)}?user_id=${encodeURIComponent(input.asUserId)}`;
@@ -218,7 +224,7 @@ var MatrixClient = class {
       user_id: opts.asUserId
     });
     if (opts.from) params.set("from", opts.from);
-    const url = `${this.homeserver}/_matrix/client/v1/rooms/${encodeURIComponent(opts.roomId)}/relations/${encodeURIComponent(opts.rootEventId)}/m.thread?${params.toString()}`;
+    const url = `${this.homeserver}/_matrix/client/v1/rooms/${encodeURIComponent(opts.roomId)}/relations/${encodeURIComponent(opts.rootEventId)}/m.thread/m.room.message?${params.toString()}`;
     const r = await this.fetch(url, {
       method: "GET",
       headers: { Authorization: `Bearer ${this.asToken}` }
@@ -281,15 +287,19 @@ var MatrixClient = class {
     const body = await r.json();
     return body.name ?? null;
   }
-  async sendEvent(roomId, asUserId, eventType, content) {
-    const txn = randomUUID();
+  async sendEvent(roomId, asUserId, eventType, content, txnId) {
+    const txn = txnId ?? randomUUID();
     const url = `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/${eventType}/${txn}?user_id=${encodeURIComponent(asUserId)}`;
     const r = await this.fetch(url, {
       method: "PUT",
       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}`);
+      err.status = r.status;
+      throw err;
+    }
     return await r.json();
   }
 };
@@ -331,7 +341,8 @@ var MatrixContextProvider = class {
     const threads = [];
     for (const ev of chunk) {
       if (ev.type !== "m.room.message") continue;
-      if (ev.content?.msgtype !== "m.text" || typeof ev.content.body !== "string") continue;
+      if (ev.content?.msgtype !== "m.text" && ev.content?.msgtype !== "m.notice" || typeof ev.content.body !== "string")
+        continue;
       const relatesTo = ev.content["m.relates_to"];
       if (relatesTo?.rel_type === "m.thread") continue;
       const agent = this.opts.agentBots.get(ev.sender);
@@ -405,7 +416,7 @@ var MatrixContextProvider = class {
         ...threadId !== void 0 ? { thread_id: threadId } : {}
       };
     }
-    if (msgtype !== "m.text" || typeof body !== "string") return null;
+    if (msgtype !== "m.text" && msgtype !== "m.notice" || typeof body !== "string") return null;
     return {
       id: ev.event_id,
       sender: ev.sender,
@@ -428,7 +439,7 @@ var MatrixContextProvider = class {
       };
     });
   }
-  async getChannelInfo(channelId) {
+  async getRoomInfo(channelId) {
     const name = await this.opts.client.fetchRoomName(channelId, this.opts.asUserId);
     return {
       id: channelId,
@@ -436,6 +447,30 @@ var MatrixContextProvider = class {
       transport: "matrix"
     };
   }
+  async getRooms() {
+    const rooms = this.opts.rooms ?? [];
+    return Promise.all(
+      rooms.map(async (r) => {
+        const name = await this.opts.client.fetchRoomName(r.alias, this.opts.asUserId);
+        return { id: r.alias, name: name ?? r.alias, transport: "matrix" };
+      })
+    );
+  }
+  async sendMessage(input) {
+    const rooms = this.opts.rooms ?? [];
+    if (!rooms.some((r) => r.alias === input.room)) {
+      throw new Error(`not_in_room: this agent is not a member of ${input.room}`);
+    }
+    const { event_id } = await this.opts.client.sendMessage({
+      roomId: input.room,
+      asUserId: this.opts.asUserId,
+      // m.notice, not m.text: agent prose sends as m.notice so
+      // .m.rule.suppress_notices silences it server-side (ZNC025 §10).
+      content: { msgtype: "m.notice", body: input.text },
+      ...input.thread_id ? { threadRoot: input.thread_id } : {}
+    });
+    return { event_id, ...input.thread_id ? { thread_id: input.thread_id } : {} };
+  }
 };
 
 // src/registration.ts
@@ -514,7 +549,7 @@ function inboundThreadRoot(event) {
   const r = event.content?.["m.relates_to"];
   return r?.rel_type === "m.thread" && r.event_id ? r.event_id : void 0;
 }
-function route(event, agents, threadStates) {
+function route(event, agents, threadStates, task) {
   if (event.type !== "m.room.message") return [];
   if (!event.content?.msgtype) return [];
   if (isMediaMsgtype(event.content.msgtype)) return [];
@@ -523,8 +558,25 @@ function route(event, agents, threadStates) {
   const threadRoot = inboundThreadRoot(event);
   const threadState = threadRoot ? threadStates?.get(threadRoot) : void 0;
   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) {
+        continue;
+      } else if (a.name === task.assignee) {
+        matches.push(a);
+      }
+      continue;
+    }
     if (a.trigger === "any") {
       matches.push(a);
       continue;
@@ -536,7 +588,7 @@ function route(event, agents, threadStates) {
     if (threadState) {
       const senderAgent = agents.find((x) => x.userId === event.sender);
       if (senderAgent) {
-        if (threadState.callers[senderAgent.name] === a.name) matches.push(a);
+        if (isReturnRoute(event, a, agents, threadState)) matches.push(a);
       } else {
         const lastPoster = threadState.participants.at(-1);
         if (lastPoster) {
@@ -549,6 +601,22 @@ function route(event, agents, threadStates) {
   }
   return matches;
 }
+function isReturnRoute(event, agent, agents, threadState) {
+  if (!threadState || agent.trigger !== "mention") return false;
+  const sender = agents.find((x) => x.userId === event.sender);
+  if (!sender || sender.name === agent.name) return false;
+  return threadState.callers[sender.name] === agent.name;
+}
+function wouldCycleCallers(callers, callee, caller) {
+  const seen = /* @__PURE__ */ new Set();
+  let cursor = caller;
+  while (cursor !== void 0) {
+    if (cursor === callee || seen.has(cursor)) return true;
+    seen.add(cursor);
+    cursor = callers[cursor];
+  }
+  return false;
+}
 
 // src/space-provisioner.ts
 async function ensureWorkforceSpace(opts) {
@@ -744,6 +812,7 @@ function buildUserPowerLevels(asUserId, admins, agents, roomAlias) {
 // src/transport.ts
 import { Hono } from "hono";
 import { timingSafeEqual } from "crypto";
+import { THREAD_RESULT_FIELD, THREAD_START_FIELD as THREAD_START_FIELD2 } from "@zooid/core";
 
 // src/session-keys.ts
 var HANDOFF_KEY_SEP = "|";
@@ -821,7 +890,11 @@ var RECOVERY_URLS = {
 function toErrorBody(evt, threadRoot) {
   const msg = evt.message.slice(0, 250);
   const out = {
-    msgtype: "m.notice",
+    // No msgtype: dev.zooid.error is not m.room.message, so the field is
+    // meaningless here — it was a vestige of copying the message-body shape.
+    // Its presence used to force careful push-rule `before` positioning
+    // (ZNC025 §10); that positioning is kept regardless, since it also
+    // protects rules for event types that never carried the field.
     body: `\u26A0 [${evt.code}] ${msg}`,
     code: evt.code,
     message: msg,
@@ -836,6 +909,25 @@ function toErrorBody(evt, threadRoot) {
   if (recovery) out.recovery = recovery;
   return out;
 }
+var PREVIEW_MAX = 140;
+function toTurnEndBody(evt, threadRoot) {
+  const preview = evt.lastMessage?.trim().replace(/\s+/g, " ");
+  return {
+    // `body` stays the turn-boundary summary: it is what a generic Matrix
+    // client renders for this event, and the prose is already its own message
+    // in the timeline. The preview below exists only for the push, which
+    // cannot see that message — agent prose is `m.notice`, deliberately
+    // silenced by `.m.rule.suppress_notices` so a chatty turn doesn't fire one
+    // push per chunk ([[ZNC025]] §10). Without it the only notification the
+    // user gets says an agent finished and nothing about what it said.
+    body: evt.producedOutput ? `${evt.agentId} finished` : `${evt.agentId} finished without output`,
+    ...preview ? { last_message: preview.slice(0, PREVIEW_MAX) } : {},
+    agent_id: evt.agentId,
+    session_id: evt.sessionId,
+    produced_output: evt.producedOutput,
+    "m.relates_to": { rel_type: "m.thread", event_id: threadRoot }
+  };
+}
 
 // src/transport.ts
 import { classify } from "@zooid/acp-client";
@@ -1037,8 +1129,282 @@ var SyncLoop = class {
   }
 };
 
+// src/transport.ts
+import { NO_PENDING_INPUT } from "@zooid/core";
+
+// src/task-registry.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var MAX_OPEN_TASKS_PER_ROOM = 5;
+var TaskRegistry = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+    this.runIdValue = this.opts.runId ?? randomUUID2();
+  }
+  opts;
+  tasks = /* @__PURE__ */ new Map();
+  byRoot = /* @__PURE__ */ new Map();
+  generations = /* @__PURE__ */ new Map();
+  runIdValue;
+  get max() {
+    return this.opts.maxOpenPerRoom ?? MAX_OPEN_TASKS_PER_ROOM;
+  }
+  get runId() {
+    return this.runIdValue;
+  }
+  save() {
+    if (!this.opts.journal) return;
+    const rows = [...this.tasks.values()].map((r) => ({ ...r, runId: r.runId ?? this.runId }));
+    const max = this.opts.maxClosedRecords ?? 500;
+    const open = rows.filter((r) => r.phase !== "closed");
+    const closed = rows.filter((r) => r.phase === "closed").sort((a, b) => (b.closedAt ?? "").localeCompare(a.closedAt ?? "")).slice(0, max);
+    this.opts.journal.save([...open, ...closed]);
+  }
+  openCount(roomId) {
+    return [...this.tasks.values()].filter((t) => t.roomId === roomId && t.phase !== "closed").length;
+  }
+  reserve(input) {
+    if (this.openCount(input.roomId) >= this.max) return;
+    const id = this.opts.newId?.() ?? randomUUID2();
+    const rec = {
+      taskId: id,
+      attemptId: id,
+      phase: "reserved",
+      runId: this.runId,
+      ...input
+    };
+    this.tasks.set(id, rec);
+    this.save();
+    return rec;
+  }
+  activate(taskId, threadRoot) {
+    const r = this.tasks.get(taskId);
+    if (!r) return;
+    r.phase = "open";
+    r.threadRoot = threadRoot;
+    this.byRoot.set(threadRoot, taskId);
+    this.save();
+  }
+  abandon(taskId) {
+    this.tasks.delete(taskId);
+    this.save();
+  }
+  markUncertain(taskId) {
+    const r = this.tasks.get(taskId);
+    if (r?.phase === "reserved") r.phase = "uncertain";
+    this.save();
+  }
+  adopt(attemptId, threadRoot) {
+    const r = this.tasks.get(attemptId);
+    if (!r) return;
+    if (r.phase === "closed" || r.threadRoot && r.threadRoot !== threadRoot) return r;
+    this.activate(r.taskId, threadRoot);
+    return r;
+  }
+  taskForRoot(threadRoot) {
+    const id = this.byRoot.get(threadRoot);
+    return id ? this.tasks.get(id) : void 0;
+  }
+  openTaskFor(agent, root) {
+    const r = this.taskForRoot(root);
+    return r?.phase === "open" && r.assignee === agent ? r : void 0;
+  }
+  recordSummary(id, summary) {
+    const r = this.tasks.get(id);
+    if (!r || r.summary !== void 0) return "already_recorded";
+    r.summary = summary;
+    this.save();
+    return "recorded";
+  }
+  clearSummary(id) {
+    const r = this.tasks.get(id);
+    if (r) r.summary = void 0;
+    this.save();
+  }
+  close(id) {
+    const r = this.tasks.get(id);
+    if (!r || r.phase === "closed") return false;
+    r.phase = "closed";
+    r.closedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.save();
+    return true;
+  }
+  /** Reconcile records from a prior daemon run and retain closed roots for trust checks. */
+  restore() {
+    const rows = this.opts.journal?.load() ?? [];
+    const interrupted = [];
+    for (const row of rows) {
+      const rec = { ...row };
+      if (rec.phase !== "closed" && rec.runId !== this.runId) {
+        rec.phase = "closed";
+        rec.closedAt = (/* @__PURE__ */ new Date()).toISOString();
+        interrupted.push(rec);
+      }
+      this.tasks.set(rec.taskId, rec);
+      if (rec.threadRoot) this.byRoot.set(rec.threadRoot, rec.taskId);
+    }
+    this.save();
+    return interrupted;
+  }
+  generationOf(agent, session) {
+    return this.generations.get(`${agent}::${session}`) ?? 0;
+  }
+  bumpGeneration(agent, session) {
+    const k = `${agent}::${session}`;
+    this.generations.set(k, this.generationOf(agent, session) + 1);
+  }
+};
+
+// src/invocation-registry.ts
+import { randomUUID as randomUUID3 } from "crypto";
+var InvocationRegistry = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  opts;
+  records = /* @__PURE__ */ new Map();
+  byCallee = /* @__PURE__ */ new Map();
+  byEvent = /* @__PURE__ */ new Map();
+  open(input) {
+    const record = { invocationId: this.opts.newId?.() ?? randomUUID3(), state: "outstanding", ...input };
+    this.records.set(record.invocationId, record);
+    return record;
+  }
+  attachCallEvent(id, eventId, sessionKey) {
+    const r = this.records.get(id);
+    if (!r) return;
+    r.callEventId = eventId;
+    r.calleeSessionKey = sessionKey;
+    this.byEvent.set(eventId, id);
+    this.byCallee.set(sessionKey, id);
+  }
+  get(id) {
+    return this.records.get(id);
+  }
+  byCallEvent(eventId) {
+    const id = this.byEvent.get(eventId);
+    return id ? this.records.get(id) : void 0;
+  }
+  forCalleeSession(session) {
+    const id = this.byCallee.get(session);
+    return id ? this.records.get(id) : void 0;
+  }
+  outstandingFor(session) {
+    return [...this.records.values()].filter((x) => x.state === "outstanding" && x.callerSessionKey === session);
+  }
+  outstandingForTask(taskId) {
+    return [...this.records.values()].filter((x) => x.state === "outstanding" && x.taskId === taskId);
+  }
+  resolve(id) {
+    const r = this.records.get(id);
+    if (!r || r.state !== "outstanding") return;
+    r.state = "returned";
+    return r;
+  }
+  cancelForTask(taskId) {
+    const records = this.outstandingForTask(taskId);
+    for (const r of records) r.state = "cancelled";
+    return records;
+  }
+  ancestorAgents(session) {
+    const agents = [], seen = /* @__PURE__ */ new Set([session]);
+    let cursor = session;
+    for (; ; ) {
+      const r = this.forCalleeSession(cursor);
+      if (!r || r.state !== "outstanding") break;
+      agents.push(r.callerAgent);
+      if (seen.has(r.callerSessionKey)) break;
+      seen.add(r.callerSessionKey);
+      cursor = r.callerSessionKey;
+    }
+    return agents;
+  }
+  isOutstandingAncestor(session, agent) {
+    return this.ancestorAgents(session).includes(agent);
+  }
+};
+
+// src/task-completion.ts
+function evaluateCompletion(input) {
+  const prose = input.prose?.trim();
+  const output = prose ? { type: "message", text: prose } : void 0;
+  const finish = (completion) => ({
+    decision: "finish",
+    completion: { agent: input.agent, thread_id: input.threadId, ...completion }
+  });
+  if (input.error !== void 0)
+    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" });
+}
+
+// src/task-dispatch.ts
+import { THREAD_START_FIELD } from "@zooid/core";
+function checkDelegable(agentName, roomId, bindings) {
+  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 };
+}
+function buildAssignmentContent(input) {
+  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
+  };
+}
+function renderCompletionPrompt(c) {
+  return [
+    `[task result] ${c.agent} \u2014 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");
+}
+function renderInvocationReturn(c) {
+  return [
+    `[handoff result] ${c.agent} \u2014 status: ${c.status}`,
+    ...c.reason ? [`reason: ${c.reason}`] : [],
+    ...c.error ? [`error: ${c.error}`] : [],
+    ...c.output?.text ? ["", c.output.text] : []
+  ].join("\n");
+}
+function renderDelivery(notify) {
+  return notify === "caller" ? "Each result returns to you as a new turn when that task completes. End your turn now \u2014 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.";
+}
+function renderAssigneeEnvelope(input) {
+  return [
+    `[task] from ${input.parentAgent} \u2014 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 \u2014 @mention an agent in this thread to hand off.",
+    "",
+    input.prompt
+  ].join("\n");
+}
+
 // src/transport.ts
 var STARTUP_GRACE_MS = 5e3;
+var RETURN_GRACE_MS = 9e4;
 async function buildMediaBlocks(items, opts) {
   const blocks = [];
   const pathLines = [];
@@ -1130,9 +1496,19 @@ function inboundThreadRoot2(evt) {
   return r?.rel_type === "m.thread" && r.event_id ? r.event_id : void 0;
 }
 function createMatrixTransport(opts) {
-  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();
@@ -1147,13 +1523,81 @@ function createMatrixTransport(opts) {
   const bufferMessageIds = /* @__PURE__ */ new Map();
   const sendQueue = /* @__PURE__ */ new Map();
   const threadStates = /* @__PURE__ */ new Map();
+  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) => bindings.find((b) => b.name === name);
+  const turnQueues = /* @__PURE__ */ new Map();
+  const pendingReturns = /* @__PURE__ */ new Map();
+  const returnKey = (agentName, threadRoot) => `${agentName}::${threadRoot}`;
+  function stashReturn(sender, threadRoot, roomId, evt, targets) {
+    const key = returnKey(sender.name, threadRoot);
+    let pending = pendingReturns.get(key);
+    if (!pending) {
+      pending = { roomId, threadRoot, event: evt, texts: [], targets: /* @__PURE__ */ new Map() };
+      pendingReturns.set(key, pending);
+    }
+    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} \u2192 ${[...pending.targets.keys()].join(",")} until turn end (thread=${threadRoot})`
+    );
+  }
+  function releaseReturn(key) {
+    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] \u2192 ${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 } : {}
+      });
+    }
+  }
+  function dropPendingReturn(threadRoot, agentName) {
+    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) {
+    for (const [key, pending] of pendingReturns) {
+      if (pending.threadRoot !== threadRoot) continue;
+      if (pending.timer) clearTimeout(pending.timer);
+      pendingReturns.delete(key);
+    }
+  }
   const cutoffTs = mode === "client" ? Number.NEGATIVE_INFINITY : Date.now() - STARTUP_GRACE_MS;
   const seenEventIds = /* @__PURE__ */ new Set();
   const flushedCounts = /* @__PURE__ */ new Map();
   const pendingCommands = /* @__PURE__ */ new Map();
   const buildTextContent = (text) => {
     const content = {
-      msgtype: "m.text",
+      // m.notice, not m.text: .m.rule.suppress_notices silences the
+      // chunk-storm of agent prose server-side (ZNC025 §10) instead of every
+      // client having to filter it. dev.zooid.error carries the same tweak
+      // for the same reason.
+      msgtype: "m.notice",
       body: text
     };
     const html = toMatrixHtml(text);
@@ -1167,21 +1611,30 @@ function createMatrixTransport(opts) {
     }
     return content;
   };
+  const lastFlushed = /* @__PURE__ */ new Map();
   const flushBuffer = (sessionId) => {
     const ctx = sessions.get(sessionId);
     const text = buffers.get(sessionId) ?? "";
     if (!ctx || text.length === 0) return false;
     buffers.set(sessionId, "");
+    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);
       }
@@ -1189,6 +1642,30 @@ function createMatrixTransport(opts) {
     sendQueue.set(sessionId, tail);
     return true;
   };
+  function registerOutgoingHandoffs(sessionId, text) {
+    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: `\u26A0 [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) => {
     const ctx = sessions.get(event.sessionId);
     if (!ctx) {
@@ -1204,8 +1681,7 @@ function createMatrixTransport(opts) {
       if (block.type === "text" && typeof block.text === "string") {
         const prevMessageId = bufferMessageIds.get(event.sessionId);
         const messageChanged = event.messageId !== void 0 && prevMessageId !== void 0 && event.messageId !== prevMessageId;
-        if (event.messageId !== void 0)
-          bufferMessageIds.set(event.sessionId, event.messageId);
+        if (event.messageId !== void 0) bufferMessageIds.set(event.sessionId, event.messageId);
         if (messageChanged) flushBuffer(event.sessionId);
         const current = buffers.get(event.sessionId) ?? "";
         const needsBreak = current.length > 0 && block.text === "";
@@ -1217,7 +1693,12 @@ function createMatrixTransport(opts) {
           const bytes = Buffer.from(block.data, "base64");
           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: ctx2.agent.userId }).then(
+          void mediaClient.upload({
+            data: bytes,
+            contentType: block.mimeType,
+            filename,
+            asUserId: ctx2.agent.userId
+          }).then(
             ({ content_uri }) => client.sendMessage({
               roomId: ctx2.roomId,
               asUserId: ctx2.agent.userId,
@@ -1273,7 +1754,10 @@ function createMatrixTransport(opts) {
       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 !== void 0) content.tool_kind = handle.toolKind;
     if (handle.toolTitle !== void 0) content.tool_title = handle.toolTitle;
     if (handle.toolInput !== void 0) content.tool_input = handle.toolInput;
@@ -1284,6 +1768,51 @@ function createMatrixTransport(opts) {
       content
     });
   });
+  function reportTurnFailure(agent, input, err) {
+    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, 2e3) : void 0,
+        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, input) {
+    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) {
     if (evt.event_id) {
       if (seenEventIds.has(evt.event_id)) {
@@ -1322,6 +1851,7 @@ function createMatrixTransport(opts) {
         return;
       }
       console.log(`[matrix] inbound dev.zooid.session_reset in ${evt.room_id} thread=${threadRoot}`);
+      dropThreadReturns(threadRoot);
       if (!threadStates.has(threadRoot) && evt.room_id) {
         try {
           threadStates.set(
@@ -1335,8 +1865,11 @@ function createMatrixTransport(opts) {
       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);
         }
       }
       return;
@@ -1360,6 +1893,15 @@ function createMatrixTransport(opts) {
             console.error(`[matrix] cancelSession(${t.agent}, ${t.sessionId}) failed:`, err);
           });
         }
+        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;
       }
       if (!content.session_id) {
@@ -1374,7 +1916,10 @@ function createMatrixTransport(opts) {
         `[matrix] interrupt session=${content.session_id} agent=${ctx.agent.name}` + (content.reason ? ` reason=${content.reason}` : "")
       );
       await agents.cancelSession(ctx.agent.name, content.session_id).catch((err) => {
-        console.error(`[matrix] cancelSession(${ctx.agent.name}, ${content.session_id}) failed:`, err);
+        console.error(
+          `[matrix] cancelSession(${ctx.agent.name}, ${content.session_id}) failed:`,
+          err
+        );
       });
       return;
     }
@@ -1382,15 +1927,20 @@ function createMatrixTransport(opts) {
       const content = evt.content ?? {};
       if (!content.session_id || !content.approval_id || !content.decision) return;
       const decision = content.option_id ? { decision: content.decision, optionId: content.option_id } : { decision: content.decision };
-      const ok = approvals.resolve(
-        content.session_id,
-        content.approval_id,
-        decision
-      );
+      const ok = approvals.resolve(content.session_id, content.approval_id, decision);
       if (!ok) console.warn(`[matrix] unknown approval ${content.approval_id}`);
       return;
     }
     logInbound(evt);
+    if (evt.type === "dev.zooid.turn.end") {
+      const agentId = evt.content?.agent_id;
+      const endedRoot = inboundThreadRoot2(evt);
+      const senderAgent = bindings.find((binding) => binding.userId === evt.sender);
+      if (agentId && endedRoot && senderAgent?.name === agentId) {
+        releaseReturn(returnKey(agentId, endedRoot));
+      }
+      return;
+    }
     if (evt.type === "m.room.message" && isMediaMsgtype(evt.content?.msgtype) && evt.room_id && evt.event_id && evt.sender && evt.content?.url && !bindings.some((b) => b.userId === evt.sender)) {
       pendingMedia.add(evt.room_id, inboundThreadRoot2(evt), {
         eventId: evt.event_id,
@@ -1416,7 +1966,32 @@ function createMatrixTransport(opts) {
         console.warn(`[matrix] failed to rebuild threadState for ${inboundRel}:`, err);
       }
     }
-    const matches = route(evt, bindings, threadStates);
+    const startField = evt.content?.[THREAD_START_FIELD2];
+    if (startField?.attempt_id && !inboundRel && evt.event_id)
+      taskRegistry.adopt(startField.attempt_id, evt.event_id);
+    if (evt.content?.[THREAD_RESULT_FIELD] !== void 0) return;
+    const taskRec = promotedRoot ? taskRegistry.taskForRoot(promotedRoot) : void 0;
+    const taskCtx = taskRec && taskRec.phase !== "reserved" ? {
+      assignee: taskRec.assignee,
+      isRoot: !inboundRel && evt.event_id === taskRec.threadRoot
+    } : void 0;
+    let matches = route(evt, bindings, threadStates, taskCtx);
+    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) : [];
+    }
+    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);
+        }
+      }
+      for (const m of matches) dropPendingReturn(promotedRoot, m.name);
+    }
     const senderIsBot = bindings.some((b) => b.userId === evt.sender);
     if (evt.type === "m.room.message" && matches.length === 0 && !senderIsBot) {
       console.warn(
@@ -1429,55 +2004,35 @@ function createMatrixTransport(opts) {
         st = { participants: [], rootMentions: [], callers: {}, handoffs: {} };
         threadStates.set(promotedRoot, st);
       }
-      const msgMentions = new Set(extractMentions(evt));
-      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);
-        if (senderAgent && 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);
+      if (taskCtx?.isRoot) {
+        if (!st.rootMentions.includes(taskRec.assignee)) st.rootMentions.push(taskRec.assignee);
+      } else {
+        const msgMentions = new Set(extractMentions(evt));
+        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);
+          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] \u2192 ${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 = inboundThreadRoot2(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, 2e3) : void 0,
-            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 } : void 0;
+      void enqueueTurn(a, {
+        roomId: evt.room_id,
+        threadRoot: promotedRoot,
+        sessionKey,
+        event: evt,
+        ...taskEnvelope ? { taskEnvelope } : {}
       });
     }
   }
@@ -1518,13 +2073,10 @@ function createMatrixTransport(opts) {
     return c.json({});
   });
   app.get("/healthz", (c) => c.text("ok"));
-  async function runTurn(agent, evt) {
-    if (!evt.room_id || !evt.event_id) return;
-    const inbound = inboundThreadRoot2(evt);
-    const threadRoot = inbound ?? evt.event_id;
-    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 });
+  async function runTurn(agent, input) {
+    const { roomId, threadRoot, sessionKey } = input;
+    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);
@@ -1533,10 +2085,14 @@ function createMatrixTransport(opts) {
       pendingCommands.delete(sessionId);
       void agents.onEvent?.(agent.name, stashedCommands);
     }
-    const roomId = evt.room_id;
     const TYPING_TTL_MS = 3e4;
     const TYPING_REFRESH_MS = 25e3;
-    const safeTyping = (typing) => client.setTyping({ roomId, asUserId: agent.userId, typing, timeoutMs: TYPING_TTL_MS }).catch((err) => console.warn(`[matrix:${agent.name}] setTyping(${typing}) failed:`, err));
+    const safeTyping = (typing) => client.setTyping({
+      roomId,
+      asUserId: agent.userId,
+      typing,
+      timeoutMs: TYPING_TTL_MS
+    }).catch((err) => console.warn(`[matrix:${agent.name}] setTyping(${typing}) failed:`, err));
     const safePresence = (presence) => client.setPresence({ asUserId: agent.userId, presence }).catch(
       (err) => console.warn(`[matrix:${agent.name}] setPresence(${presence}) failed:`, err)
     );
@@ -1545,13 +2101,19 @@ function createMatrixTransport(opts) {
     const refresh = setInterval(() => {
       void safeTyping(true);
     }, TYPING_REFRESH_MS);
+    let turnError;
+    let stopReason;
     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;
       const pendingItems = pendingMedia.drain(
-        evt.room_id,
-        inboundThreadRoot2(evt),
-        evt.sender ?? ""
+        roomId,
+        input.event ? inboundThreadRoot2(input.event) : void 0,
+        input.event?.sender ?? ""
       );
       const { blocks, pathLines } = await buildMediaBlocks(pendingItems, {
         agent,
@@ -1560,7 +2122,7 @@ function createMatrixTransport(opts) {
         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
@@ -1568,38 +2130,307 @@ function createMatrixTransport(opts) {
         }
       });
       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;
       const drainStart = Date.now();
       let drained = buffers.get(sessionId) ?? "";
       while (drainQuietMs > 0 && Date.now() - drainStart < drainMaxMs) {
         await delay(drainQuietMs);
         const next = buffers.get(sessionId) ?? "";
-        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;
       }
       flushBuffer(sessionId);
-      await (sendQueue.get(sessionId) ?? Promise.resolve());
-      if ((flushedCounts.get(sessionId) ?? 0) === 0) {
-        console.warn(
-          `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${evt.room_id}`
-        );
-      }
+    } catch (err) {
+      turnError = err;
+      throw err;
     } finally {
       clearInterval(refresh);
       await safeTyping(false);
       await safePresence("online");
+      await (sendQueue.get(sessionId) ?? Promise.resolve());
+      const producedOutput = (flushedCounts.get(sessionId) ?? 0) > 0;
+      if (!producedOutput) {
+        console.warn(
+          `[matrix:${agent.name}] turn finished with empty buffer (session=${sessionId}); nothing sent to ${roomId}`
+        );
+      }
+      await client.sendCustomEvent({
+        roomId,
+        asUserId: agent.userId,
+        eventType: "dev.zooid.turn.end",
+        content: toTurnEndBody(
+          {
+            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 : void 0,
+          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);
+      lastFlushed.delete(sessionId);
       sendQueue.delete(sessionId);
     }
   }
+  async function finishTask(task, ctx) {
+    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) => 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, completion, task) {
+    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 = {
+    async startTasks(caller, input) {
+      const notify = input.notify ?? "caller";
+      const results = new Array(input.tasks.length);
+      const callerBinding = bindingFor(caller.agentName);
+      const enclosing = taskRegistry.taskForRoot(caller.threadRoot);
+      const admitted = [];
+      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.status;
+              if (status !== void 0 && status >= 400 && status < 500 && status !== 429) {
+                taskRegistry.abandon(rec.taskId);
+                results[index] = {
+                  agent: spec.agent,
+                  status: "failed",
+                  reason: `post_failed: ${String(second.message)}`
+                };
+              } else {
+                taskRegistry.markUncertain(rec.taskId);
+                results[index] = {
+                  agent: spec.agent,
+                  status: "failed",
+                  reason: `post_uncertain: ${String(second.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 !== void 0 && openTask.threadRoot === caller.sessionKey,
+        can_start_task_threads: enclosing === void 0
+      };
+    }
+  };
+  queueMicrotask(() => {
+    for (const task of interruptedTasks) {
+      if (!task.threadRoot) continue;
+      const assignee = bindingFor(task.assignee);
+      if (!assignee) continue;
+      const completion = {
+        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 = mode === "client" ? bindings.map(
     (b) => new SyncLoop({
       client,
@@ -1611,6 +2442,7 @@ function createMatrixTransport(opts) {
   ) : void 0;
   return {
     app,
+    taskActions,
     syncLoops,
     bootstrap: async (bootstrapOpts = {}) => {
       await pool.bootstrap({ adminUserId, ...bootstrapOpts });
@@ -1626,7 +2458,12 @@ function createMatrixTransport(opts) {
   };
 }
 async function rebuildThreadState(client, roomId, rootEventId, bindings) {
-  const state = { participants: [], rootMentions: [], callers: {}, handoffs: {} };
+  const state = {
+    participants: [],
+    rootMentions: [],
+    callers: {},
+    handoffs: {}
+  };
   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);
@@ -1637,7 +2474,7 @@ async function rebuildThreadState(client, roomId, rootEventId, bindings) {
     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);
@@ -1657,7 +2494,7 @@ async function rebuildThreadState(client, roomId, rootEventId, bindings) {
     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] ??= [];
@@ -1726,9 +2563,11 @@ export {
   AGENT_KEY_RE,
   BotPool,
   INLINE_IMAGE_MIMES,
+  InvocationRegistry,
   MAX_DOWNLOAD_BYTES,
   MAX_INLINE_IMAGE_BYTES,
   MAX_MEDIA_PER_TURN,
+  MAX_OPEN_TASKS_PER_ROOM,
   MEDIA_MSGTYPES,
   MatrixClient,
   MatrixContextProvider,
@@ -1736,17 +2575,23 @@ export {
   PendingMediaStore,
   SLUG_RE,
   SyncLoop,
+  TaskRegistry,
   agentMxid,
+  buildAssignmentContent,
   buildWorkforceRoster,
+  checkDelegable,
   createMatrixTransport,
   ensureDefaultChannel,
   ensureWorkforceSpace,
+  evaluateCompletion,
   extractMentions,
   isMediaMsgtype,
   isValidAgentKey,
   isValidWorkstation,
   parseMxcUri,
   publishWorkforce,
+  renderCompletionPrompt,
+  renderInvocationReturn,
   renderRegistration,
   route,
   serverNameFromMxid,