@zooid/context-mcp 0.7.0

package/src/daemon-socket.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { SpawnRegistry } from './spawn-registry.js'
+import { startDaemonSocketServer, callDaemon } from './daemon-socket.js'
+import type { TransportContextProvider } from '@zooid/core'
+
+function fakeProvider(over: Partial<TransportContextProvider> = {}): TransportContextProvider {
+  return {
+    getRoomHistory: async () => ({ messages: [], has_more: false }),
+    getRecentThreads: async () => ({ threads: [], has_more: false }),
+    getThreadHistory: async () => ({ messages: [], has_more: false }),
+    getChannelMembers: async () => [],
+    getChannelInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+    ...over,
+  }
+}
+
+const defaultProvider = fakeProvider({
+  getRoomHistory: async () => ({
+    messages: [
+      { id: 'e1', sender: 'alice', text: 'hi', timestamp: '2026-05-11T00:00:00Z', is_agent: false },
+    ],
+    has_more: false,
+  }),
+  getChannelMembers: async () => [{ id: '@alice:hs', name: 'alice', is_agent: false }],
+  getChannelInfo: async () => ({ id: '!r:hs', name: 'general', transport: 'matrix' }),
+})
+
+const cleanup: Array<() => Promise<void>> = []
+afterEach(async () => {
+  for (const fn of cleanup) await fn()
+  cleanup.length = 0
+})
+
+describe('daemon-socket', () => {
+  it('routes a getRoomHistory call to the bound provider and returns the payload', async () => {
+    const registry = new SpawnRegistry()
+    const spawnId = registry.register({
+      agentName: 'a',
+      threadRef: { channelId: 'c', threadId: 't' },
+      provider: defaultProvider,
+    })
+    const sockPath = join(tmpdir(), `zooid-test-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    const res = await callDaemon(sockPath, {
+      spawnId,
+      method: 'getRoomHistory',
+      params: { limit: 50 },
+    })
+
+    expect(res).toEqual({
+      messages: [
+        { id: 'e1', sender: 'alice', text: 'hi', timestamp: '2026-05-11T00:00:00Z', is_agent: false },
+      ],
+      has_more: false,
+    })
+  })
+
+  it('routes getRecentThreads and getThreadHistory with thread metadata', async () => {
+    const provider = fakeProvider({
+      getRecentThreads: async () => ({
+        threads: [
+          {
+            id: '$root',
+            sender: 'alice',
+            text: 'kickoff',
+            timestamp: 'T',
+            is_agent: false,
+            reply_count: 2,
+            last_activity_at: 'T2',
+          },
+        ],
+        has_more: false,
+      }),
+      getThreadHistory: async (_c, threadId) => ({
+        messages: [
+          { id: threadId, sender: 'alice', text: 'root', timestamp: 'T', is_agent: false, thread_id: threadId },
+        ],
+        has_more: false,
+      }),
+    })
+    const registry = new SpawnRegistry()
+    const spawnId = registry.register({
+      agentName: 'a',
+      threadRef: { channelId: 'c', threadId: 't' },
+      provider,
+    })
+    const sockPath = join(tmpdir(), `zooid-test-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    const overview = (await callDaemon(sockPath, {
+      spawnId,
+      method: 'getRecentThreads',
+      params: {},
+    })) as { threads: Array<{ id: string; reply_count: number }> }
+    expect(overview.threads[0]).toMatchObject({ id: '$root', reply_count: 2 })
+
+    const detail = (await callDaemon(sockPath, {
+      spawnId,
+      method: 'getThreadHistory',
+      params: { threadId: '$root' },
+    })) as { messages: Array<{ id: string; thread_id: string }> }
+    expect(detail.messages[0]).toMatchObject({ id: '$root', thread_id: '$root' })
+  })
+
+  it('returns an error envelope for unknown spawn-ids', async () => {
+    const registry = new SpawnRegistry()
+    const sockPath = join(tmpdir(), `zooid-test-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    await expect(
+      callDaemon(sockPath, { spawnId: 'unknown', method: 'getRoomHistory', params: {} }),
+    ).rejects.toThrow(/unknown spawn/i)
+  })
+
+  it('routes getChannelMembers and getChannelInfo', async () => {
+    const registry = new SpawnRegistry()
+    const spawnId = registry.register({
+      agentName: 'a',
+      threadRef: { channelId: 'c', threadId: 't' },
+      provider: defaultProvider,
+    })
+    const sockPath = join(tmpdir(), `zooid-test-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    const members = await callDaemon(sockPath, { spawnId, method: 'getChannelMembers', params: {} })
+    expect(members).toEqual([{ id: '@alice:hs', name: 'alice', is_agent: false }])
+
+    const info = await callDaemon(sockPath, { spawnId, method: 'getChannelInfo', params: {} })
+    expect(info).toEqual({ id: '!r:hs', name: 'general', transport: 'matrix' })
+  })
+
+  it('serves two different spawns on one shared socket — each routed to its own provider', async () => {
+    const providerA = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [{ id: 'A1', sender: 'alice', text: 'from A', timestamp: 'T', is_agent: false }],
+        has_more: false,
+      }),
+      getChannelInfo: async () => ({ id: '!a:hs', name: 'room-A', transport: 'matrix' }),
+    })
+    const providerB = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [{ id: 'B1', sender: 'bob', text: 'from B', timestamp: 'T', is_agent: false }],
+        has_more: false,
+      }),
+      getChannelInfo: async () => ({ id: '!b:hs', name: 'room-B', transport: 'matrix' }),
+    })
+    const registry = new SpawnRegistry()
+    const spawnA = registry.register({
+      agentName: 'architect',
+      threadRef: { channelId: '!a:hs', threadId: '!a:hs' },
+      provider: providerA,
+    })
+    const spawnB = registry.register({
+      agentName: 'product-owner',
+      threadRef: { channelId: '!b:hs', threadId: '!b:hs' },
+      provider: providerB,
+    })
+    const sockPath = join(tmpdir(), `zooid-test-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    const [resA, resB] = await Promise.all([
+      callDaemon(sockPath, { spawnId: spawnA, method: 'getRoomHistory', params: {} }),
+      callDaemon(sockPath, { spawnId: spawnB, method: 'getRoomHistory', params: {} }),
+    ])
+
+    expect((resA as { messages: Array<{ id: string }> }).messages[0].id).toBe('A1')
+    expect((resB as { messages: Array<{ id: string }> }).messages[0].id).toBe('B1')
+
+    const infoB = await callDaemon(sockPath, { spawnId: spawnB, method: 'getChannelInfo', params: {} })
+    expect((infoB as { id: string }).id).toBe('!b:hs')
+  })
+
+  it('handles many sequential calls from one client connection without leaking state', async () => {
+    const providerA = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [{ id: 'A', sender: 'a', text: 'a', timestamp: 'T', is_agent: false }],
+        has_more: false,
+      }),
+    })
+    const providerB = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [{ id: 'B', sender: 'b', text: 'b', timestamp: 'T', is_agent: false }],
+        has_more: false,
+      }),
+    })
+    const registry = new SpawnRegistry()
+    const spawnA = registry.register({
+      agentName: 'a',
+      threadRef: { channelId: 'a', threadId: 'a' },
+      provider: providerA,
+    })
+    const spawnB = registry.register({
+      agentName: 'b',
+      threadRef: { channelId: 'b', threadId: 'b' },
+      provider: providerB,
+    })
+    const sockPath = join(tmpdir(), `zooid-test-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    for (let i = 0; i < 20; i++) {
+      const spawnId = i % 2 === 0 ? spawnA : spawnB
+      const expected = i % 2 === 0 ? 'A' : 'B'
+      const res = (await callDaemon(sockPath, {
+        spawnId,
+        method: 'getRoomHistory',
+        params: {},
+      })) as { messages: Array<{ id: string }> }
+      expect(res.messages[0].id).toBe(expected)
+    }
+  })
+})

