@zooid/transport-matrix 0.9.0 → 0.10.0

package/package.json

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

package/src/bot-pool.test.ts

@@ -107,6 +107,129 @@ describe('BotPool.bootstrap — create-if-missing rooms', () => {
     ])
   })
 
+  it('joins the existing room when createRoom loses a race (alias taken)', async () => {
+    // Another agent/process created the room first: the alias didn't resolve at
+    // first check, createRoom then fails (alias in use), and a re-resolve finds
+    // it. We must join that room — not leave an orphan.
+    const calls: string[] = []
+    let resolveCount = 0
+    const client = {
+      registerBot: async () => {},
+      setDisplayName: async () => {},
+      resolveAlias: async (a: string) => {
+        resolveCount++
+        // First check: not found (we'll try to create). After the failed
+        // create, the re-resolve finds the room the concurrent creator made.
+        const r = resolveCount === 1 ? null : '!raced:localhost'
+        calls.push(`resolve:${a}->${r ?? 'null'}`)
+        return r
+      },
+      createRoom: async () => {
+        calls.push('create:THROWS(alias in use)')
+        throw new Error('createRoom(welcome) failed: 409 M_ROOM_IN_USE')
+      },
+      joinRoom: async (room: string, asUser: string) => {
+        calls.push(`join:${asUser}->${room}`)
+      },
+    }
+    const pool = new BotPool(client as never, [
+      {
+        name: 'echo',
+        userId: '@echo:localhost',
+        rooms: [{ alias: '#welcome:localhost' }],
+        trigger: 'mention',
+      },
+    ])
+    await pool.bootstrap({ adminUserId: '@admin:localhost' })
+    expect(calls).toEqual([
+      'resolve:#welcome:localhost->null',
+      'create:THROWS(alias in use)',
+      'resolve:#welcome:localhost->!raced:localhost',
+      'join:@echo:localhost->!raced:localhost',
+    ])
+  })
+
+  it('two pools racing the same room → exactly one room, both join it, no orphans', async () => {
+    // Models the real bug: two agents in *separate* daemon processes bootstrap
+    // the same workforce concurrently. They share one stateful homeserver where
+    // an alias can be claimed exactly once. Each pool's first directory read is
+    // stale (returns null — it read before anyone claimed), so both proceed to
+    // createRoom; the second create loses (alias in use) and must recover by
+    // re-resolving and joining, not orphaning.
+    const aliasToRoom = new Map<string, string>()
+    let roomsCreated = 0
+    let n = 0
+    const makeClient = () => {
+      let staleRead = true
+      const joins: string[] = []
+      return {
+        joins,
+        registerBot: async () => {},
+        setDisplayName: async () => {},
+        invite: async () => {},
+        sendStateEvent: async () => ({ event_id: '$x' }),
+        resolveAlias: async (a: string) => {
+          if (staleRead) {
+            staleRead = false
+            return null
+          }
+          return aliasToRoom.get(a) ?? null
+        },
+        createRoom: async (o: { roomAliasName: string }) => {
+          const alias = `#${o.roomAliasName}:s`
+          if (aliasToRoom.has(alias)) throw new Error('createRoom(shared) failed: 409 M_ROOM_IN_USE')
+          const id = `!room${++n}:s`
+          aliasToRoom.set(alias, id)
+          roomsCreated++
+          return id
+        },
+        joinRoom: async (room: string, user: string) => {
+          joins.push(`${user}->${room}`)
+        },
+      }
+    }
+    const a = makeClient()
+    const b = makeClient()
+    const poolA = new BotPool(a as never, [
+      { name: 'a', userId: '@a:s', rooms: [{ alias: '#shared:s' }], trigger: 'mention' },
+    ])
+    const poolB = new BotPool(b as never, [
+      { name: 'b', userId: '@b:s', rooms: [{ alias: '#shared:s' }], trigger: 'mention' },
+    ])
+    await poolA.bootstrap({ adminUserId: '@admin:s' })
+    await poolB.bootstrap({ adminUserId: '@admin:s' })
+
+    // Exactly one room exists — the loser recovered instead of orphaning.
+    expect(roomsCreated).toBe(1)
+    const theRoom = aliasToRoom.get('#shared:s')
+    // Both agents joined that one room.
+    expect(a.joins).toEqual([`@a:s->${theRoom}`])
+    expect(b.joins).toEqual([`@b:s->${theRoom}`])
+  })
+
+  it('rethrows when createRoom fails and the alias still does not resolve', async () => {
+    const client = {
+      registerBot: async () => {},
+      setDisplayName: async () => {},
+      resolveAlias: async () => null, // never resolves — genuine creation failure
+      createRoom: async () => {
+        throw new Error('createRoom(welcome) failed: 500 boom')
+      },
+      joinRoom: vi.fn(async () => undefined),
+    }
+    const pool = new BotPool(client as never, [
+      {
+        name: 'echo',
+        userId: '@echo:localhost',
+        rooms: [{ alias: '#welcome:localhost' }],
+        trigger: 'mention',
+      },
+    ])
+    // bootstrap swallows per-room errors (logs); the room is never joined.
+    await pool.bootstrap({ adminUserId: '@admin:localhost' })
+    expect(client.joinRoom).not.toHaveBeenCalled()
+  })
+
   it('skips create when the alias already resolves', async () => {
     const calls: string[] = []
     const client = {
@@ -248,8 +371,14 @@ describe('BotPool.bootstrap workforce-space attachment', () => {
       ],
     )
     await pool.bootstrap({ spaceRoomId: '!space:zoon.local', asUserId: '@zooid:zoon.local' })
+    // Created BY the AS sender bot (room owner/admin), never by the agent —
+    // agents join as plain members, never room admins.
     expect(createRoom).toHaveBeenCalledWith(
-      expect.objectContaining({ roomAliasName: 'design', restrictedToSpaceId: '!space:zoon.local' }),
+      expect.objectContaining({
+        roomAliasName: 'design',
+        restrictedToSpaceId: '!space:zoon.local',
+        senderUserId: '@zooid:zoon.local',
+      }),
     )
   })
 

package/src/bot-pool.ts

@@ -82,21 +82,39 @@ export class BotPool {
               } else {
                 const colon = room.indexOf(':')
                 const aliasLocalpart = colon > 1 ? room.slice(1, colon) : room.slice(1)
-                const sender = opts.adminUserId ?? a.userId
+                // Workstation-created rooms are owned by the AS sender bot (PL
+                // 100, already seeded in the power override below). Agents join
+                // as plain members and must never be room admins. The human
+                // operator is invited + seeded at PL 100, but can't be the
+                // creator under a workstation-scoped namespace — the AS token
+                // can't impersonate a non-namespaced human.
+                const sender = opts.asUserId ?? opts.adminUserId ?? a.userId
                 const userPowerLevels = buildUserPowerLevels(
                   opts.asUserId,
                   opts.adminUserIds,
                   this.agents,
                   room,
                 )
-                resolved = await this.client.createRoom({
-                  roomAliasName: aliasLocalpart,
-                  invite: opts.adminUserId ? [opts.adminUserId] : [],
-                  senderUserId: sender,
-                  name: aliasLocalpart,
-                  ...(opts.spaceRoomId ? { restrictedToSpaceId: opts.spaceRoomId } : {}),
-                  ...(userPowerLevels ? { userPowerLevels } : {}),
-                })
+                try {
+                  resolved = await this.client.createRoom({
+                    roomAliasName: aliasLocalpart,
+                    invite: opts.adminUserId ? [opts.adminUserId] : [],
+                    senderUserId: sender,
+                    name: aliasLocalpart,
+                    ...(opts.spaceRoomId ? { restrictedToSpaceId: opts.spaceRoomId } : {}),
+                    ...(userPowerLevels ? { userPowerLevels } : {}),
+                  })
+                } catch (err) {
+                  // Another agent — or another daemon process bootstrapping the
+                  // same workforce — may have created this room concurrently, so
+                  // its alias is now taken (createRoom fails with the alias in
+                  // use). Re-resolve and join the existing room rather than
+                  // leaving an orphan. Only rethrow if the alias still doesn't
+                  // resolve (a genuine creation failure).
+                  const raced = await this.client.resolveAlias(room)
+                  if (!raced) throw err
+                  resolved = raced
+                }
               }
               aliasToId.set(room, resolved)
             }

