@zooid/transport-matrix 0.9.0 → 0.10.0

package/src/sync-loop.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest'
+import { SyncLoop } from './sync-loop.js'
+
+const evt = (id: string, roomId: string) => ({
+  type: 'm.room.message',
+  event_id: id,
+  sender: '@me:zoon.eco',
+  room_id: roomId,
+  content: { msgtype: 'm.text', body: 'hi' },
+})
+
+function fakeClient(pages: unknown[]) {
+  let i = 0
+  return {
+    sync: vi.fn(async () => pages[Math.min(i++, pages.length - 1)]),
+  }
+}
+
+describe('SyncLoop', () => {
+  it('dispatches each timeline event once and persists next_batch', async () => {
+    const store = new Map<string, string>()
+    const dispatched: string[] = []
+    const client = fakeClient([
+      { next_batch: 's1', rooms: { join: { '!r': { timeline: { events: [evt('a', '!r')] } } } } },
+      { next_batch: 's2', rooms: { join: { '!r': { timeline: { events: [evt('b', '!r')] } } } } },
+      { next_batch: 's2', rooms: { join: {} } },
+    ])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: (e) => dispatched.push(e.event_id as string),
+    })
+    await loop.tick()
+    await loop.tick()
+    expect(dispatched).toEqual(['a', 'b'])
+    expect(store.get('docs')).toBe('s2')
+  })
+
+  it('resumes from the persisted since (no reprocessing across restart)', async () => {
+    const store = new Map<string, string>([['docs', 's-persisted']])
+    const client = fakeClient([{ next_batch: 's3', rooms: { join: {} } }])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: () => {},
+    })
+    await loop.tick()
+    expect((client.sync as ReturnType<typeof vi.fn>).mock.calls[0][0].since).toBe('s-persisted')
+  })
+
+  it('tolerates an idle sync with no `rooms` key (real homeservers omit it)', async () => {
+    const store = new Map<string, string>()
+    const dispatched: string[] = []
+    // Real Tuwunel returns just { next_batch } on an idle incremental sync.
+    const client = fakeClient([{ next_batch: 's-idle' }])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: (e) => dispatched.push(e.event_id as string),
+    })
+    await expect(loop.tick()).resolves.toBeUndefined()
+    expect(dispatched).toEqual([])
+    expect(store.get('docs')).toBe('s-idle') // cursor still advances
+  })
+
+  it('tolerates a joined room with no `timeline` (state/ephemeral-only update)', async () => {
+    const store = new Map<string, string>()
+    const dispatched: string[] = []
+    // A room can appear in rooms.join carrying only state — no timeline key.
+    const client = fakeClient([
+      { next_batch: 's-state', rooms: { join: { '!r': { state: { events: [] } } } } },
+    ])
+    const loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => store.get('docs') ?? null,
+      saveSince: (s) => store.set('docs', s),
+      onEvent: (e) => dispatched.push(e.event_id as string),
+    })
+    await expect(loop.tick()).resolves.toBeUndefined()
+    expect(dispatched).toEqual([])
+    expect(store.get('docs')).toBe('s-state')
+  })
+
+  it('run() survives a throwing tick and keeps going (no daemon crash)', async () => {
+    let calls = 0
+    let loop!: SyncLoop
+    const client = {
+      sync: vi.fn(async () => {
+        calls++
+        if (calls === 1) throw new Error('transient /sync 502')
+        loop.stop() // recovered on the 2nd tick — end the loop deterministically
+        return { next_batch: 's-ok' }
+      }),
+    }
+    loop = new SyncLoop({
+      client: client as never,
+      asUserId: '@laptop.docs:zoon.eco',
+      loadSince: () => null,
+      saveSince: () => {},
+      onEvent: () => {},
+      retryDelayMs: 1,
+    })
+    await loop.run() // tick 1 throws → backoff → tick 2 recovers → stop → exits
+    expect(calls).toBe(2)
+  })
+})

package/src/sync-loop.ts

