@zooid/context-mcp 0.13.0 → 0.14.0

package/src/mcp-server.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest'
 import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
 import { buildContextMcpServer } from './mcp-server.js'
-import type { TransportContextProvider } from '@zooid/core'
+import type { TaskActions, TransportContextProvider } from '@zooid/core'
 
 function makeProvider(over: Partial<TransportContextProvider> = {}): TransportContextProvider {
   return {
@@ -10,7 +10,18 @@ function makeProvider(over: Partial<TransportContextProvider> = {}): TransportCo
     getRecentThreads: async () => ({ threads: [], has_more: false }),
     getThreadHistory: async () => ({ messages: [], has_more: false }),
     getChannelMembers: async () => [],
-    getChannelInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+    getRoomInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+    getRooms: async () => [{ id: '!a:localhost', name: 'general', transport: 'matrix' }],
+    sendMessage: async () => ({ event_id: '$sent' }),
+    ...over,
+  }
+}
+
+function makeTasks(over: Partial<TaskActions> = {}): TaskActions {
+  return {
+    startTasks: async () => ({ results: [], notify: 'caller', delivery: 'd' }),
+    completeTask: async () => ({ status: 'recorded' }),
+    describeRole: async () => ({ is_task_assignee: false, can_start_task_threads: true }),
     ...over,
   }
 }