package/src/daemon-socket.ts

@@ -0,0 +1,148 @@
+import { createServer, createConnection, type Server, type Socket } from 'node:net'
+import { unlink } from 'node:fs/promises'
+import type { SpawnRegistry } from './spawn-registry.js'
+
+interface DaemonRequest {
+  spawnId: string
+  method:
+    | 'getRoomHistory'
+    | 'getRecentThreads'
+    | 'getThreadHistory'
+    | 'getChannelMembers'
+    | 'getChannelInfo'
+  params: Record<string, unknown>
+}
+
+interface DaemonResponse {
+  ok: true
+  result: unknown
+}
+
+interface DaemonError {
+  ok: false
+  error: string
+}
+
+export interface DaemonSocketHandle {
+  close(): Promise<void>
+}
+
+export async function startDaemonSocketServer(opts: {
+  sockPath: string
+  registry: SpawnRegistry
+}): Promise<DaemonSocketHandle> {
+  await unlink(opts.sockPath).catch(() => {})
+  const server: Server = createServer((socket: Socket) => {
+    let buf = ''
+    socket.setEncoding('utf8')
+    socket.on('data', async (chunk) => {
+      buf += chunk
+      let idx: number
+      while ((idx = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, idx)
+        buf = buf.slice(idx + 1)
+        if (!line) continue
+        await handleLine(line, socket, opts.registry)
+      }
+    })
+    socket.on('error', () => {})
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(opts.sockPath, () => {
+      server.removeListener('error', reject)
+      resolve()
+    })
+  })
+  return {
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve())
+      }),
+  }
+}
+
+async function handleLine(line: string, socket: Socket, registry: SpawnRegistry) {
+  let req: DaemonRequest
+  try {
+    req = JSON.parse(line) as DaemonRequest
+  } catch {
+    socket.write(JSON.stringify({ ok: false, error: 'invalid json' } satisfies DaemonError) + '\n')
+    return
+  }
+  const binding = registry.get(req.spawnId)
+  if (!binding) {
+    process.stderr.write(
+      `[context-mcp] daemon: unknown spawn-id ${req.spawnId} for method=${req.method}\n`,
+    )
+    socket.write(
+      JSON.stringify({
+        ok: false,
+        error: `unknown spawn-id: ${req.spawnId}`,
+      } satisfies DaemonError) + '\n',
+    )
+    return
+  }
+  process.stderr.write(
+    `[context-mcp] daemon: ${req.method} spawn=${req.spawnId.slice(0, 8)} agent=${binding.agentName}\n`,
+  )
+  try {
+    let result: unknown
+    const channelId = binding.threadRef.channelId
+    if (req.method === 'getRoomHistory') {
+      result = await binding.provider.getRoomHistory(channelId, req.params)
+    } else if (req.method === 'getRecentThreads') {
+      result = await binding.provider.getRecentThreads(channelId, req.params)
+    } else if (req.method === 'getThreadHistory') {
+      const threadId = String(req.params.threadId ?? '')
+      result = await binding.provider.getThreadHistory(channelId, threadId, req.params)
+    } else if (req.method === 'getChannelMembers') {
+      result = await binding.provider.getChannelMembers(channelId)
+    } else if (req.method === 'getChannelInfo') {
+      result = await binding.provider.getChannelInfo(channelId)
+    } else {
+      socket.write(
+        JSON.stringify({
+          ok: false,
+          error: `unknown method: ${(req as { method: string }).method}`,
+        } satisfies DaemonError) + '\n',
+      )
+      return
+    }
+    socket.write(JSON.stringify({ ok: true, result } satisfies DaemonResponse) + '\n')
+  } catch (err) {
+    socket.write(
+      JSON.stringify({
+        ok: false,
+        error: String(err instanceof Error ? err.message : err),
+      } satisfies DaemonError) + '\n',
+    )
+  }
+}
+
+export async function callDaemon(sockPath: string, req: DaemonRequest): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(sockPath)
+    let buf = ''
+    socket.setEncoding('utf8')
+    socket.on('error', reject)
+    socket.on('data', (chunk) => {
+      buf += chunk
+      const idx = buf.indexOf('\n')
+      if (idx < 0) return
+      const line = buf.slice(0, idx)
+      let parsed: DaemonResponse | DaemonError
+      try {
+        parsed = JSON.parse(line) as DaemonResponse | DaemonError
+      } catch (e) {
+        socket.end()
+        reject(e instanceof Error ? e : new Error(String(e)))
+        return
+      }
+      socket.end()
+      if (parsed.ok) resolve(parsed.result)
+      else reject(new Error(parsed.error))
+    })
+    socket.write(JSON.stringify(req) + '\n')
+  })
+}

