@zooid/transport-matrix 0.12.0 → 0.14.0

package/package.json

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

package/src/context-provider.test.ts

@@ -155,7 +155,7 @@ describe('MatrixContextProvider', () => {
     ])
   })
 
-  it('getChannelInfo returns the room name and transport: matrix', async () => {
+  it('getRoomInfo returns the room name and transport: matrix', async () => {
     const client = fakeClient({
       fetchRoomName: vi.fn().mockResolvedValue('engineering'),
     } as unknown as Partial<MatrixClient>)
@@ -164,10 +164,67 @@ describe('MatrixContextProvider', () => {
       asUserId: '@_zooid:hs',
       agentBots: new Map(),
     })
-    const info = await provider.getChannelInfo('!room:hs')
+    const info = await provider.getRoomInfo('!room:hs')
     expect(info).toEqual({ id: '!room:hs', name: 'engineering', transport: 'matrix' })
   })
 
+  it('getRooms maps this agent\'s own room bindings to RoomInfo, fetching each name', async () => {
+    const fetchRoomName = vi.fn().mockResolvedValueOnce('general').mockResolvedValueOnce('dev')
+    const client = fakeClient({ fetchRoomName } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+      rooms: [{ alias: '!a:hs' }, { alias: '!b:hs' }],
+    })
+    const rooms = await provider.getRooms()
+    expect(rooms).toEqual([
+      { id: '!a:hs', name: 'general', transport: 'matrix' },
+      { id: '!b:hs', name: 'dev', transport: 'matrix' },
+    ])
+    expect(fetchRoomName).toHaveBeenCalledWith('!a:hs', '@architect:hs')
+  })
+
+  it('getRooms returns an empty list when the provider has no room bindings', async () => {
+    const provider = new MatrixContextProvider({
+      client: fakeClient(),
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+    })
+    expect(await provider.getRooms()).toEqual([])
+  })
+
+  it('sendMessage posts as this agent into a bound room, echoing thread_id when replying in-thread', async () => {
+    const sendMessage = vi.fn().mockResolvedValue({ event_id: '$sent' })
+    const client = fakeClient({ sendMessage } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+      rooms: [{ alias: '!a:hs' }],
+    })
+    const result = await provider.sendMessage({ room: '!a:hs', thread_id: '$root', text: 'noted' })
+    expect(result).toEqual({ event_id: '$sent', thread_id: '$root' })
+    expect(sendMessage).toHaveBeenCalledWith({
+      roomId: '!a:hs',
+      asUserId: '@architect:hs',
+      content: { msgtype: 'm.notice', body: 'noted' },
+      threadRoot: '$root',
+    })
+  })
+
+  it('sendMessage refuses a room this agent is not bound to', async () => {
+    const provider = new MatrixContextProvider({
+      client: fakeClient(),
+      asUserId: '@architect:hs',
+      agentBots: new Map(),
+      rooms: [{ alias: '!a:hs' }],
+    })
+    await expect(provider.sendMessage({ room: '!elsewhere:hs', text: 'hi' })).rejects.toThrow(
+      /not_in_room/,
+    )
+  })
+
   it('getRecentThreads returns top-level entries newest-first with bundled thread metadata, skipping thread replies', async () => {
     const client = fakeClient({
       fetchRoomMessages: vi.fn().mockResolvedValue({
@@ -311,7 +368,7 @@ describe('MatrixContextProvider', () => {
       asUserId: '@_zooid:hs',
       agentBots: new Map(),
     })
-    const info = await provider.getChannelInfo('!room:hs')
+    const info = await provider.getRoomInfo('!room:hs')
     expect(info.name).toBe('!room:hs')
   })
 
@@ -347,4 +404,122 @@ describe('MatrixContextProvider', () => {
     expect(byId.get('$img')?.text).toBe('[image: dog.jpg]')
     expect(byId.get('$file')?.text).toBe('[file: report.pdf]')
   })
+
+  it('renders agent prose sent as m.notice — ZNC025 §10 switches agent output to m.notice', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$e1',
+            sender: '@architect:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.notice', body: 'agent output' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+    const page = await provider.getRoomHistory('!room:hs', {})
+    expect(page.messages[0]?.text).toBe('agent output')
+  })
+
+  it('getRecentThreads keeps a thread rooted in an m.notice', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$root',
+            sender: '@architect:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.notice', body: 'agent thread root' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map([['@architect:hs', 'architect']]),
+    })
+    const page = await provider.getRecentThreads('!room:hs', { limit: 50 })
+    expect(page.threads.map((t) => t.id)).toEqual(['$root'])
+    expect(page.threads[0]?.text).toBe('agent thread root')
+  })
+})
+
+// The authorization boundary for context reads is the homeserver, not this
+// class: every read is impersonated as the *agent's own* Matrix user, so a room
+// or thread the agent isn't in fails at Matrix. Nothing asserted that, and a
+// stale doc comment claimed the opposite (that asUserId was the AS bot, which
+// can read every room) — so a refactor could have quietly swapped in the AS
+// user and turned a homeserver-enforced boundary into an honour system.
+describe('MatrixContextProvider — reads are impersonated as the agent', () => {
+  const AGENT = '@dev.assistant:hs'
+
+  function provider(overrides: Partial<MatrixClient>) {
+    return new MatrixContextProvider({
+      client: fakeClient(overrides),
+      asUserId: AGENT,
+      agentBots: new Map(),
+    })
+  }
+
+  it('threads the agent user through every read, never a different user', async () => {
+    const fetchRoomMessages = vi.fn().mockResolvedValue({ chunk: [], end: undefined })
+    const getJoinedMembers = vi.fn().mockResolvedValue({ joined: {} })
+    const fetchRoomName = vi.fn().mockResolvedValue('room')
+    const fetchEvent = vi.fn().mockResolvedValue(null)
+    const fetchThreadRelations = vi.fn().mockResolvedValue({ chunk: [], next_batch: undefined })
+    const p = provider({
+      fetchRoomMessages,
+      getJoinedMembers,
+      fetchRoomName,
+      fetchEvent,
+      fetchThreadRelations,
+    } as unknown as Partial<MatrixClient>)
+
+    await p.getRoomHistory('!room:hs', { limit: 10 })
+    await p.getRecentThreads('!room:hs', { limit: 10 })
+    await p.getThreadHistory('!room:hs', '$root', { limit: 10 })
+    await p.getChannelMembers('!room:hs')
+    await p.getRoomInfo('!room:hs')
+
+    expect(fetchRoomMessages.mock.calls.every(([a]) => a.asUserId === AGENT)).toBe(true)
+    expect(fetchThreadRelations).toHaveBeenCalledWith(expect.objectContaining({ asUserId: AGENT }))
+    // These two take the user as a positional argument, not a field.
+    expect(getJoinedMembers).toHaveBeenCalledWith('!room:hs', AGENT)
+    expect(fetchRoomName).toHaveBeenCalledWith('!room:hs', AGENT)
+    expect(fetchEvent).toHaveBeenCalledWith('!room:hs', '$root', AGENT)
+  })
+
+  // An agent naming a room it isn't in must fail loudly. Swallowing the error
+  // and returning `{ messages: [] }` would read as "empty room" to the model —
+  // indistinguishable from a real empty room, and it would hide the refusal.
+  it('propagates a homeserver refusal instead of returning an empty page', async () => {
+    const forbidden = new Error('fetchRoomMessages(!private:hs) failed: 403')
+    const p = provider({
+      fetchRoomMessages: vi.fn().mockRejectedValue(forbidden),
+    } as unknown as Partial<MatrixClient>)
+
+    await expect(p.getRoomHistory('!private:hs', { limit: 10 })).rejects.toThrow('403')
+  })
+
+  it('propagates a refusal on the thread path too', async () => {
+    const p = provider({
+      fetchEvent: vi.fn().mockResolvedValue(null),
+      fetchThreadRelations: vi
+        .fn()
+        .mockRejectedValue(new Error('fetchThreadRelations($x) failed: 403')),
+    } as unknown as Partial<MatrixClient>)
+
+    await expect(p.getThreadHistory('!private:hs', '$x', { limit: 10 })).rejects.toThrow('403')
+  })
 })