package/src/identity.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import {
+  isValidWorkstation,
+  isValidAgentKey,
+  agentMxid,
+  splitAgentLocalpart,
+  workstationUserNamespace,
+} from './identity.js'
+
+describe('workstation / agent grammar', () => {
+  it('accepts dot-free lowercase-alnum-hyphen', () => {
+    expect(isValidWorkstation('laptop')).toBe(true)
+    expect(isValidWorkstation('ec2-prod')).toBe(true)
+    expect(isValidAgentKey('docs')).toBe(true)
+  })
+  it('rejects dots (the workstation/agent separator) and bad chars', () => {
+    expect(isValidWorkstation('lap.top')).toBe(false) // dot is the boundary, never inside
+    expect(isValidWorkstation('Laptop')).toBe(false) // strict ASCII lowercase
+    expect(isValidWorkstation('lap_top')).toBe(false)
+    expect(isValidWorkstation('')).toBe(false)
+    expect(isValidAgentKey('a.b')).toBe(false)
+  })
+})
+
+describe('agentMxid', () => {
+  it('builds @{workstation}.{agent}:server', () => {
+    expect(agentMxid('laptop', 'assistant', 'zoon.eco')).toBe('@laptop.assistant:zoon.eco')
+  })
+  it('throws on invalid parts', () => {
+    expect(() => agentMxid('lap.top', 'assistant', 'zoon.eco')).toThrow()
+    expect(() => agentMxid('laptop', 'a.b', 'zoon.eco')).toThrow()
+  })
+})
+
+describe('splitAgentLocalpart — split on FIRST dot', () => {
+  it('recovers (workstation, agent)', () => {
+    expect(splitAgentLocalpart('laptop.assistant')).toEqual({
+      workstation: 'laptop',
+      agent: 'assistant',
+    })
+  })
+  it('throws when there is no separator', () => {
+    expect(() => splitAgentLocalpart('zooid')).toThrow()
+  })
+})
+
+describe('workstationUserNamespace', () => {
+  it('emits an escaped-dot exclusive regex for the workstation', () => {
+    // The literal dot must be escaped so @{workstation}.* does not also match @{workstation}X*
+    expect(workstationUserNamespace('laptop', 'zoon.eco')).toBe('@laptop\\..*:zoon.eco')
+  })
+})