package/src/factory.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest'
+import { existsSync } from 'node:fs'
+import { buildContextServerSpec } from './factory.js'
+
+describe('buildContextServerSpec', () => {
+  it('produces the ACP mcpServers entry the daemon passes to session/new', () => {
+    const spec = buildContextServerSpec({
+      spawnId: '11111111-1111-4111-8111-111111111111',
+      sockPath: '/run/zooid/abc.sock',
+      binPath: '/usr/local/lib/zooid/zooid-context-mcp.js',
+    })
+    expect(spec.name).toBe('zooid-context')
+    expect(spec.command).toBe(process.execPath)
+    expect(spec.args[0]).toBe('/usr/local/lib/zooid/zooid-context-mcp.js')
+    expect(spec.args).toContain('--spawn-id')
+    expect(spec.args).toContain('11111111-1111-4111-8111-111111111111')
+    expect(spec.env).toEqual([{ name: 'ZOOID_DAEMON_SOCK', value: '/run/zooid/abc.sock' }])
+  })
+
+  it('resolves the default bin via Node module resolution to a real path on disk', () => {
+    // Pinned regression: tsup bundles this file into the CLI chunk, so the
+    // earlier `import.meta.url`-based default broke at runtime (it resolved
+    // to `<cli-dist>/bin.js`, not this package's dist). `createRequire` must
+    // walk node_modules and return an actual file path.
+    const spec = buildContextServerSpec({
+      spawnId: 'sid',
+      sockPath: '/tmp/x.sock',
+    })
+    expect(spec.args[0]).toMatch(/context-mcp[/\\]dist[/\\]bin\.js$/)
+    expect(existsSync(spec.args[0])).toBe(true)
+  })
+})

