@zooid/transport-matrix 0.13.0 → 0.14.0

package/src/router.ts

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

package/src/task-completion.test.ts

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

package/src/task-completion.ts

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

package/src/task-dispatch.test.ts

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

package/src/task-dispatch.ts

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

package/src/task-envelope.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { renderAssigneeEnvelope, renderDelivery } from './task-dispatch.js'
+
+describe('renderAssigneeEnvelope', () => {
+  it('names the caller, the owed result, and the depth cap', () => {
+    const out = renderAssigneeEnvelope({
+      parentAgent: 'zooid-assistant',
+      prompt: 'Write a one-sentence bug report.',
+    })
+    expect(out).toMatch(/^\[task\] from zooid-assistant/)
+    expect(out).toMatch(/zooid_complete_task/)
+    expect(out).toMatch(/ending your turn without one/i)
+    expect(out).toMatch(/@mention/)
+    expect(out.endsWith('Write a one-sentence bug report.')).toBe(true)
+  })
+})
+
+describe('renderDelivery', () => {
+  it('tells a notify:caller supervisor to stop and wait', () => {
+    expect(renderDelivery('caller')).toMatch(/new turn/)
+    expect(renderDelivery('caller')).toMatch(/do not read the task thread/i)
+  })
+  it('tells a notify:none supervisor the thread is the result surface', () => {
+    expect(renderDelivery('none')).toMatch(/no result returns/i)
+    expect(renderDelivery('none')).not.toMatch(/new turn/)
+  })
+})

package/src/task-registry.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { MAX_OPEN_TASKS_PER_ROOM, TaskRegistry } from './task-registry.js'
+
+const parent = {
+  agent: 'supervisor',
+  threadRoot: '$parent',
+  sessionKey: '$parent',
+  generation: 0,
+}
+const reserve = (r: TaskRegistry, roomId = '!room:hs') =>
+  r.reserve({ roomId, assignee: 'worker', notify: 'caller', parent })
+
+describe('TaskRegistry', () => {
+  it('enforces the open-task cap independently per room and releases once', () => {
+    const r = new TaskRegistry({
+      newId: (() => {
+        let i = 0
+        return () => `t${++i}`
+      })(),
+    })
+    for (let i = 0; i < MAX_OPEN_TASKS_PER_ROOM; i++) expect(reserve(r)).toBeDefined()
+    expect(reserve(r)).toBeUndefined()
+    const task = r.taskForRoot('$root')
+    expect(task).toBeUndefined()
+    r.activate('t1', '$root')
+    expect(r.close('t1')).toBe(true)
+    expect(r.close('t1')).toBe(false)
+    expect(reserve(r)).toBeDefined()
+    expect(reserve(r, '!other:hs')).toBeDefined()
+  })
+  it('adopts only issued attempts, retains closed roots, and protects uncertain sends', () => {
+    const r = new TaskRegistry({ maxOpenPerRoom: 1, newId: () => 'attempt' })
+    const task = reserve(r)!
+    r.markUncertain(task.taskId)
+    expect(reserve(r)).toBeUndefined()
+    expect(r.adopt('forged', '$bad')).toBeUndefined()
+    expect(r.adopt(task.attemptId, '$root')?.phase).toBe('open')
+    expect(r.openTaskFor('worker', '$root')?.taskId).toBe(task.taskId)
+    expect(r.recordSummary(task.taskId, 'first')).toBe('recorded')
+    expect(r.recordSummary(task.taskId, 'second')).toBe('already_recorded')
+    r.close(task.taskId)
+    expect(r.taskForRoot('$root')?.phase).toBe('closed')
+  })
+  it('bumps session generations after a reset', () => {
+    const r = new TaskRegistry()
+    expect(r.generationOf('a', '$s')).toBe(0)
+    r.bumpGeneration('a', '$s')
+    expect(r.generationOf('a', '$s')).toBe(1)
+  })
+})

package/src/task-registry.ts