package/src/context-provider.ts

@@ -3,12 +3,15 @@ import type {
   HistoryOptions,
   HistoryPage,
   Member,
-  ChannelInfo,
+  RoomInfo,
+  SendMessageInput,
+  SendMessageResult,
   Message,
   ThreadOverview,
   ThreadOverviewPage,
 } from '@zooid/core'
 import type { MatrixClient } from './matrix-client.js'
+import type { RoomBinding } from '@zooid/core'
 
 interface MatrixMessageEvent {
   event_id: string
@@ -32,10 +35,30 @@ interface MatrixMessageEvent {
 
 export interface MatrixContextProviderOpts {
   client: MatrixClient
-  /** AS sender_localpart user (read access). */
+  /**
+   * The **agent's own** Matrix user (`@{workstation}.{name}:server`), which
+   * every read is impersonated as via `?user_id=`. Not the AS bot: that would
+   * read every room on the homeserver and make this class the only thing
+   * standing between an agent and someone else's conversation.
+   *
+   * This is load-bearing. It is what makes the homeserver — not our own
+   * bookkeeping — the authorization boundary for context reads, so a room or
+   * thread the agent is not in fails at Matrix with 403/404. Anything that
+   * widens who can name a room (a CLI, a new tool parameter) is safe only
+   * while this holds.
+   */
   asUserId: string
   /** Map of Matrix user IDs → agent names, for is_agent / agent_name flags. */
   agentBots: Map<string, string>
+  /**
+   * This agent's own room bindings — the live array `BotPool.bootstrap`
+   * rewrites `.alias` on in place, so reads through this field after
+   * bootstrap see canonical room IDs. Backs `getRooms()` and the
+   * `sendMessage()` authorization check. Absent/empty = no rooms known
+   * (context providers built before this field existed, or in tests that
+   * don't exercise either method).
+   */
+  rooms?: RoomBinding[]
 }
 
 export class MatrixContextProvider implements TransportContextProvider {
@@ -84,7 +107,14 @@ export class MatrixContextProvider implements TransportContextProvider {
     const threads: ThreadOverview[] = []
     for (const ev of chunk as unknown as MatrixMessageEvent[]) {
       if (ev.type !== 'm.room.message') continue
-      if (ev.content?.msgtype !== 'm.text' || typeof ev.content.body !== 'string') continue
+      // m.notice: agent prose sends as m.notice so
+      // .m.rule.suppress_notices silences the chunk storm server-side
+      // (ZNC025 §10) — a thread root sent by an agent must still surface here.
+      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 // skip thread replies
       const agent = this.opts.agentBots.get(ev.sender)
@@ -169,7 +199,8 @@ export class MatrixContextProvider implements TransportContextProvider {
       }
     }
 
-    if (msgtype !== 'm.text' || typeof body !== 'string') return null
+    // Agent prose sends as m.notice (ZNC025 §10); m.text is human prose.
+    if ((msgtype !== 'm.text' && msgtype !== 'm.notice') || typeof body !== 'string') return null
     return {
       id: ev.event_id,
       sender: ev.sender,
@@ -194,7 +225,7 @@ export class MatrixContextProvider implements TransportContextProvider {
     })
   }
 
-  async getChannelInfo(channelId: string): Promise<ChannelInfo> {
+  async getRoomInfo(channelId: string): Promise<RoomInfo> {
     const name = await this.opts.client.fetchRoomName(channelId, this.opts.asUserId)
     return {
       id: channelId,
@@ -202,4 +233,30 @@ export class MatrixContextProvider implements TransportContextProvider {
       transport: 'matrix',
     }
   }
+
+  async getRooms(): Promise<RoomInfo[]> {
+    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' as const }
+      }),
+    )
+  }
+
+  async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
+    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 } : {}) }
+  }
 }

