@zooid/transport-matrix 0.11.0 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/transport-matrix",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "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/acp-client": "^0.11.0",
-    "@zooid/core": "^0.11.0"
+    "@zooid/acp-client": "^0.11.2",
+    "@zooid/core": "^0.11.2"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.0",

package/src/router.test.ts

@@ -142,7 +142,9 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
   }
 
   function states(s: Partial<ThreadState>): Map<string, ThreadState> {
-    return new Map([['$root', { participants: [], rootMentions: [], callers: {}, ...s }]])
+    return new Map([
+      ['$root', { participants: [], rootMentions: [], callers: {}, handoffs: {}, ...s }],
+    ])
   }
 
   it("routes a sub's bare reply up to its caller (parent notified)", () => {
@@ -225,3 +227,73 @@ describe('directional thread continuation (agent-to-agent handoffs)', () => {
     expect(matches).toEqual([])
   })
 })
+
+describe('fan-out: two subs called in one message ([[ZOD071]] acceptance)', () => {
+  const mk = (name: string): AgentBinding => ({
+    name,
+    userId: `@${name}:example.com`,
+    rooms: [{ alias: '!room1:example.com' }],
+    trigger: 'mention',
+  })
+  const parent = mk('parent')
+  const bebop = mk('bebop')
+  const rocksteady = mk('rocksteady')
+  const trio = [parent, bebop, rocksteady]
+
+  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: {}, handoffs: {}, ...s }],
+    ])
+  }
+
+  it('a single message @mentioning both subs triggers both (fan-out)', () => {
+    const matches = route(
+      threadMsg({
+        sender: '@parent:example.com',
+        mentions: ['@bebop:example.com', '@rocksteady:example.com'],
+      }),
+      trio,
+      states({ participants: ['parent'] }),
+    )
+    expect(matches.map((m) => m.name).sort()).toEqual(['bebop', 'rocksteady'])
+  })
+
+  it("bebop's bare return triggers only parent — never its sibling", () => {
+    const matches = route(
+      threadMsg({ sender: '@bebop:example.com' }),
+      trio,
+      states({
+        participants: ['parent', 'rocksteady', 'bebop'],
+        callers: { bebop: 'parent', rocksteady: 'parent' },
+      }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['parent'])
+  })
+
+  it("rocksteady's bare return likewise routes only up", () => {
+    const matches = route(
+      threadMsg({ sender: '@rocksteady:example.com' }),
+      trio,
+      states({
+        participants: ['parent', 'bebop', 'rocksteady'],
+        callers: { bebop: 'parent', rocksteady: 'parent' },
+      }),
+    )
+    expect(matches.map((m) => m.name)).toEqual(['parent'])
+  })
+})

package/src/router.ts