@@ -0,0 +1,152 @@
+import { randomUUID } from 'node:crypto'
+export const MAX_OPEN_TASKS_PER_ROOM = 5
+export type TaskPhase = 'reserved' | 'uncertain' | 'open' | 'closed'
+export interface TaskRecord {
+  taskId: string
+  attemptId: string
+  roomId: string
+  assignee: string
+  notify: 'caller' | 'none'
+  parent: {
+    agent: string
+    threadRoot: string
+    sessionKey: string
+    generation: number
+  }
+  phase: TaskPhase
+  threadRoot?: string
+  summary?: string
+  runId?: string
+  closedAt?: string
+}
+export interface PersistedTask extends Required<Pick<TaskRecord, 'taskId' | 'attemptId' | 'roomId' | 'assignee' | 'notify' | 'parent' | 'phase'>> {
+  threadRoot?: string
+  summary?: string
+  runId: string
+  closedAt?: string
+}
+export interface TaskJournal { load(): PersistedTask[]; save(tasks: PersistedTask[]): void }
+export class TaskRegistry {
+  private readonly tasks = new Map<string, TaskRecord>()
+  private readonly byRoot = new Map<string, string>()
+  private readonly generations = new Map<string, number>()
+  private readonly runIdValue: string
+  constructor(
+    private readonly opts: {
+      maxOpenPerRoom?: number
+      newId?: () => string
+      journal?: TaskJournal
+      runId?: string
+      maxClosedRecords?: number
+    } = {},
+  ) {
+    this.runIdValue = this.opts.runId ?? randomUUID()
+  }
+  private get max() {
+    return this.opts.maxOpenPerRoom ?? MAX_OPEN_TASKS_PER_ROOM
+  }
+  private get runId() { return this.runIdValue }
+  private save() {
+    if (!this.opts.journal) return
+    const rows = [...this.tasks.values()].map((r) => ({ ...r, runId: r.runId ?? this.runId }) as PersistedTask)
+    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: string) {
+    return [...this.tasks.values()].filter((t) => t.roomId === roomId && t.phase !== 'closed')
+      .length
+  }
+  reserve(
+    input: Omit<TaskRecord, 'taskId' | 'attemptId' | 'phase' | 'threadRoot' | 'summary'>,
+  ): TaskRecord | undefined {
+    if (this.openCount(input.roomId) >= this.max) return
+    const id = this.opts.newId?.() ?? randomUUID()
+    const rec: TaskRecord = {
+      taskId: id,
+      attemptId: id,
+      phase: 'reserved',
+      runId: this.runId,
+      ...input,
+    }
+    this.tasks.set(id, rec)
+    this.save()
+    return rec
+  }
+  activate(taskId: string, threadRoot: string) {
+    const r = this.tasks.get(taskId)
+    if (!r) return
+    r.phase = 'open'
+    r.threadRoot = threadRoot
+    this.byRoot.set(threadRoot, taskId)
+    this.save()
+  }
+  abandon(taskId: string) {
+    this.tasks.delete(taskId)
+    this.save()
+  }
+  markUncertain(taskId: string) {
+    const r = this.tasks.get(taskId)
+    if (r?.phase === 'reserved') r.phase = 'uncertain'
+    this.save()
+  }
+  adopt(attemptId: string, threadRoot: string) {
+    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: string) {
+    const id = this.byRoot.get(threadRoot)
+    return id ? this.tasks.get(id) : undefined
+  }
+  openTaskFor(agent: string, root: string) {
+    const r = this.taskForRoot(root)
+    return r?.phase === 'open' && r.assignee === agent ? r : undefined
+  }
+  recordSummary(id: string, summary: string) {
+    const r = this.tasks.get(id)
+    if (!r || r.summary !== undefined) return 'already_recorded' as const
+    r.summary = summary
+    this.save()
+    return 'recorded' as const
+  }
+  clearSummary(id: string) {
+    const r = this.tasks.get(id)
+    if (r) r.summary = undefined
+    this.save()
+  }
+  close(id: string) {
+    const r = this.tasks.get(id)
+    if (!r || r.phase === 'closed') return false
+    r.phase = 'closed'
+    r.closedAt = new Date().toISOString()
+    this.save()
+    return true
+  }
+  /** Reconcile records from a prior daemon run and retain closed roots for trust checks. */
+  restore(): TaskRecord[] {
+    const rows = this.opts.journal?.load() ?? []
+    const interrupted: TaskRecord[] = []
+    for (const row of rows) {
+      const rec: TaskRecord = { ...row }
+      if (rec.phase !== 'closed' && rec.runId !== this.runId) {
+        rec.phase = 'closed'; rec.closedAt = 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: string, session: string) {
+    return this.generations.get(`${agent}::${session}`) ?? 0
+  }
+  bumpGeneration(agent: string, session: string) {
+    const k = `${agent}::${session}`
+    this.generations.set(k, this.generationOf(agent, session) + 1)
+  }
+}