@@ -0,0 +1,74 @@
+export interface SyncResponse {
+  next_batch: string
+  // Real homeservers omit `rooms` (and `rooms.join`) entirely on an idle
+  // incremental sync — both are optional.
+  rooms?: {
+    join?: Record<string, {
+      // A joined room may carry only state/ephemeral/account_data on a given
+      // sync, with no `timeline` (or a timeline with no `events`).
+      timeline?: {
+        events?: Record<string, unknown>[]
+        prev_batch?: string
+        limited?: boolean
+      }
+    }>
+  }
+}
+
+export interface SyncClient {
+  sync(opts: { asUserId: string; since: string | null; timeoutMs: number }): Promise<SyncResponse>
+}
+
+export interface SyncLoopOptions {
+  client: SyncClient
+  asUserId: string
+  loadSince: () => string | null
+  saveSince: (since: string) => void
+  onEvent: (evt: Record<string, unknown>) => void | Promise<void>
+  timeoutMs?: number
+  /** Backoff after a failed tick before retrying. Default 5000ms. */
+  retryDelayMs?: number
+}
+
+export class SyncLoop {
+  private readonly opts: SyncLoopOptions
+  private running = false
+
+  constructor(opts: SyncLoopOptions) {
+    this.opts = opts
+  }
+
+  async tick(): Promise<void> {
+    const since = this.opts.loadSince()
+    const res = await this.opts.client.sync({
+      asUserId: this.opts.asUserId,
+      since,
+      timeoutMs: this.opts.timeoutMs ?? 30_000,
+    })
+    for (const [roomId, roomState] of Object.entries(res.rooms?.join ?? {})) {
+      for (const baseEvt of roomState.timeline?.events ?? []) {
+        await this.opts.onEvent({ ...(baseEvt as Record<string, unknown>), room_id: roomId })
+      }
+    }
+    this.opts.saveSince(res.next_batch)
+  }
+
+  async run(): Promise<void> {
+    this.running = true
+    while (this.running) {
+      try {
+        await this.tick()
+      } catch (err) {
+        // A transient /sync failure (network blip, sleep/wake, 5xx) must not
+        // kill the loop — log and back off, then resume from the same `since`.
+        if (!this.running) break
+        console.warn(`[sync-loop] ${this.opts.asUserId} tick failed, retrying:`, err)
+        await new Promise((r) => setTimeout(r, this.opts.retryDelayMs ?? 5_000))
+      }
+    }
+  }
+
+  stop(): void {
+    this.running = false
+  }
+}

package/src/transport.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest'
 import { EventEmitter } from 'node:events'
-import { createMatrixTransport } from './transport.js'
+import { createMatrixTransport, rebuildThreadState } from './transport.js'
 
 function fakeRegistry() {
   let resolvePrompt: (() => void) | undefined
@@ -1683,3 +1683,109 @@ describe('ad-hoc bot invite declines', () => {
     expect(client.leaveRoom).not.toHaveBeenCalled()
   })
 })
+
+describe('directional agent-to-agent handoffs', () => {
+  const parentSub = [
+    {
+      name: 'parent',
+      userId: '@parent:example.com',
+      rooms: [{ alias: '!r:example.com' }],
+      trigger: 'mention' as const,
+    },
+    {
+      name: 'sub',
+      userId: '@sub:example.com',
+      rooms: [{ alias: '!r:example.com' }],
+      trigger: 'mention' as const,
+    },
+  ]
+
+  function makePairTransport() {
+    const { reg } = fakeRegistry()
+    const approvals = fakeApprovals()
+    const client = fakeClient()
+    // Resolve prompts immediately so runTurn completes and `participants` append.
+    reg.prompt.mockImplementation(async () => ({ stopReason: 'end_turn' as const }))
+    const transport = createMatrixTransport({
+      agents: reg as never,
+      approvals: approvals as never,
+      client: client as never,
+      bindings: parentSub,
+      hsToken: 'hs-secret',
+      botUserId: '@zooid:example.com',
+      drainQuietMs: 0,
+    })
+    return { transport, agents: reg, client }
+  }
+
+  // Post one m.room.message. Top-level unless `root` is given (then it's a
+  // thread reply on that root). `mentions` sets m.mentions.user_ids.
+  function post(
+    transport: ReturnType<typeof makePairTransport>['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 },
+      ],
+    })
+  }
+
+  it("a parent's ack does not re-trigger the sub, but the sub's reply notifies the parent", async () => {
+    const { transport, agents } = makePairTransport()
+
+    // 1. Human @mentions parent (top-level) → thread root is $root.
+    await post(transport, { id: '$root', sender: '@alice:example.com', mentions: ['@parent:example.com'] })
+    await settleTurn()
+
+    // 2. Parent replies in-thread @mentioning sub → sub is called; caller[sub]=parent.
+    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')
+
+    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')
+
+    agents.ensureSession.mockClear()
+
+    // 4. Parent replies bare (the "ack") → parent has no caller → routes to NOBODY.
+    //    This is the loop guard: sub is NOT re-triggered.
+    await post(transport, { id: '$p2', sender: '@parent:example.com', root: '$root' })
+    await settleTurn()
+    expect(agents.ensureSession).not.toHaveBeenCalled()
+  })
+
+  it('rebuildThreadState reconstructs caller[] from the timeline after a restart', async () => {
+    const client = {
+      // root: human @mentions parent (no caller — human sender).
+      fetchEvent: vi.fn(async () => ({
+        type: 'm.room.message',
+        sender: '@alice:example.com',
+        content: { 'm.mentions': { user_ids: ['@parent:example.com'] } },
+      })),
+      // thread: parent @mentions sub (caller[sub]=parent), then sub replies bare.
+      fetchThreadRelations: vi.fn(async () => ({
+        chunk: [
+          {
+            type: 'm.room.message',
+            sender: '@parent:example.com',
+            content: { 'm.mentions': { user_ids: ['@sub:example.com'] } },
+          },
+          { type: 'm.room.message', sender: '@sub:example.com', content: { body: 'ack' } },
+        ],
+      })),
+    }
+    const state = await rebuildThreadState(client as never, '!r:example.com', '$root', parentSub)
+    expect(state.callers).toEqual({ sub: 'parent' })
+    expect(state.rootMentions).toEqual(['parent', 'sub'])
+    expect(state.participants).toEqual(['parent', 'sub'])
+  })
+})