@@ -41,6 +41,13 @@ export interface ThreadState {
    * Implicit triggers → Directional continuation.
    */
   callers: Record<string, string>
+  /**
+   * Handoff arcs per sub-agent: the event ids of the agent→agent @mention
+   * messages that called it, in timeline order (last = current arc). Each
+   * call opens a fresh ACP session keyed `threadRoot|callEventId`
+   * ([[ZOD071]]). Append-only; rebuilt from the timeline after a restart.
+   */
+  handoffs: Record<string, string[]>
 }
 
 interface MaybeEvent {

package/src/session-keys.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { HANDOFF_KEY_SEP, composeHandoffKey, sessionKeyFor } from './session-keys.js'
+import type { ThreadState } from './router.js'
+
+const state = (handoffs: Record<string, string[]>): ThreadState => ({
+  participants: [],
+  rootMentions: [],
+  callers: {},
+  handoffs,
+})
+
+describe('composeHandoffKey', () => {
+  it('joins threadRoot and callEventId with the separator', () => {
+    expect(composeHandoffKey('$root', '$call')).toBe(`$root${HANDOFF_KEY_SEP}$call`)
+  })
+})
+
+describe('sessionKeyFor', () => {
+  it('returns the bare threadRoot when there is no thread state', () => {
+    expect(sessionKeyFor('bebop', '$root', undefined)).toBe('$root')
+  })
+
+  it('returns the bare threadRoot when the agent has never been called', () => {
+    expect(sessionKeyFor('bebop', '$root', state({}))).toBe('$root')
+  })
+
+  it('returns the arc key when the agent has been called', () => {
+    expect(sessionKeyFor('bebop', '$root', state({ bebop: ['$c1'] }))).toBe('$root|$c1')
+  })
+
+  it('a re-delegation wins: the LAST call is the current arc (Option A)', () => {
+    expect(sessionKeyFor('bebop', '$root', state({ bebop: ['$c1', '$c2'] }))).toBe('$root|$c2')
+  })
+
+  it("another agent's arcs do not leak onto this agent's key", () => {
+    // parent called bebop; parent's OWN key stays thread-level.
+    expect(sessionKeyFor('parent', '$root', state({ bebop: ['$c1'] }))).toBe('$root')
+  })
+})

package/src/session-keys.ts

@@ -0,0 +1,29 @@
+import type { ThreadState } from './router.js'
+
+/**
+ * Separator between a thread root and a handoff-arc call event id inside a
+ * session key. Matrix event IDs ('$' + URL-safe base64; legacy '$hash:domain')
+ * never contain '|', so composed keys are unambiguous — though nothing below
+ * the transport ever parses one: the key is opaque downstream ([[ZOD071]]).
+ */
+export const HANDOFF_KEY_SEP = '|'
+
+export function composeHandoffKey(threadRoot: string, callEventId: string): string {
+  return `${threadRoot}${HANDOFF_KEY_SEP}${callEventId}`
+}
+
+/**
+ * The session key for an agent's next turn in a thread: its latest handoff
+ * arc when it has been called (agent→agent @mention, [[ZOD071]]), else the
+ * thread-level key. Relies on the transaction handler recording the arc
+ * BEFORE the turn is dispatched, so a just-called sub resolves to the arc
+ * minted by its own triggering event.
+ */
+export function sessionKeyFor(
+  agentName: string,
+  threadRoot: string,
+  state: ThreadState | undefined,
+): string {
+  const arc = state?.handoffs[agentName]?.at(-1)
+  return arc ? composeHandoffKey(threadRoot, arc) : threadRoot
+}

package/src/transport.test.ts

@@ -139,7 +139,7 @@ describe('matrix transport /transactions', () => {
     expect(res.status).toBe(200)
     await settleTurn()
     // Agent-promotion: sessionKey is the inbound event_id, NOT the room.
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
     // The reply threads against the user's message.
     expect(client.sendMessage).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -229,7 +229,7 @@ describe('matrix transport /transactions', () => {
     })
     await postTxn(transport.app, { events })
     await settleTurn()
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
     expect(client.sendMessage).toHaveBeenCalledWith(
       expect.objectContaining({ threadRoot: '$root' }),
     )
@@ -425,7 +425,7 @@ describe('thread implicit triggers', () => {
     await settleTurn()
 
     // architect should be triggered implicitly because they posted in the thread.
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
   })
 
   it("inherits the thread root's @mentions when no agent has posted yet", async () => {
@@ -468,7 +468,7 @@ describe('thread implicit triggers', () => {
     })
     await settleTurn()
     // Inherits the root's @mention of architect.
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
   })
 
   it('does not trigger any agent for a bare top-level message', async () => {
@@ -533,7 +533,7 @@ describe('thread implicit triggers', () => {
       ],
     })
     await settleTurn()
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
   })
 })
 
@@ -634,7 +634,7 @@ describe('dev.zooid.session_reset', () => {
       ],
     })
     await settleTurn()
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
   })
 })
 
@@ -1391,7 +1391,7 @@ describe('full loop integration', () => {
       }],
     })
     await settleTurn()
-    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('architect', '$root', '!r:example.com', '$root')
     expect(client.sendMessage).toHaveBeenCalledWith(
       expect.objectContaining({ threadRoot: '$root' }),
     )