package/src/identity.ts

@@ -0,0 +1,27 @@
+// A workstation id (and an agent key) must be "slug-shaped": kebab-case,
+// MXID/alias-safe. SLUG_RE names the *format*; the domain noun is workstation.
+export const SLUG_RE = /^[a-z0-9-]+$/
+export const AGENT_KEY_RE = /^[a-z0-9-]+$/
+
+export const isValidWorkstation = (s: string): boolean => SLUG_RE.test(s)
+export const isValidAgentKey = (s: string): boolean => AGENT_KEY_RE.test(s)
+
+export function agentMxid(workstation: string, agent: string, serverName: string): string {
+  if (!isValidWorkstation(workstation))
+    throw new Error(`invalid workstation: ${JSON.stringify(workstation)}`)
+  if (!isValidAgentKey(agent)) throw new Error(`invalid agent key: ${JSON.stringify(agent)}`)
+  return `@${workstation}.${agent}:${serverName}`
+}
+
+export function splitAgentLocalpart(localpart: string): { workstation: string; agent: string } {
+  const i = localpart.indexOf('.') // first dot is the boundary; workstation/agent are dot-free
+  if (i <= 0 || i === localpart.length - 1)
+    throw new Error(`not a workstation.agent localpart: ${localpart}`)
+  return { workstation: localpart.slice(0, i), agent: localpart.slice(i + 1) }
+}
+
+export function workstationUserNamespace(workstation: string, serverName: string): string {
+  if (!isValidWorkstation(workstation))
+    throw new Error(`invalid workstation: ${JSON.stringify(workstation)}`)
+  return `@${workstation}\\..*:${serverName}` // escaped dot — exclusive to this workstation's agents
+}

package/src/index.ts

@@ -4,6 +4,15 @@ export { MatrixContextProvider } from './context-provider.js'
 export type { MatrixContextProviderOpts } from './context-provider.js'
 export { renderRegistration } from './registration.js'
 export type { MatrixTransportConfig } from './registration.js'
+export {
+  isValidWorkstation,
+  isValidAgentKey,
+  agentMxid,
+  splitAgentLocalpart,
+  workstationUserNamespace,
+  SLUG_RE,
+  AGENT_KEY_RE,
+} from './identity.js'
 export { extractMentions } from './mentions.js'
 export type { MaybeMessage } from './mentions.js'
 export { route, isMediaMsgtype, MEDIA_MSGTYPES } from './router.js'