@@ -23,19 +34,121 @@ async function connect(server: ReturnType<typeof buildContextMcpServer>) {
 }
 
 describe('buildContextMcpServer', () => {
-  it('lists exactly five tools with the spec names', async () => {
-    const server = buildContextMcpServer({ resolve: async () => makeProvider() })
+  it('lists the read-only surface plus zooid_send_message and zooid_get_rooms when no task role is given', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+    })
     const client = await connect(server)
     const list = await client.listTools()
     expect(list.tools.map((t) => t.name).sort()).toEqual([
-      'zooid_get_channel_info',
       'zooid_get_history',
       'zooid_get_members',
       'zooid_get_recent_threads',
+      'zooid_get_room_info',
+      'zooid_get_rooms',
       'zooid_get_thread_history',
+      'zooid_send_message',
     ])
   })
 
+  it('renames the two tools that did not name Matrix primitives', async () => {
+    const server = buildContextMcpServer({ resolve: async () => makeProvider() })
+    const client = await connect(server)
+    const names = (await client.listTools()).tools.map((t) => t.name)
+    expect(names).toContain('zooid_get_room_info')
+    expect(names).not.toContain('zooid_get_channel_info')
+    expect(names).toContain('zooid_send_message')
+    expect(names).toContain('zooid_get_rooms')
+  })
+
+  it('registers start_task_threads but not complete_task for a non-assignee', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+      resolveTasks: async () => makeTasks(),
+      role: { is_task_assignee: false, can_start_task_threads: true },
+    })
+    const names = (await (await connect(server)).listTools()).tools.map((t) => t.name)
+    expect(names).toContain('zooid_start_task_threads')
+    expect(names).not.toContain('zooid_complete_task')
+  })
+
+  it('registers complete_task but not start_task_threads for an assignee', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+      resolveTasks: async () => makeTasks(),
+      role: { is_task_assignee: true, can_start_task_threads: false },
+    })
+    const names = (await (await connect(server)).listTools()).tools.map((t) => t.name)
+    expect(names).toContain('zooid_complete_task')
+    expect(names).not.toContain('zooid_start_task_threads')
+  })
+
+  it('omits both task tools when no role is resolved', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+      resolveTasks: async () => makeTasks(),
+    })
+    const names = (await (await connect(server)).listTools()).tools.map((t) => t.name)
+    expect(names).not.toContain('zooid_complete_task')
+    expect(names).not.toContain('zooid_start_task_threads')
+  })
+
+  it('start_task_threads returns the delivery contract verbatim', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+      resolveTasks: async () =>
+        makeTasks({
+          startTasks: async () => ({
+            results: [{ agent: 'reviewer', status: 'started', thread_id: '$t' }],
+            notify: 'caller',
+            delivery:
+              '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.',
+          }),
+        }),
+      role: { is_task_assignee: false, can_start_task_threads: true },
+    })
+    const client = await connect(server)
+    const res = await client.callTool({
+      name: 'zooid_start_task_threads',
+      arguments: { tasks: [{ agent: 'reviewer', prompt: 'review' }] },
+    })
+    const payload = JSON.parse((res.content as Array<{ text: string }>)[0].text)
+    expect(payload.notify).toBe('caller')
+    expect(payload.delivery).toMatch(/End your turn now/)
+  })
+
+  it('send_message forwards room, thread_id and text', async () => {
+    const sent: unknown[] = []
+    const server = buildContextMcpServer({
+      resolve: async () =>
+        makeProvider({
+          sendMessage: async (input) => {
+            sent.push(input)
+            return { event_id: '$e', thread_id: '$t' }
+          },
+        }),
+    })
+    const client = await connect(server)
+    await client.callTool({
+      name: 'zooid_send_message',
+      arguments: { room: '!a:localhost', thread_id: '$t', text: 'noted' },
+    })
+    expect(sent).toEqual([{ room: '!a:localhost', thread_id: '$t', text: 'noted' }])
+  })
+
+  it('zooid_get_rooms returns the provider payload', async () => {
+    const server = buildContextMcpServer({
+      resolve: async () =>
+        makeProvider({
+          getRooms: async () => [{ id: '!a:localhost', name: 'general', transport: 'matrix' }],
+        }),
+    })
+    const client = await connect(server)
+    const res = await client.callTool({ name: 'zooid_get_rooms', arguments: {} })
+    const payload = JSON.parse((res.content as Array<{ text: string }>)[0].text)
+    expect(payload).toEqual({ rooms: [{ id: '!a:localhost', name: 'general', transport: 'matrix' }] })
+  })
+
   it('zooid_get_history forwards limit + before and returns the page as text JSON', async () => {
     const calls: Array<{ limit?: number; before?: string }> = []
     const provider = makeProvider({
@@ -43,7 +156,13 @@ describe('buildContextMcpServer', () => {
         calls.push(opts)
         return {
           messages: [
-            { id: 'e1', sender: 'alice', text: 'hi', timestamp: 'T', is_agent: false },
+            {
+              id: 'e1',
+              sender: 'alice',
+              text: 'hi',
+              timestamp: 'T',
+              is_agent: false,
+            },
           ],
           next_before: 'cursor-2',
           has_more: true,
@@ -59,7 +178,15 @@ describe('buildContextMcpServer', () => {
     expect(calls).toEqual([{ limit: 10, before: 'cursor-1' }])
     const text = (res.content as Array<{ type: string; text: string }>)[0].text
     expect(JSON.parse(text)).toEqual({
-      messages: [{ id: 'e1', sender: 'alice', text: 'hi', timestamp: 'T', is_agent: false }],
+      messages: [
+        {
+          id: 'e1',
+          sender: 'alice',
+          text: 'hi',
+          timestamp: 'T',
+          is_agent: false,
+        },
+      ],
       next_before: 'cursor-2',
       has_more: true,
     })
@@ -75,7 +202,10 @@ describe('buildContextMcpServer', () => {
     })
     const server = buildContextMcpServer({ resolve: async () => provider })
     const client = await connect(server)
-    await client.callTool({ name: 'zooid_get_history', arguments: { limit: 5000 } })
+    await client.callTool({
+      name: 'zooid_get_history',
+      arguments: { limit: 5000 },
+    })
     expect(calls[0].limit).toBe(200)
   })
 
@@ -112,19 +242,31 @@ describe('buildContextMcpServer', () => {
     })
     const server = buildContextMcpServer({ resolve: async () => provider })
     const client = await connect(server)
-    const res = await client.callTool({ name: 'zooid_get_recent_threads', arguments: {} })
+    const res = await client.callTool({
+      name: 'zooid_get_recent_threads',
+      arguments: {},
+    })
     const payload = JSON.parse((res.content as Array<{ text: string }>)[0].text)
     expect(payload.threads[0]).toMatchObject({ id: '$root', reply_count: 4 })
   })
 
   it('zooid_get_thread_history forwards thread_id and limit/before', async () => {
-    const calls: Array<{ threadId: string; opts: { limit?: number; before?: string } }> = []
+    const calls: Array<{
+      threadId: string
+      opts: { limit?: number; before?: string }
+    }> = []
     const provider = makeProvider({
       getThreadHistory: async (_c, threadId, opts) => {
         calls.push({ threadId, opts })
         return {
           messages: [
-            { id: '$root', sender: 'alice', text: 'root', timestamp: 'T', is_agent: false },
+            {
+              id: '$root',
+              sender: 'alice',
+              text: 'root',
+              timestamp: 'T',
+              is_agent: false,
+            },
           ],
           has_more: false,
         }
@@ -136,36 +278,64 @@ describe('buildContextMcpServer', () => {
       name: 'zooid_get_thread_history',
       arguments: { thread_id: '$root', limit: 10 },
     })
-    expect(calls[0]).toEqual({ threadId: '$root', opts: { limit: 10, before: undefined } })
+    expect(calls[0]).toEqual({
+      threadId: '$root',
+      opts: { limit: 10, before: undefined },
+    })
   })
 
   it('zooid_get_thread_history surfaces a validation error when thread_id is missing', async () => {
-    const server = buildContextMcpServer({ resolve: async () => makeProvider() })
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+    })
     const client = await connect(server)
-    const res = await client.callTool({ name: 'zooid_get_thread_history', arguments: {} })
+    const res = await client.callTool({
+      name: 'zooid_get_thread_history',
+      arguments: {},
+    })
     expect(res.isError).toBe(true)
   })
 
-  it('zooid_get_members and zooid_get_channel_info return the provider payload', async () => {
+  it('zooid_get_members and zooid_get_room_info return the provider payload', async () => {
     const provider = makeProvider({
       getChannelMembers: async () => [
         { id: '@alice:hs', name: 'alice', is_agent: false },
-        { id: '@architect:hs', name: 'architect', is_agent: true, agent_name: 'architect' },
+        {
+          id: '@architect:hs',
+          name: 'architect',
+          is_agent: true,
+          agent_name: 'architect',
+        },
       ],
-      getChannelInfo: async () => ({ id: '!r:hs', name: 'general', transport: 'matrix' }),
+      getRoomInfo: async () => ({
+        id: '!r:hs',
+        name: 'general',
+        transport: 'matrix',
+      }),
     })
     const server = buildContextMcpServer({ resolve: async () => provider })
     const client = await connect(server)
 
-    const m = await client.callTool({ name: 'zooid_get_members', arguments: {} })
+    const m = await client.callTool({
+      name: 'zooid_get_members',
+      arguments: {},
+    })
     expect(JSON.parse((m.content as Array<{ text: string }>)[0].text)).toEqual({
       members: [
         { id: '@alice:hs', name: 'alice', is_agent: false },
-        { id: '@architect:hs', name: 'architect', is_agent: true, agent_name: 'architect' },
+        {
+          id: '@architect:hs',
+          name: 'architect',
+          is_agent: true,
+          agent_name: 'architect',
+        },
       ],
     })
 
-    const i = await client.callTool({ name: 'zooid_get_channel_info', arguments: {} })
+    const i = await client.callTool({
+      name: 'zooid_get_room_info',
+      arguments: {},
+    })
     expect(JSON.parse((i.content as Array<{ text: string }>)[0].text)).toEqual({
       id: '!r:hs',
       name: 'general',
@@ -180,7 +350,41 @@ describe('buildContextMcpServer', () => {
       },
     })
     const client = await connect(server)
-    const res = await client.callTool({ name: 'zooid_get_history', arguments: {} })
+    const res = await client.callTool({
+      name: 'zooid_get_history',
+      arguments: {},
+    })
     expect(res.isError).toBe(true)
   })
+
+  it('exposes task writes only when the daemon supplies task actions and a matching role', async () => {
+    const calls: unknown[] = []
+    const server = buildContextMcpServer({
+      resolve: async () => makeProvider(),
+      resolveTasks: async () =>
+        makeTasks({
+          startTasks: async (_caller, input) => {
+            calls.push(input)
+            return {
+              results: [{ agent: 'worker', status: 'started', thread_id: '$task' }],
+              notify: 'caller',
+              delivery: 'd',
+            }
+          },
+        }),
+      role: { is_task_assignee: false, can_start_task_threads: true },
+    })
+    const client = await connect(server)
+    expect((await client.listTools()).tools.map((t) => t.name)).toContain(
+      'zooid_start_task_threads',
+    )
+    const result = await client.callTool({
+      name: 'zooid_start_task_threads',
+      arguments: { tasks: [{ agent: 'worker', prompt: 'audit' }] },
+    })
+    expect(calls).toEqual([{ tasks: [{ agent: 'worker', prompt: 'audit' }], notify: 'caller' }])
+    expect(JSON.parse((result.content as Array<{ text: string }>)[0].text)).toMatchObject({
+      results: [{ thread_id: '$task' }],
+    })
+  })
 })

package/src/mcp-server.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { TransportContextProvider } from '@zooid/core'
+import type { TaskActions, TaskCallerRef, TaskRole, TransportContextProvider } from '@zooid/core'
 
 const MAX_LIMIT = 200
 const DEFAULT_LIMIT = 50
@@ -12,6 +12,21 @@ export interface BuildContextMcpServerOpts {
    * fake provider directly.
    */
   resolve: () => Promise<TransportContextProvider>
+  resolveTasks?: () => Promise<TaskActions>
+  /**
+   * What this session is, queried once before the server is built. Absent =
+   * neither task tool is registered — the safe direction for MCP, since the
+   * tools are additive and a spawn that can't reach the daemon can't
+   * usefully call them anyway ([[ZOD084]]).
+   */
+  role?: TaskRole
+}
+// The socket substitutes its authenticated spawn binding; models never supply an address.
+const CALLER_FROM_BINDING: TaskCallerRef = {
+  agentName: '',
+  channelId: '',
+  threadRoot: '',
+  sessionKey: '',
 }
 
 export function buildContextMcpServer(opts: BuildContextMcpServerOpts): McpServer {
@@ -19,7 +34,7 @@ export function buildContextMcpServer(opts: BuildContextMcpServerOpts): McpServe
 
   server.tool(
     'zooid_get_history',
-    "Read every message in the current room chronologically — top-level messages and all thread replies. Each message has an optional `thread_id` so the agent can group by thread. For a scan-the-room overview without reply noise, use `zooid_get_recent_threads` instead. Supports `limit` + `before` pagination.",
+    'Read every message in the current room chronologically — top-level messages and all thread replies. Each message has an optional `thread_id` so the agent can group by thread. For a scan-the-room overview without reply noise, use `zooid_get_recent_threads` instead. Supports `limit` + `before` pagination.',
     {
       limit: z.number().int().positive().optional(),
       before: z.string().optional(),
@@ -27,11 +42,47 @@ export function buildContextMcpServer(opts: BuildContextMcpServerOpts): McpServe
     async ({ limit, before }) => {
       const provider = await opts.resolve()
       const clamped = Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)
-      const page = await provider.getRoomHistory('', { limit: clamped, before })
+      const page = await provider.getRoomHistory('', {
+        limit: clamped,
+        before,
+      })
       return { content: [{ type: 'text', text: JSON.stringify(page) }] }
     },
   )
 
+  if (opts.resolveTasks && opts.role?.can_start_task_threads) {
+    server.tool(
+      'zooid_start_task_threads',
+      'Assign concurrent work to other agents in this room. Each task opens a separate thread. The return payload states how the result comes back — read `delivery` before deciding what to do next.',
+      {
+        tasks: z.array(z.object({ agent: z.string(), prompt: z.string() })).min(1),
+        notify: z.enum(['caller', 'none']).optional(),
+      },
+      async ({ tasks, notify }) => {
+        const out = await opts.resolveTasks!().then((actions) =>
+          actions.startTasks(CALLER_FROM_BINDING, {
+            tasks,
+            notify: notify ?? 'caller',
+          }),
+        )
+        return { content: [{ type: 'text', text: JSON.stringify(out) }] }
+      },
+    )
+  }
+  if (opts.resolveTasks && opts.role?.is_task_assignee) {
+    server.tool(
+      'zooid_complete_task',
+      'Record an explicit result for the delegated task you were assigned.',
+      { summary: z.string().min(1) },
+      async ({ summary }) => {
+        const out = await opts.resolveTasks!().then((actions) =>
+          actions.completeTask(CALLER_FROM_BINDING, { summary }),
+        )
+        return { content: [{ type: 'text', text: JSON.stringify(out) }] }
+      },
+    )
+  }
+
   server.tool(
     'zooid_get_recent_threads',
     "Scan-the-room overview: top-level messages and thread roots in the current room, newest first. Each entry has `reply_count` and `last_activity_at` so the agent can spot active conversations. Drill into a thread with `zooid_get_thread_history(thread_id)` where `thread_id` is the entry's `id`.",
@@ -42,14 +93,17 @@ export function buildContextMcpServer(opts: BuildContextMcpServerOpts): McpServe
     async ({ limit, before }) => {
       const provider = await opts.resolve()
       const clamped = Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)
-      const page = await provider.getRecentThreads('', { limit: clamped, before })
+      const page = await provider.getRecentThreads('', {
+        limit: clamped,
+        before,
+      })
       return { content: [{ type: 'text', text: JSON.stringify(page) }] }
     },
   )
 
   server.tool(
     'zooid_get_thread_history',
-    "Drill into a specific thread: the root message followed by all replies in chronological order. Pass the `thread_id` from a `zooid_get_recent_threads` entry or a `Message.thread_id` from `zooid_get_history`.",
+    'Drill into a specific thread: the root message followed by all replies in chronological order. Pass the `thread_id` from a `zooid_get_recent_threads` entry or a `Message.thread_id` from `zooid_get_history`.',
     {
       thread_id: z.string(),
       limit: z.number().int().positive().optional(),
@@ -78,15 +132,41 @@ export function buildContextMcpServer(opts: BuildContextMcpServerOpts): McpServe
   )
 
   server.tool(
-    'zooid_get_channel_info',
+    'zooid_get_room_info',
     'Describe the current room: id, display name, transport kind.',
     {},
     async () => {
       const provider = await opts.resolve()
-      const info = await provider.getChannelInfo('')
+      const info = await provider.getRoomInfo('')
       return { content: [{ type: 'text', text: JSON.stringify(info) }] }
     },
   )
 
+  server.tool(
+    'zooid_get_rooms',
+    'List the rooms this agent is a member of. Valid targets for zooid_send_message.',
+    {},
+    async () => {
+      const provider = await opts.resolve()
+      const rooms = await provider.getRooms()
+      return { content: [{ type: 'text', text: JSON.stringify({ rooms }) }] }
+    },
+  )
+
+  server.tool(
+    'zooid_send_message',
+    'Post a message into a room or thread this agent is bound to. Fire-and-forget: no assignee, no completion tracking, no notify. Use zooid_start_task_threads instead when the intent is delegation.',
+    {
+      room: z.string(),
+      thread_id: z.string().optional(),
+      text: z.string(),
+    },
+    async ({ room, thread_id, text }) => {
+      const provider = await opts.resolve()
+      const result = await provider.sendMessage({ room, thread_id, text })
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+    },
+  )
+
   return server
 }

package/src/socket-paths.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { agentSocketPath, MAX_RUN_DIR, SUN_PATH_MAX } from './socket-paths.js'
+
+describe('agentSocketPath', () => {
+  it('is stable, fixed-width, and safely within sun_path', () => {
+    const path = agentSocketPath({ runDir: '/data/run', agentName: 'zooid-assistant' })
+    expect(path).toBe(agentSocketPath({ runDir: '/data/run', agentName: 'zooid-assistant' }))
+    expect(path).toMatch(/^\/data\/run\/context-[0-9a-f]{12}\.sock$/)
+    expect(path.length).toBeLessThanOrEqual(SUN_PATH_MAX)
+  })
+
+  it('separates punctuation and case without spending extra path budget', () => {
+    const paths = ['Ops/Team #1', 'ops team 1', 'ops-team-1'].map((agentName) =>
+      agentSocketPath({ runDir: '/data/run', agentName }),
+    )
+    expect(new Set(paths).size).toBe(3)
+    expect(new Set(paths.map((path) => path.length)).size).toBe(1)
+  })
+
+  it('accepts the documented run-dir limit and rejects one byte beyond it', () => {
+    const ok = '/' + 'x'.repeat(MAX_RUN_DIR - 1)
+    expect(() => agentSocketPath({ runDir: ok, agentName: 'a' })).not.toThrow()
+    expect(() => agentSocketPath({ runDir: `${ok}x`, agentName: 'a' })).toThrow(/exceeds the \d+-byte limit/)
+  })
+})

package/src/socket-paths.ts

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+
+/** Maximum pathname bytes accepted by Unix-domain sockets, excluding its NUL. */
+export const SUN_PATH_MAX = process.platform === 'darwin' ? 103 : 107
+
+/** `context-` + twelve hex characters + `.sock`. */
+const BASENAME_LEN = 25
+
+/** Longest run directory which can hold one of this module's sockets. */
+export const MAX_RUN_DIR = SUN_PATH_MAX - 1 - BASENAME_LEN
+
+/**
+ * Return a deterministic, fixed-width socket pathname for an agent.
+ *
+ * Hashing keeps arbitrary agent names out of the Unix socket path and leaves a
+ * predictable amount of `sun_path` room for the daemon data directory.
+ */
+export function agentSocketPath(opts: { runDir: string; agentName: string }): string {
+  if (opts.runDir.length > MAX_RUN_DIR) {
+    throw new Error(
+      `[context-mcp] run dir ${opts.runDir} (${opts.runDir.length} bytes) exceeds ` +
+        `the ${MAX_RUN_DIR}-byte limit — unix socket paths cap at ${SUN_PATH_MAX + 1} bytes. ` +
+        `Move the data dir closer to the filesystem root.`,
+    )
+  }
+  const hash = createHash('sha256').update(opts.agentName).digest('hex').slice(0, 12)
+  return join(opts.runDir, `context-${hash}.sock`)
+}

package/src/spawn-registry.test.ts

@@ -7,7 +7,9 @@ const fakeProvider: TransportContextProvider = {
   getRecentThreads: async () => ({ threads: [], has_more: false }),
   getThreadHistory: async () => ({ messages: [], has_more: false }),
   getChannelMembers: async () => [],
-  getChannelInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+  getRoomInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+  getRooms: async () => [],
+  sendMessage: async () => ({ event_id: '$sent' }),
 }
 
 describe('SpawnRegistry', () => {
@@ -55,4 +57,15 @@ describe('SpawnRegistry', () => {
     const r = new SpawnRegistry()
     expect(r.get('not-a-real-id')).toBeUndefined()
   })
+
+  it('resolves bindings by ACP session after linking without crossing agents', () => {
+    const r = new SpawnRegistry()
+    const a = r.register({ agentName: 'a', threadRef: { channelId: 'c', threadId: 't' }, sessionKey: 't', provider: fakeProvider })
+    const b = r.register({ agentName: 'b', threadRef: { channelId: 'c', threadId: 't' }, sessionKey: 't', provider: fakeProvider })
+    r.linkSession('a', 't', 'acp-a')
+    r.linkSession('b', 't', 'acp-b')
+    expect(r.getByAcpSession('acp-a')?.spawnId).toBe(a)
+    expect(r.getByAcpSession('acp-b')?.spawnId).toBe(b)
+    expect(r.getByAcpSession('orphan')).toBeUndefined()
+  })
 })

package/src/spawn-registry.ts

@@ -1,17 +1,22 @@
 import { randomUUID } from 'node:crypto'
 import type { SpawnBinding } from './types.js'
-import type { TransportContextProvider, ThreadRef } from '@zooid/core'
+import type { TaskActions, TransportContextProvider, ThreadRef } from '@zooid/core'
 
 export class SpawnRegistry {
   private readonly bindings = new Map<string, SpawnBinding>()
+  private readonly spawnByAgentSession = new Map<string, string>()
+  private readonly spawnByAcpSession = new Map<string, string>()
+  private tasks: TaskActions | undefined
 
   register(input: {
     agentName: string
     threadRef: ThreadRef
     provider: TransportContextProvider
+    sessionKey?: string
   }): string {
     const spawnId = randomUUID()
     this.bindings.set(spawnId, { spawnId, ...input })
+    this.spawnByAgentSession.set(this.key(input.agentName, input.sessionKey ?? input.threadRef.threadId), spawnId)
     return spawnId
   }
 
@@ -21,5 +26,28 @@ export class SpawnRegistry {
 
   release(spawnId: string): void {
     this.bindings.delete(spawnId)
+    for (const [key, value] of this.spawnByAgentSession) {
+      if (value === spawnId) this.spawnByAgentSession.delete(key)
+    }
+    for (const [key, value] of this.spawnByAcpSession) {
+      if (value === spawnId) this.spawnByAcpSession.delete(key)
+    }
+  }
+  linkSession(agentName: string, sessionKey: string, acpSessionId: string): void {
+    const spawnId = this.spawnByAgentSession.get(this.key(agentName, sessionKey))
+    if (spawnId) this.spawnByAcpSession.set(acpSessionId, spawnId)
+  }
+  getByAcpSession(acpSessionId: string): SpawnBinding | undefined {
+    const spawnId = this.spawnByAcpSession.get(acpSessionId)
+    return spawnId ? this.bindings.get(spawnId) : undefined
+  }
+  setTaskActions(actions: TaskActions | undefined): void {
+    this.tasks = actions
+  }
+  get taskActions(): TaskActions | undefined {
+    return this.tasks
+  }
+  private key(agentName: string, sessionKey: string): string {
+    return `${agentName}::${sessionKey}`
   }
 }

package/src/types.ts

@@ -9,6 +9,8 @@ export interface SpawnBinding {
   agentName: string
   threadRef: ThreadRef
   provider: TransportContextProvider
+  /** Exact ACP session key; the thread reference remains the context root. */
+  sessionKey?: string
 }
 
 /** Shape we pass into ACP `session/new mcpServers[]`. */