@@ -1742,17 +1742,18 @@ describe('directional agent-to-agent handoffs', () => {
     await settleTurn()
 
     // 2. Parent replies in-thread @mentioning sub → sub is called; caller[sub]=parent.
+    //    [[ZOD071]]: this call opens a fresh handoff arc for sub, keyed by $p1.
     await post(transport, { id: '$p1', sender: '@parent:example.com', root: '$root', mentions: ['@sub:example.com'] })
     await settleTurn()
-    expect(agents.ensureSession).toHaveBeenCalledWith('sub', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('sub', '$root|$p1', '!r:example.com', '$root')
 
     agents.ensureSession.mockClear()
 
     // 3. Sub replies bare → bubbles UP to its caller (parent), nobody else.
     await post(transport, { id: '$s1', sender: '@sub:example.com', root: '$root' })
     await settleTurn()
-    expect(agents.ensureSession).toHaveBeenCalledWith('parent', '$root', '!r:example.com')
-    expect(agents.ensureSession).not.toHaveBeenCalledWith('sub', '$root', '!r:example.com')
+    expect(agents.ensureSession).toHaveBeenCalledWith('parent', '$root', '!r:example.com', '$root')
+    expect(agents.ensureSession.mock.calls.map((c) => c[0])).not.toContain('sub')
 
     agents.ensureSession.mockClear()
 
@@ -1789,3 +1790,331 @@ describe('directional agent-to-agent handoffs', () => {
     expect(state.participants).toEqual(['parent', 'sub'])
   })
 })
+
+describe('per-handoff session isolation ([[ZOD071]])', () => {
+  const mkBinding = (name: string) => ({
+    name,
+    userId: `@${name}:example.com`,
+    rooms: [{ alias: '!r:example.com' }],
+    trigger: 'mention' as const,
+  })
+  const trio = [mkBinding('parent'), mkBinding('bebop'), mkBinding('rocksteady')]
+
+  function makeTrioTransport() {
+    const { reg } = fakeRegistry()
+    const approvals = fakeApprovals()
+    const client = fakeClient()
+    // Session ids must be unique per (agent, key) — the shared-prompt default
+    // fake returns `sess-${threadId}`, which would collide for two subs
+    // called by the same event (same composed key, different agent).
+    reg.ensureSession.mockImplementation(
+      async (name: string, threadId: string) => `sess-${name}-${threadId}`,
+    )
+    // Per-agent prompt gates: parent turns resolve immediately; sub turns stay
+    // open until released, so both arcs are provably IN FLIGHT at once.
+    const gates = new Map<string, () => void>()
+    reg.prompt.mockImplementation(async (name: string) => {
+      if (name === 'parent') return { stopReason: 'end_turn' as const }
+      return new Promise<{ stopReason: 'end_turn' }>((res) =>
+        gates.set(name, () => res({ stopReason: 'end_turn' as const })),
+      )
+    })
+    const transport = createMatrixTransport({
+      agents: reg as never,
+      approvals: approvals as never,
+      client: client as never,
+      bindings: trio,
+      hsToken: 'hs-secret',
+      botUserId: '@zooid:example.com',
+      drainQuietMs: 0,
+    })
+    return { transport, agents: reg, client, gates }
+  }
+
+  function post(
+    transport: ReturnType<typeof makeTrioTransport>['transport'],
+    o: { id: string; sender: string; root?: string; mentions?: string[] },
+  ) {
+    const content: Record<string, unknown> = { msgtype: 'm.text', body: 'x' }
+    if (o.mentions) content['m.mentions'] = { user_ids: o.mentions }
+    if (o.root) content['m.relates_to'] = { rel_type: 'm.thread', event_id: o.root }
+    return postTxn(transport.app, {
+      events: [
+        {
+          type: 'm.room.message',
+          event_id: o.id,
+          room_id: '!r:example.com',
+          sender: o.sender,
+          content,
+        },
+      ],
+    })
+  }
+
+  const agentsCalled = (reg: ReturnType<typeof fakeRegistry>['reg']) =>
+    reg.ensureSession.mock.calls.map((c) => c[0] as string)
+
+  it('fans out to two subs on one call event, runs their arcs concurrently with interleaved completion, and returns control to the parent once per sub', async () => {
+    const { transport, agents, gates } = makeTrioTransport()
+
+    // 1. Human @parent (top-level, $root) → parent gets the THREAD-LEVEL
+    //    session; the real threadRoot rides along as the context ref.
+    await post(transport, {
+      id: '$root',
+      sender: '@alice:example.com',
+      mentions: ['@parent:example.com'],
+    })
+    await settleTurn()
+    expect(agents.ensureSession).toHaveBeenCalledWith(
+      'parent',
+      '$root',
+      '!r:example.com',
+      '$root',
+    )
+
+    // 2. Parent calls BOTH subs in ONE message ($p1). Each sub gets a fresh
+    //    arc session keyed by the same call event id — the composed key
+    //    string is identical; the sessions are distinct via the agent
+    //    dimension (per-agent client/store).
+    await post(transport, {
+      id: '$p1',
+      sender: '@parent:example.com',
+      root: '$root',
+      mentions: ['@bebop:example.com', '@rocksteady:example.com'],
+    })
+    await settleTurn()
+    expect(agents.ensureSession).toHaveBeenCalledWith(
+      'bebop',
+      '$root|$p1',
+      '!r:example.com',
+      '$root',
+    )
+    expect(agents.ensureSession).toHaveBeenCalledWith(
+      'rocksteady',
+      '$root|$p1',
+      '!r:example.com',
+      '$root',
+    )
+    // Both sub turns are open simultaneously — the arcs are concurrent, not
+    // queued. Their thread events will interleave; that's the point.
+    expect(gates.size).toBe(2)
+
+    agents.ensureSession.mockClear()
+
+    // 3. Rocksteady finishes FIRST (reverse of call order — interleaved).
+    //    Its bare return routes ONLY to parent, resuming parent's continuous
+    //    thread-level session; the sibling is untouched.
+    gates.get('rocksteady')!()
+    await settleTurn()
+    await post(transport, { id: '$r1', sender: '@rocksteady:example.com', root: '$root' })
+    await settleTurn()
+    expect(agents.ensureSession).toHaveBeenCalledWith(
+      'parent',
+      '$root',
+      '!r:example.com',
+      '$root',
+    )
+    expect(agentsCalled(agents)).not.toContain('bebop')
+
+    agents.ensureSession.mockClear()
+
+    // 4. Bebop finishes second — same story, sibling untouched. Parent has
+    //    now been handed control exactly once per sub, both times in the
+    //    SAME thread-level session (it aggregates the two results).
+    gates.get('bebop')!()
+    await settleTurn()
+    await post(transport, { id: '$b1', sender: '@bebop:example.com', root: '$root' })
+    await settleTurn()
+    expect(agents.ensureSession).toHaveBeenCalledWith(
+      'parent',
+      '$root',
+      '!r:example.com',
+      '$root',
+    )
+    expect(agentsCalled(agents)).not.toContain('rocksteady')
+  })
+
+  it('re-delegating to the same sub opens a FRESH session (Option A: cold re-invoke)', async () => {
+    const { transport, agents, gates } = makeTrioTransport()
+
+    await post(transport, {
+      id: '$root',
+      sender: '@alice:example.com',
+      mentions: ['@parent:example.com'],
+    })
+    await settleTurn()
+
+    // First delegation: arc $p1.
+    await post(transport, {
+      id: '$p1',
+      sender: '@parent:example.com',
+      root: '$root',
+      mentions: ['@bebop:example.com'],
+    })
+    await settleTurn()
+    gates.get('bebop')!()
+    await settleTurn()
+    await post(transport, { id: '$b1', sender: '@bebop:example.com', root: '$root' })
+    await settleTurn()
+
+    // Second delegation: arc $p2 — a NEW session key, not a resume.
+    await post(transport, {
+      id: '$p2',
+      sender: '@parent:example.com',
+      root: '$root',
+      mentions: ['@bebop:example.com'],
+    })
+    await settleTurn()
+    gates.get('bebop')!()
+    await settleTurn()
+
+    const bebopKeys = agents.ensureSession.mock.calls
+      .filter((c) => c[0] === 'bebop')
+      .map((c) => c[1])
+    expect(bebopKeys).toEqual(['$root|$p1', '$root|$p2'])
+  })
+
+  it("a human bare reply to the last-posting sub resumes the sub's current arc", async () => {
+    const { transport, agents, gates } = makeTrioTransport()
+
+    await post(transport, {
+      id: '$root',
+      sender: '@alice:example.com',
+      mentions: ['@parent:example.com'],
+    })
+    await settleTurn()
+    await post(transport, {
+      id: '$p1',
+      sender: '@parent:example.com',
+      root: '$root',
+      mentions: ['@bebop:example.com'],
+    })
+    await settleTurn()
+    gates.get('bebop')!()
+    await settleTurn() // participants: [parent, bebop] — bebop is last poster
+
+    agents.ensureSession.mockClear()
+
+    // Human "why did you do X?" — routes to bebop (last poster) and lands in
+    // the session that DID the work, not a cold thread-level one.
+    await post(transport, { id: '$h1', sender: '@alice:example.com', root: '$root' })
+    await settleTurn()
+    expect(agents.ensureSession).toHaveBeenCalledWith(
+      'bebop',
+      '$root|$p1',
+      '!r:example.com',
+      '$root',
+    )
+  })
+
+  it('/clear (session_reset) ends the thread-level session AND every handoff arc', async () => {
+    const { transport, agents, gates } = makeTrioTransport()
+
+    await post(transport, {
+      id: '$root',
+      sender: '@alice:example.com',
+      mentions: ['@parent:example.com'],
+    })
+    await settleTurn()
+    await post(transport, {
+      id: '$p1',
+      sender: '@parent:example.com',
+      root: '$root',
+      mentions: ['@bebop:example.com', '@rocksteady:example.com'],
+    })
+    await settleTurn()
+    gates.get('bebop')!()
+    gates.get('rocksteady')!()
+    await settleTurn()
+
+    await postTxn(transport.app, {
+      events: [
+        {
+          type: 'dev.zooid.session_reset',
+          event_id: '$reset',
+          room_id: '!r:example.com',
+          sender: '@alice:example.com',
+          content: { 'm.relates_to': { rel_type: 'm.thread', event_id: '$root' } },
+        },
+      ],
+    })
+    await settleTurn()
+
+    const ended = agents.endSession.mock.calls.map((c) => `${c[0]}:${c[1]}`)
+    expect(ended).toContain('parent:$root')
+    expect(ended).toContain('bebop:$root')
+    expect(ended).toContain('rocksteady:$root')
+    expect(ended).toContain('bebop:$root|$p1')
+    expect(ended).toContain('rocksteady:$root|$p1')
+  })
+
+  it('/clear right after a restart rebuilds thread state so arc sessions are still ended', async () => {
+    const { transport, agents, client } = makeTrioTransport()
+    // No prior inbound events — simulate a daemon restart: threadStates is
+    // empty, but the timeline (via the client fetchers) knows the arc.
+    ;(client as unknown as Record<string, unknown>).fetchEvent = vi.fn(async () => ({
+      type: 'm.room.message',
+      sender: '@alice:example.com',
+      content: { 'm.mentions': { user_ids: ['@parent:example.com'] } },
+    }))
+    ;(client as unknown as Record<string, unknown>).fetchThreadRelations = vi.fn(async () => ({
+      chunk: [
+        {
+          type: 'm.room.message',
+          event_id: '$p1',
+          sender: '@parent:example.com',
+          content: { 'm.mentions': { user_ids: ['@bebop:example.com'] } },
+        },
+      ],
+    }))
+
+    await postTxn(transport.app, {
+      events: [
+        {
+          type: 'dev.zooid.session_reset',
+          event_id: '$reset',
+          room_id: '!r:example.com',
+          sender: '@alice:example.com',
+          content: { 'm.relates_to': { rel_type: 'm.thread', event_id: '$root' } },
+        },
+      ],
+    })
+    await settleTurn()
+
+    const ended = agents.endSession.mock.calls.map((c) => `${c[0]}:${c[1]}`)
+    expect(ended).toContain('bebop:$root')
+    expect(ended).toContain('bebop:$root|$p1')
+  })
+
+  it('rebuildThreadState reconstructs handoff arcs (multi-sub + re-delegation) from the timeline', async () => {
+    const client = {
+      fetchEvent: vi.fn(async () => ({
+        type: 'm.room.message',
+        sender: '@alice:example.com',
+        content: { 'm.mentions': { user_ids: ['@parent:example.com'] } },
+      })),
+      fetchThreadRelations: vi.fn(async () => ({
+        chunk: [
+          {
+            type: 'm.room.message',
+            event_id: '$p1',
+            sender: '@parent:example.com',
+            content: {
+              'm.mentions': { user_ids: ['@bebop:example.com', '@rocksteady:example.com'] },
+            },
+          },
+          { type: 'm.room.message', event_id: '$b1', sender: '@bebop:example.com', content: { body: 'done' } },
+          {
+            type: 'm.room.message',
+            event_id: '$p2',
+            sender: '@parent:example.com',
+            content: { 'm.mentions': { user_ids: ['@bebop:example.com'] } },
+          },
+        ],
+      })),
+    }
+    const state = await rebuildThreadState(client as never, '!r:example.com', '$root', trio)
+    expect(state.handoffs).toEqual({ bebop: ['$p1', '$p2'], rocksteady: ['$p1'] })
+    expect(state.callers).toEqual({ bebop: 'parent', rocksteady: 'parent' })
+  })
+})