@@ -11,6 +20,8 @@ export type { AgentBinding, RouteMatch } from './router.js'
 export { BotPool } from './bot-pool.js'
 export { createMatrixTransport } from './transport.js'
 export type { CreateMatrixTransportOptions, MediaClientLike } from './transport.js'
+export { SyncLoop } from './sync-loop.js'
+export type { SyncLoopOptions, SyncResponse, SyncClient } from './sync-loop.js'
 export { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
 export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {

package/src/matrix-client.test.ts

@@ -160,6 +160,49 @@ describe('MatrixClient', () => {
     })
   })
 
+  it('createRoom keeps the creator at PL 100 when a power-level override omits them', async () => {
+    // power_level_content_override.users REPLACES the default { creator: 100 }
+    // map; if the creator is left out they drop to 0 and can't claim the alias.
+    const fetch = fakeFetch(async ({ init }) => {
+      const body = JSON.parse(init.body as string)
+      expect(body.power_level_content_override.users).toEqual({
+        '@zooid:localhost': 100,
+        '@creator:localhost': 100,
+      })
+      return new Response(JSON.stringify({ room_id: '!new:localhost' }), { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.createRoom({
+      roomAliasName: 'welcome',
+      invite: [],
+      senderUserId: '@creator:localhost',
+      userPowerLevels: { '@zooid:localhost': 100 },
+    })
+  })
+
+  it('createRoom does not override an explicit power level already set for the creator', async () => {
+    const fetch = fakeFetch(async ({ init }) => {
+      const body = JSON.parse(init.body as string)
+      expect(body.power_level_content_override.users['@creator:localhost']).toBe(50)
+      return new Response(JSON.stringify({ room_id: '!new:localhost' }), { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.createRoom({
+      roomAliasName: 'welcome',
+      invite: [],
+      senderUserId: '@creator:localhost',
+      userPowerLevels: { '@creator:localhost': 50 },
+    })
+  })
+
   it('setDisplayName PUTs the displayname endpoint impersonating the user', async () => {
     const fetch = fakeFetch(async ({ url, init }) => {
       expect(url).toBe(
@@ -478,6 +521,29 @@ describe('MatrixClient.leaveRoom', () => {
   })
 })
 
+describe('MatrixClient.sync (impersonated)', () => {
+  it('GETs /sync with ?user_id=, as_token bearer, since + timeout', async () => {
+    const fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ next_batch: 's2', rooms: { join: {} } }), { status: 200 }),
+    )
+    const c = new MatrixClient({
+      homeserver: 'https://zoon.eco',
+      asToken: 'as-tok',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    const out = await c.sync({ asUserId: '@laptop.docs:zoon.eco', since: 's1', timeoutMs: 30000 })
+
+    expect(out.next_batch).toBe('s2')
+    const url = new URL(fetch.mock.calls[0]![0] as string)
+    expect(url.pathname).toBe('/_matrix/client/v3/sync')
+    expect(url.searchParams.get('user_id')).toBe('@laptop.docs:zoon.eco')
+    expect(url.searchParams.get('since')).toBe('s1')
+    expect(url.searchParams.get('timeout')).toBe('30000')
+    const headers = (fetch.mock.calls[0]![1] as RequestInit).headers as Record<string, string>
+    expect(headers.Authorization).toBe('Bearer as-tok')
+  })
+})
+
 describe('MatrixClient.createRoom restricted', () => {
   it('injects a restricted join rule referencing the space when restrictedToSpaceId is set', async () => {
     const fetch = fakeFetch(async ({ url, init }) => {

package/src/matrix-client.ts

@@ -115,7 +115,14 @@ export class MatrixClient {
       ]
     }
     if (opts.userPowerLevels && Object.keys(opts.userPowerLevels).length > 0) {
-      body.power_level_content_override = { users: opts.userPowerLevels }
+      // `power_level_content_override.users` REPLACES the default `{ creator: 100 }`
+      // map rather than merging into it. If the creator (senderUserId) is omitted
+      // here they drop to `users_default` (0) and can't set `m.room.canonical_alias`
+      // (PL 50) during creation — the createRoom call then 403s and leaves an
+      // aliasless orphan room. Always keep the creator at admin power.
+      const users = { ...opts.userPowerLevels }
+      if (users[opts.senderUserId] === undefined) users[opts.senderUserId] = 100
+      body.power_level_content_override = { users }
     }
     const r = await this.fetch(
       `${this.homeserver}/_matrix/client/v3/createRoom?user_id=${encodeURIComponent(opts.senderUserId)}`,
@@ -420,6 +427,38 @@ export class MatrixClient {
     return (await r.json()) as { joined: Record<string, { display_name?: string }> }
   }
 
+  async sync(opts: {
+    asUserId: string
+    since?: string | null
+    timeoutMs?: number
+  }): Promise<{
+    next_batch: string
+    rooms: {
+      join: Record<string, {
+        timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
+      }>
+    }
+  }> {
+    const params = new URLSearchParams({
+      user_id: opts.asUserId,
+      timeout: String(opts.timeoutMs ?? 30_000),
+    })
+    if (opts.since) params.set('since', opts.since)
+    const url = `${this.homeserver}/_matrix/client/v3/sync?${params.toString()}`
+    const r = await this.fetch(url, {
+      headers: { Authorization: `Bearer ${this.asToken}` },
+    })
+    if (!r.ok) throw new Error(`sync(${opts.asUserId}) failed: ${r.status}`)
+    return r.json() as Promise<{
+      next_batch: string
+      rooms: {
+        join: Record<string, {
+          timeline: { events: Record<string, unknown>[]; prev_batch?: string; limited?: boolean }
+        }>
+      }
+    }>
+  }
+
   async fetchRoomName(roomId: string, asUserId: string): Promise<string | null> {
     const url =
       `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}` +

package/src/registration.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import { parse } from 'yaml'
 import { renderRegistration, type MatrixTransportConfig } from './registration.js'
 
 const baseConfig: MatrixTransportConfig = {
@@ -39,3 +40,22 @@ describe('renderRegistration', () => {
     expect(yaml).toContain('rate_limited: false')
   })
 })
+
+it('renders a workstation-scoped EXCLUSIVE registration', () => {
+  const y = parse(
+    renderRegistration({
+      id: 'laptop',
+      url: 'http://10.0.1.5:9099',
+      homeserver: 'https://zoon.eco',
+      asToken: 'as-x',
+      hsToken: 'hs-x',
+      senderLocalpart: 'laptop',
+      userNamespace: '@laptop\\..*:zoon.eco',
+      exclusive: true,
+    }),
+  )
+  expect(y.sender_localpart).toBe('laptop')
+  expect(y.url).toBe('http://10.0.1.5:9099')
+  expect(y.namespaces.users[0]).toEqual({ exclusive: true, regex: '@laptop\\..*:zoon.eco' })
+  expect(y.namespaces.rooms).toEqual([]) // never fence by room id
+})

package/src/router.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { route, isMediaMsgtype, type AgentBinding } from './router.js'
+import { route, isMediaMsgtype, type AgentBinding, type ThreadState } from './router.js'
 
 const agents: AgentBinding[] = [
   {
@@ -109,3 +109,119 @@ describe('media events', () => {
     expect(matches).toEqual([])
   })
 })
+
+describe('directional thread continuation (agent-to-agent handoffs)', () => {
+  const parent: AgentBinding = {
+    name: 'parent',
+    userId: '@parent:example.com',
+    rooms: [{ alias: '!room1:example.com' }],
+    trigger: 'mention',
+  }
+  const sub: AgentBinding = {
+    name: 'sub',
+    userId: '@sub:example.com',
+    rooms: [{ alias: '!room1:example.com' }],
+    trigger: 'mention',
+  }
+  const pair = [parent, sub]
+
+  // A bare (or mentioning) reply inside the thread rooted at $root.
+  function threadMsg(o: { sender: string; mentions?: string[] }) {
+    return {
+      type: 'm.room.message',
+      room_id: '!room1:example.com',
+      sender: o.sender,
+      event_id: '$evt',
+      content: {
+        msgtype: 'm.text',
+        body: 'reply',
+        'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+        ...(o.mentions ? { 'm.mentions': { user_ids: o.mentions } } : {}),
+      },
+    }
+  }
+
+  function states(s: Partial<ThreadState>): Map<string, ThreadState> {
+    return new Map([['$root', { participants: [], rootMentions: [], callers: {}, ...s }]])
+  }
+
+  it("routes a sub's bare reply up to its caller (parent notified)", () => {
+    const matches = route(
+      threadMsg({ sender: '@sub:example.com' }),
+      pair,
+      states({ participants: ['parent'], callers: { sub: 'parent' } }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['parent'])
+  })
+
+  it('does NOT re-trigger a callee when its parent posts a bare reply (loop guard)', () => {
+    // parent is the sender; sub is its callee. parent has no caller of its own,
+    // so its bare reply routes to nobody — the loop dies here.
+    const matches = route(
+      threadMsg({ sender: '@parent:example.com' }),
+      pair,
+      states({ participants: ['parent', 'sub'], callers: { sub: 'parent' } }),
+    )
+    expect(matches).toEqual([])
+  })
+
+  it('an explicit @mention still re-engages the sub (rule 1 wins)', () => {
+    const matches = route(
+      threadMsg({ sender: '@parent:example.com', mentions: ['@sub:example.com'] }),
+      pair,
+      states({ participants: ['parent', 'sub'], callers: { sub: 'parent' } }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['sub'])
+  })
+
+  it('dedupes: a sub reply that also @mentions its caller triggers the caller once', () => {
+    const matches = route(
+      threadMsg({ sender: '@sub:example.com', mentions: ['@parent:example.com'] }),
+      pair,
+      states({ participants: ['parent'], callers: { sub: 'parent' } }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['parent'])
+  })
+
+  it('bubbles a 3-level chain one hop at a time (grandchild → child, not parent)', () => {
+    const child: AgentBinding = {
+      name: 'child',
+      userId: '@child:example.com',
+      rooms: [{ alias: '!room1:example.com' }],
+      trigger: 'mention',
+    }
+    const grand: AgentBinding = {
+      name: 'grand',
+      userId: '@grand:example.com',
+      rooms: [{ alias: '!room1:example.com' }],
+      trigger: 'mention',
+    }
+    const matches = route(
+      threadMsg({ sender: '@grand:example.com' }),
+      [parent, child, grand],
+      states({
+        participants: ['parent', 'child'],
+        callers: { child: 'parent', grand: 'child' },
+      }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['child'])
+  })
+
+  it('a human bare reply still continues with the most-recent-posting agent (unchanged)', () => {
+    const matches = route(
+      threadMsg({ sender: '@alice:example.com' }),
+      pair,
+      states({ participants: ['parent', 'sub'], callers: { sub: 'parent' } }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['sub'])
+  })
+
+  it('an agent with no caller (human-initiated) returns to nobody', () => {
+    const matches = route(
+      threadMsg({ sender: '@parent:example.com' }),
+      pair,
+      states({ participants: ['parent'], callers: {} }),
+    )
+    expect(matches).toEqual([])
+  })
+})

package/src/router.ts

@@ -33,6 +33,14 @@ export interface ThreadState {
   participants: string[]
   /** Agent names @mentioned in the thread root event (or subsequently). */
   rootMentions: string[]
+  /**
+   * Agent-to-agent call edges: sub-agent name → the agent that @mentioned
+   * (called) it in this thread. A sub's bare reply bubbles up to its caller;
+   * a caller never implicitly re-triggers its callee. Makes agent↔agent
+   * acknowledgement loops structurally impossible. See [[ZOD039]] §
+   * Implicit triggers → Directional continuation.
+   */
+  callers: Record<string, string>
 }
 
 interface MaybeEvent {
@@ -77,14 +85,24 @@ export function route(
       matches.push(a)
       continue
     }
-    // Implicit trigger in a thread: most-recent-poster, or root-mention
-    // inheritance if no agent has posted yet.
+    // Implicit trigger in a thread.
     if (threadState) {
-      const lastPoster = threadState.participants.at(-1)
-      if (lastPoster) {
-        if (lastPoster === a.name) matches.push(a)
-      } else if (threadState.rootMentions.includes(a.name)) {
-        matches.push(a)
+      const senderAgent = agents.find((x) => x.userId === event.sender)
+      if (senderAgent) {
+        // Agent reply = a "return": route only to the agent that called the
+        // 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)
+      } 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.
+        const lastPoster = threadState.participants.at(-1)
+        if (lastPoster) {
+          if (lastPoster === a.name) matches.push(a)
+        } else if (threadState.rootMentions.includes(a.name)) {
+          matches.push(a)
+        }
       }
     }
   }