package/src/event-encoders.test.ts

@@ -10,6 +10,7 @@ import {
   toPlanBody,
   toErrorBody,
   toAvailableCommandsBody,
+  toTurnEndBody,
 } from './event-encoders.js'
 
 describe('toToolCallBody', () => {
@@ -165,7 +166,6 @@ describe('toErrorBody', () => {
       threadRoot,
     )
     expect(body).toMatchObject({
-      msgtype: 'm.notice',
       body: '⚠ [auth_missing] Authentication required',
       session_id: 'sess-1',
       turn_id: 'turn-1',
@@ -179,6 +179,14 @@ describe('toErrorBody', () => {
     expect(body.recovery).toMatch(/^https:\/\/zooid\.dev\/docs\//)
   })
 
+  it('carries no msgtype — dev.zooid.error is not m.room.message, so the field is meaningless', () => {
+    const body = toErrorBody(
+      { kind: 'error', agentId: 'a', sessionId: 's', turnId: 't', code: 'auth_missing', message: 'x', transient: false },
+      threadRoot,
+    )
+    expect(body).not.toHaveProperty('msgtype')
+  })
+
   it('truncates message to 250 chars and detail to 2000 chars', () => {
     const body = toErrorBody(
       {
@@ -230,3 +238,63 @@ describe('toErrorBody', () => {
     expect(body.session_id).toBeUndefined()
   })
 })
+
+describe('toTurnEndBody', () => {
+  it('carries the produced_output flag ZOD076 reads', () => {
+    expect(toTurnEndBody({ agentId: 'claude', sessionId: 's1', producedOutput: true }, '$root')).toEqual({
+      body: 'claude finished',
+      agent_id: 'claude',
+      session_id: 's1',
+      produced_output: true,
+      'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
+    })
+  })
+
+  it('carries a preview of the final message — the prose itself never pushes', () => {
+    // Agent prose goes out as m.notice and is silenced by
+    // .m.rule.suppress_notices, so without this the only notification the user
+    // gets says an agent finished and nothing about what it said.
+    const out = toTurnEndBody(
+      { agentId: 'claude', sessionId: 's1', producedOutput: true, lastMessage: 'the deploy is green' },
+      '$root',
+    )
+    expect(out.last_message).toBe('the deploy is green')
+    // body stays the turn-boundary summary a generic Matrix client renders.
+    expect(out.body).toBe('claude finished')
+  })
+
+  it('collapses whitespace and truncates a long final message', () => {
+    const out = toTurnEndBody(
+      {
+        agentId: 'claude',
+        sessionId: 's1',
+        producedOutput: true,
+        lastMessage: '  line one\n\nline two   ' + 'x'.repeat(400),
+      },
+      '$root',
+    )
+    const preview = out.last_message as string
+    expect(preview.length).toBe(140)
+    expect(preview.startsWith('line one line two ')).toBe(true)
+    expect(preview).not.toContain('\n')
+  })
+
+  it('omits last_message entirely when the turn produced nothing', () => {
+    const out = toTurnEndBody({ agentId: 'claude', sessionId: 's1', producedOutput: false }, '$root')
+    expect('last_message' in out).toBe(false)
+  })
+
+  it('marks an empty turn', () => {
+    const out = toTurnEndBody(
+      { agentId: 'claude', sessionId: 's1', producedOutput: false },
+      '$root',
+    )
+    expect(out.produced_output).toBe(false)
+    expect(out.body).toBe('claude finished without output')
+  })
+
+  it('carries no msgtype — a vestigial m.notice here would collide with .m.rule.suppress_notices', () => {
+    const out = toTurnEndBody({ agentId: 'a', sessionId: 's', producedOutput: true }, '$r')
+    expect(out).not.toHaveProperty('msgtype')
+  })
+})

package/src/event-encoders.ts

@@ -91,7 +91,11 @@ type ErrorTap = Extract<TapEvent, { kind: 'error' }>
 export function toErrorBody(evt: ErrorTap, threadRoot: string): Record<string, unknown> {
   const msg = evt.message.slice(0, 250)
   const out: Record<string, unknown> = {
-    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: `⚠ [${evt.code}] ${msg}`,
     code: evt.code,
     message: msg,
@@ -106,3 +110,39 @@ export function toErrorBody(evt: ErrorTap, threadRoot: string): Record<string, u
   if (recovery) out.recovery = recovery
   return out
 }
+
+export interface TurnEnd {
+  agentId: string
+  sessionId: string
+  producedOutput: boolean
+  /** The turn's final assistant message, for the push notification's preview. */
+  lastMessage?: string
+}
+
+/** Push payloads are size-capped, and a notification body is glanceable or useless. */
+const PREVIEW_MAX = 140
+
+/**
+ * Turn-boundary marker for [[ZOD076]] and push notifications. Carries no
+ * `msgtype` — a vestigial one (as `toErrorBody` used to carry) would collide
+ * with `.m.rule.suppress_notices`'s type-agnostic match and silently swallow
+ * the event before the [[ZNC025]] agent push rule ever sees it.
+ */
+export function toTurnEndBody(evt: TurnEnd, threadRoot: string): Record<string, unknown> {
+  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 },
+  }
+}

package/src/index.ts

@@ -1,5 +1,9 @@
 export { MatrixClient } from './matrix-client.js'
-export type { MatrixClientOptions, SendMessageInput, SendCustomEventInput } from './matrix-client.js'
+export type {
+  MatrixClientOptions,
+  SendMessageInput,
+  SendCustomEventInput,
+} from './matrix-client.js'
 export { MatrixContextProvider } from './context-provider.js'
 export type { MatrixContextProviderOpts } from './context-provider.js'
 export { renderRegistration } from './registration.js'
@@ -22,7 +26,11 @@ 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 {
+  ensureDefaultChannel,
+  ensureWorkforceSpace,
+  serverNameFromMxid,
+} from './space-provisioner.js'
 export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {
   buildWorkforceRoster,
@@ -35,9 +43,21 @@ export type {
   PublisherHandle,
   StartOpts as StartWorkforcePublisherOpts,
 } from './workforce-publisher.js'
-export { MediaClient, parseMxcUri, MAX_INLINE_IMAGE_BYTES, INLINE_IMAGE_MIMES, MAX_DOWNLOAD_BYTES } from './media-client.js'
+export {
+  MediaClient,
+  parseMxcUri,
+  MAX_INLINE_IMAGE_BYTES,
+  INLINE_IMAGE_MIMES,
+  MAX_DOWNLOAD_BYTES,
+} from './media-client.js'
 export type { MediaClientOptions } from './media-client.js'
 export { PendingMediaStore, MAX_MEDIA_PER_TURN } from './pending-media.js'
 export type { PendingMediaItem } from './pending-media.js'
 export { writeAttachment } from './attachments.js'
 export type { WriteAttachmentInput } from './attachments.js'
+export { TaskRegistry, MAX_OPEN_TASKS_PER_ROOM } from './task-registry.js'
+export type { TaskRecord, TaskPhase, PersistedTask, TaskJournal } from './task-registry.js'
+export { InvocationRegistry } from './invocation-registry.js'
+export { evaluateCompletion } from './task-completion.js'
+export type { CompletionInputs, CompletionDecision, StopReason } from './task-completion.js'
+export { checkDelegable, buildAssignmentContent, renderCompletionPrompt, renderInvocationReturn } from './task-dispatch.js'

package/src/invocation-registry.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { InvocationRegistry } from './invocation-registry.js'
+
+describe('InvocationRegistry', () => {
+  it('tracks a handoff before its Matrix event exists and resolves exactly once', () => {
+    const registry = new InvocationRegistry({ newId: () => 'i1' })
+    const invocation = registry.open({ taskId: 't1', callerAgent: 'a', callerSessionKey: '$root', calleeAgent: 'b' })
+    expect(registry.outstandingFor('$root')).toHaveLength(1)
+    registry.attachCallEvent(invocation.invocationId, '$call', '$root|$call')
+    expect(registry.forCalleeSession('$root|$call')).toBe(invocation)
+    expect(registry.resolve(invocation.invocationId)).toBe(invocation)
+    expect(registry.resolve(invocation.invocationId)).toBeUndefined()
+  })
+  it('detects an outstanding ancestor and cancels late returns', () => {
+    const registry = new InvocationRegistry({ newId: () => 'i1' })
+    const invocation = registry.open({ taskId: 't1', callerAgent: 'a', callerSessionKey: '$root', calleeAgent: 'b' })
+    registry.attachCallEvent('i1', '$call', '$root|$call')
+    expect(registry.isOutstandingAncestor('$root|$call', 'a')).toBe(true)
+    registry.cancelForTask('t1')
+    expect(registry.resolve('i1')).toBeUndefined()
+  })
+})

package/src/invocation-registry.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto'
+import type { InvocationRecord } from '@zooid/core'
+
+export class InvocationRegistry {
+  private readonly records = new Map<string, InvocationRecord>()
+  private readonly byCallee = new Map<string, string>()
+  private readonly byEvent = new Map<string, string>()
+  constructor(private readonly opts: { newId?: () => string } = {}) {}
+  open(input: Omit<InvocationRecord, 'invocationId' | 'state'>): InvocationRecord {
+    const record = { invocationId: this.opts.newId?.() ?? randomUUID(), state: 'outstanding' as const, ...input }
+    this.records.set(record.invocationId, record)
+    return record
+  }
+  attachCallEvent(id: string, eventId: string, sessionKey: string) {
+    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: string) { return this.records.get(id) }
+  byCallEvent(eventId: string) { const id = this.byEvent.get(eventId); return id ? this.records.get(id) : undefined }
+  forCalleeSession(session: string) { const id = this.byCallee.get(session); return id ? this.records.get(id) : undefined }
+  outstandingFor(session: string) { return [...this.records.values()].filter(x => x.state === 'outstanding' && x.callerSessionKey === session) }
+  outstandingForTask(taskId: string) { return [...this.records.values()].filter(x => x.state === 'outstanding' && x.taskId === taskId) }
+  resolve(id: string) { const r = this.records.get(id); if (!r || r.state !== 'outstanding') return; r.state = 'returned'; return r }
+  cancelForTask(taskId: string) { const records = this.outstandingForTask(taskId); for (const r of records) r.state = 'cancelled'; return records }
+  ancestorAgents(session: string) {
+    const agents: string[] = [], seen = 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: string, agent: string) { return this.ancestorAgents(session).includes(agent) }
+}