package/src/factory.ts

@@ -0,0 +1,35 @@
+import { createRequire } from 'node:module'
+import type { ZooidContextServerSpec } from './types.js'
+
+/**
+ * Resolve `dist/bin.js` via Node's runtime module resolver rather than
+ * `import.meta.url`. tsup bundles this file into the CLI's own chunk, so
+ * `import.meta.url` at runtime points to the CLI bundle — not this
+ * package's dist. `createRequire` walks the runtime `node_modules` tree
+ * instead and finds the package wherever it actually lives.
+ */
+function resolveDefaultBin(): string {
+  const req = createRequire(import.meta.url)
+  // Resolve via the dedicated `./bin` export → `./dist/bin.js`. Avoids the
+  // exports-restriction surprise of importing `./package.json`.
+  return req.resolve('@zooid/context-mcp/bin')
+}
+
+let cachedDefaultBin: string | null = null
+function getDefaultBin(): string {
+  if (!cachedDefaultBin) cachedDefaultBin = resolveDefaultBin()
+  return cachedDefaultBin
+}
+
+export function buildContextServerSpec(opts: {
+  spawnId: string
+  sockPath: string
+  binPath?: string
+}): ZooidContextServerSpec {
+  return {
+    name: 'zooid-context',
+    command: process.execPath,
+    args: [opts.binPath ?? getDefaultBin(), '--spawn-id', opts.spawnId],
+    env: [{ name: 'ZOOID_DAEMON_SOCK', value: opts.sockPath }],
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { SpawnRegistry } from './spawn-registry.js'
+export { startDaemonSocketServer, callDaemon } from './daemon-socket.js'
+export type { DaemonSocketHandle } from './daemon-socket.js'
+export { buildContextMcpServer } from './mcp-server.js'
+export { buildContextServerSpec } from './factory.js'
+export type { SpawnBinding, ZooidContextServerSpec } from './types.js'

package/src/integration.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { SpawnRegistry } from './spawn-registry.js'
+import { startDaemonSocketServer } from './daemon-socket.js'
+import type { TransportContextProvider } from '@zooid/core'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const BIN = join(__dirname, '..', 'dist', 'bin.js')
+
+const cleanup: Array<() => Promise<void>> = []
+afterEach(async () => {
+  for (const fn of cleanup) await fn()
+  cleanup.length = 0
+})
+
+function fakeProvider(over: Partial<TransportContextProvider> = {}): TransportContextProvider {
+  return {
+    getRoomHistory: async () => ({ messages: [], has_more: false }),
+    getRecentThreads: async () => ({ threads: [], has_more: false }),
+    getThreadHistory: async () => ({ messages: [], has_more: false }),
+    getChannelMembers: async () => [],
+    getChannelInfo: async () => ({ id: 'r', name: 'r', transport: 'matrix' }),
+    ...over,
+  }
+}
+
+describe.skipIf(!existsSync(BIN))('zooid-context MCP server (out-of-process)', () => {
+  it('end-to-end tools/call → daemon socket → provider → tool result', async () => {
+    const provider = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [
+          { id: 'e1', sender: 'alice', text: 'hi', timestamp: 'T', is_agent: false },
+        ],
+        has_more: false,
+      }),
+    })
+    const registry = new SpawnRegistry()
+    const spawnId = registry.register({
+      agentName: 'architect',
+      threadRef: { channelId: '!room:hs', threadId: '!room:hs' },
+      provider,
+    })
+    const sockPath = join(tmpdir(), `zooid-it-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    const transport = new StdioClientTransport({
+      command: process.execPath,
+      args: [BIN, '--spawn-id', spawnId],
+      env: { ...process.env, ZOOID_DAEMON_SOCK: sockPath } as Record<string, string>,
+    })
+    const client = new Client({ name: 'it', version: '0.0.1' }, { capabilities: {} })
+    await client.connect(transport)
+    cleanup.push(async () => {
+      await client.close()
+    })
+
+    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_thread_history',
+    ])
+
+    const result = await client.callTool({ name: 'zooid_get_history', arguments: {} })
+    const payload = JSON.parse((result.content as Array<{ text: string }>)[0].text)
+    expect(payload.messages[0].id).toBe('e1')
+  })
+
+  it('two MCP server subprocesses sharing one socket route to their own bindings', async () => {
+    const providerA = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [{ id: 'A1', sender: 'alice', text: 'from A', timestamp: 'T', is_agent: false }],
+        has_more: false,
+      }),
+      getChannelInfo: async () => ({ id: '!a:hs', name: 'room-A', transport: 'matrix' }),
+    })
+    const providerB = fakeProvider({
+      getRoomHistory: async () => ({
+        messages: [{ id: 'B1', sender: 'bob', text: 'from B', timestamp: 'T', is_agent: false }],
+        has_more: false,
+      }),
+      getChannelInfo: async () => ({ id: '!b:hs', name: 'room-B', transport: 'matrix' }),
+    })
+    const registry = new SpawnRegistry()
+    const spawnA = registry.register({
+      agentName: 'architect',
+      threadRef: { channelId: '!a:hs', threadId: '!a:hs' },
+      provider: providerA,
+    })
+    const spawnB = registry.register({
+      agentName: 'product-owner',
+      threadRef: { channelId: '!b:hs', threadId: '!b:hs' },
+      provider: providerB,
+    })
+    const sockPath = join(tmpdir(), `zooid-it-${randomUUID()}.sock`)
+    const server = await startDaemonSocketServer({ sockPath, registry })
+    cleanup.push(() => server.close())
+
+    async function startClient(spawnId: string) {
+      const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [BIN, '--spawn-id', spawnId],
+        env: { ...process.env, ZOOID_DAEMON_SOCK: sockPath } as Record<string, string>,
+      })
+      const client = new Client({ name: 'it', version: '0.0.1' }, { capabilities: {} })
+      await client.connect(transport)
+      cleanup.push(async () => {
+        await client.close()
+      })
+      return client
+    }
+
+    const [clientA, clientB] = await Promise.all([startClient(spawnA), startClient(spawnB)])
+
+    const [resA, resB] = await Promise.all([
+      clientA.callTool({ name: 'zooid_get_history', arguments: {} }),
+      clientB.callTool({ name: 'zooid_get_history', arguments: {} }),
+    ])
+    const payloadA = JSON.parse((resA.content as Array<{ text: string }>)[0].text)
+    const payloadB = JSON.parse((resB.content as Array<{ text: string }>)[0].text)
+    expect(payloadA.messages[0].id).toBe('A1')
+    expect(payloadB.messages[0].id).toBe('B1')
+
+    const infoA = await clientA.callTool({ name: 'zooid_get_channel_info', arguments: {} })
+    const infoB = await clientB.callTool({ name: 'zooid_get_channel_info', arguments: {} })
+    expect(JSON.parse((infoA.content as Array<{ text: string }>)[0].text).id).toBe('!a:hs')
+    expect(JSON.parse((infoB.content as Array<{ text: string }>)[0].text).id).toBe('!b:hs')
+  })
+})