cross-agent-teams-mcp 0.2.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "cross-agent-teams-mcp",
+  "version": "0.2.0",
+  "description": "MCP daemon for cross-agent collaboration",
+  "type": "module",
+  "bin": {
+    "cross-agent-teams-mcp": "./dist/cli.js",
+    "cross-agent-teams-channel": "./dist/channel-cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jtianling/cross-agent-teams-mcp.git"
+  },
+  "homepage": "https://github.com/jtianling/cross-agent-teams-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/jtianling/cross-agent-teams-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "agent",
+    "multi-agent",
+    "cross-agent"
+  ],
+  "author": "jtianling <jtianling@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.3.0",
+    "fastify": "^5.0.0",
+    "json-schema-diff-validator": "^0.4.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/channel/auto-daemon.ts

@@ -0,0 +1,130 @@
+import { spawn, type SpawnOptions } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { mkdirSync, openSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export interface EnsureDaemonHealthyOptions {
+  daemonUrl: string
+  log?: NodeJS.WritableStream
+  // Test-only injection points; production callers leave these undefined.
+  fetchImpl?: typeof fetch
+  spawnImpl?: typeof spawn
+  daemonEntryOverride?: string
+  probeTimeoutMs?: number
+  pollAttempts?: number
+  pollIntervalMs?: number
+  logFilePath?: string
+}
+
+const DEFAULT_LOG_PATH = join(homedir(), '.cross-agent-teams-mcp', 'daemon.log')
+
+function isLoopbackHost(host: string): boolean {
+  return host === '127.0.0.1' || host === 'localhost'
+}
+
+function originOf(url: URL): string {
+  return `${url.protocol}//${url.host}`
+}
+
+async function probeHealth(
+  origin: string,
+  timeoutMs: number,
+  fetchImpl: typeof fetch
+): Promise<boolean> {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const resp = await fetchImpl(`${origin}/health`, { signal: ac.signal })
+    return resp.status >= 200 && resp.status < 300
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function resolveDaemonEntry(): string {
+  // Test escape hatch: when set, tests can inject a fake daemon entry without
+  // having to mock child_process.spawn inside a subprocess.
+  const override = process.env.CROSS_AGENT_TEAMS_CHANNEL_DAEMON_ENTRY
+  if (override && override.length > 0) return override
+  // After tsup bundles, this module is inlined into dist/channel-cli.js;
+  // the daemon entry sits next to it as dist/cli.js.  Resolving relative to
+  // import.meta.url (which equals the channel-cli.js URL post-build) gives
+  // the right neighbor file.
+  return fileURLToPath(new URL('./cli.js', import.meta.url))
+}
+
+function ensureLogDir(logPath: string): void {
+  try {
+    mkdirSync(dirname(logPath), { recursive: true })
+  } catch {
+    // best-effort — spawn will fail clearly if path still unusable
+  }
+}
+
+export async function ensureDaemonHealthy(opts: EnsureDaemonHealthyOptions): Promise<void> {
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const spawnImpl = opts.spawnImpl ?? spawn
+  const probeTimeoutMs = opts.probeTimeoutMs ?? 2000
+  const pollAttempts = opts.pollAttempts ?? 20
+  const pollIntervalMs = opts.pollIntervalMs ?? 250
+  const logFilePath = opts.logFilePath ?? DEFAULT_LOG_PATH
+
+  let parsed: URL
+  try {
+    parsed = new URL(opts.daemonUrl)
+  } catch {
+    throw new Error(`invalid daemon URL: ${opts.daemonUrl}`)
+  }
+
+  const origin = originOf(parsed)
+  const host = parsed.hostname
+  const port = parsed.port ? Number(parsed.port) : null
+
+  // Step 1: probe.
+  if (await probeHealth(origin, probeTimeoutMs, fetchImpl)) return
+
+  // Step 2: non-loopback → no spawn, error out.
+  if (!isLoopbackHost(host)) {
+    throw new Error(
+      `daemon at ${opts.daemonUrl} not reachable; auto-spawn disabled for non-loopback URLs`
+    )
+  }
+
+  // Step 3: spawn detached daemon.
+  const entry = opts.daemonEntryOverride ?? resolveDaemonEntry()
+  const args = ['daemon']
+  if (port !== null && Number.isFinite(port)) {
+    args.push('--port', String(port))
+  }
+
+  ensureLogDir(logFilePath)
+  let logFd: number | undefined
+  try {
+    logFd = openSync(logFilePath, 'a')
+  } catch {
+    logFd = undefined
+  }
+
+  const spawnOptions: SpawnOptions = {
+    detached: true,
+    stdio: logFd !== undefined
+      ? ['ignore', logFd, logFd]
+      : 'ignore'
+  }
+  const child = spawnImpl(process.execPath, [entry, ...args], spawnOptions)
+  try { child.unref() } catch { /* best-effort */ }
+
+  // Step 4: poll /health.
+  for (let i = 0; i < pollAttempts; i++) {
+    await new Promise(r => setTimeout(r, pollIntervalMs))
+    if (await probeHealth(origin, probeTimeoutMs, fetchImpl)) return
+  }
+
+  throw new Error(
+    `daemon failed to become healthy at ${opts.daemonUrl} within bootstrap deadline; ` +
+    `see log at ${logFilePath}`
+  )
+}

package/src/channel/daemon-client.ts

@@ -0,0 +1,155 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+
+export interface RegistrationConfig {
+  daemonUrl: string
+  channel_session_id: string
+  backoffInitialMs?: number
+  backoffMaxMs?: number
+  notificationHandler?: (payload: unknown) => void
+}
+
+export interface ReconnectingProxyConfig extends RegistrationConfig {
+  onSequenceComplete?: (order: string[]) => void
+  onDisconnect?: () => void
+  healthCheckIntervalMs?: number
+}
+
+export interface ReconnectingProxyController {
+  stop(): Promise<void>
+}
+
+export interface RegistrationSequenceResult {
+  order: string[]
+  lastSubscribeResult: unknown
+  client: Client
+  transport: StreamableHTTPClientTransport
+  close: () => Promise<void>
+}
+
+type ToolResult = Record<string, unknown>
+
+async function parseToolResult(resp: unknown): Promise<ToolResult> {
+  const r = resp as { content?: Array<{ text?: string }> }
+  const text = r.content?.[0]?.text
+  if (typeof text !== 'string') return {}
+  try { return JSON.parse(text) as ToolResult } catch { return {} }
+}
+
+export async function runRegistrationSequence(
+  config: RegistrationConfig
+): Promise<RegistrationSequenceResult> {
+  const order: string[] = []
+  const transport = new StreamableHTTPClientTransport(new URL(config.daemonUrl))
+  const client = new Client({ name: 'cross-agent-teams-channel', version: '0.1.0' })
+
+  if (config.notificationHandler) {
+    client.fallbackNotificationHandler = async (n) => {
+      if (n.method === 'notifications/channel_wake') {
+        config.notificationHandler!(n.params)
+      }
+    }
+  }
+
+  await client.connect(transport)
+
+  // 1. register_agent as proxy — identity keyed on pid, stable across reconnects
+  // so the (team, name) ON CONFLICT upsert reuses the same row instead of spamming new rows
+  const registerResp = await client.callTool({
+    name: 'register_agent',
+    arguments: {
+      client: 'custom',
+      client_name: 'cross-agent-teams-channel',
+      model: 'proxy',
+      role: '__channel_proxy__',
+      name: `channel-proxy-${process.pid}`,
+      team: 'default',
+      claude_ui_pid: process.ppid,
+      delivery: {
+        kind: 'claude-channel',
+        channel_session_id: config.channel_session_id,
+      },
+    }
+  })
+  order.push('register_agent')
+  const regResult = await parseToolResult(registerResp)
+  if (!('agent_id' in regResult)) {
+    throw new Error(`register_agent failed: ${JSON.stringify(regResult)}`)
+  }
+
+  // 2. subscribe_channel_wake — proxy's csid is fresh per startup
+  const subResp = await client.callTool({
+    name: 'subscribe_channel_wake',
+    arguments: { channel_session_id: config.channel_session_id }
+  })
+  order.push('subscribe_channel_wake')
+  const subResult = await parseToolResult(subResp)
+  if (!('ok' in subResult) || subResult.ok !== true) {
+    throw new Error(`subscribe_channel_wake failed: ${JSON.stringify(subResult)}`)
+  }
+
+  return {
+    order,
+    lastSubscribeResult: subResult,
+    client,
+    transport,
+    close: async () => {
+      try { await client.close() } catch { /* best-effort */ }
+      try { await transport.close() } catch { /* best-effort */ }
+    }
+  }
+}
+
+export function runReconnectingProxy(config: ReconnectingProxyConfig): ReconnectingProxyController {
+  let stopped = false
+  let currentSeq: RegistrationSequenceResult | null = null
+
+  async function waitForDisconnect(seq: RegistrationSequenceResult): Promise<void> {
+    const interval = config.healthCheckIntervalMs ?? 200
+    let disconnected = false
+    const closeHandler = () => { disconnected = true }
+    const prevOnClose = seq.transport.onclose
+    seq.transport.onclose = () => { prevOnClose?.(); closeHandler() }
+    while (!disconnected && !stopped) {
+      await new Promise(r => setTimeout(r, interval))
+      if (disconnected || stopped) break
+      try {
+        await seq.client.callTool({ name: 'echo', arguments: { msg: 'hb' } })
+      } catch {
+        disconnected = true
+        break
+      }
+    }
+  }
+
+  async function loop(): Promise<void> {
+    while (!stopped) {
+      try {
+        const seq = await runRegistrationSequence(config)
+        currentSeq = seq
+        if (config.onSequenceComplete) config.onSequenceComplete([...seq.order])
+
+        await waitForDisconnect(seq)
+        if (config.onDisconnect) config.onDisconnect()
+        try { await seq.close() } catch { /* best-effort */ }
+        currentSeq = null
+      } catch {
+        // register/subscribe failed — wait and retry.
+      }
+      if (stopped) break
+      const wait = config.backoffInitialMs ?? 500
+      await new Promise(r => setTimeout(r, wait))
+    }
+  }
+
+  void loop()
+
+  return {
+    stop: async () => {
+      stopped = true
+      if (currentSeq) {
+        try { await currentSeq.close() } catch { /* best-effort */ }
+      }
+    }
+  }
+}

package/src/channel/proxy.ts

@@ -0,0 +1,28 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+
+export function createProxyServer(): McpServer {
+  return new McpServer(
+    { name: 'cross-agent-teams-channel', version: '0.1.0' },
+    { capabilities: { experimental: { 'claude/channel': {} } } }
+  )
+}
+
+export interface ChannelWakeParams {
+  content: string
+  meta: Record<string, string>
+}
+
+export function relayChannelWake(server: McpServer, params: ChannelWakeParams): void {
+  try {
+    const notif = {
+      method: 'notifications/claude/channel',
+      params: params as unknown as Record<string, unknown>
+    }
+    const p = (server.server.notification as (n: typeof notif) => Promise<void>)(notif)
+    if (p && typeof p.catch === 'function') {
+      p.catch(() => { /* host closed — drop silently */ })
+    }
+  } catch {
+    // host transport closed or not yet connected — drop silently
+  }
+}

package/src/channel-cli.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createProxyServer, relayChannelWake } from './channel/proxy.js'
+import { runReconnectingProxy } from './channel/daemon-client.js'
+import { ensureDaemonHealthy } from './channel/auto-daemon.js'
+
+const DEFAULT_DAEMON_URL = 'http://127.0.0.1:9100/mcp'
+
+interface CliArgs {
+  daemonUrl: string
+}
+
+export class CliArgError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CliArgError'
+  }
+}
+
+export function buildStartupHint(csid: string): { content: string; meta: { source: string; kind: string } } {
+  const content = [
+    `cross-agent-teams-mcp: your channel_session_id is ${csid}.`,
+    `Preferred in Claude Code: call register_claude_self({name: "<agent-name>", ui_pid: $PPID}) from this session — do NOT pass channel_session_id here; the daemon auto-binds via ui_pid.`,
+    `Unified equivalent: register_agent({client: "claude-code", name: "<agent-name>", model: "<model>", ui_pid: $PPID}) — also without channel_session_id.`,
+    `bind_channel({channel_session_id: "${csid}"}) is the low-level rebind tool for an already-registered Claude host that needs to switch to a fresh csid; it is NOT the primary registration path.`,
+    `Do not use curl or another external HTTP client for Claude registration here — that would create a different MCP session, and follow-up tools in Claude Code could still see unknown_agent.`
+  ].join(' ')
+  return {
+    content,
+    meta: { source: 'cross_agent_teams_mcp', kind: 'startup_bind_hint' }
+  }
+}
+
+export function parseCliArgs(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): CliArgs {
+  let daemonUrl: string | undefined
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]
+    const next = argv[i + 1]
+    switch (flag) {
+      case '--daemon-url':
+        daemonUrl = next; i++; break
+      default:
+        // Ignore unknown flags for forward-compat (including legacy
+        // --agent-team / --agent-name, which are no longer honored).
+        break
+    }
+  }
+
+  if (!daemonUrl || daemonUrl.length === 0) {
+    daemonUrl = env.CROSS_AGENT_TEAMS_MCP_DAEMON_URL
+  }
+
+  if (!daemonUrl || daemonUrl.length === 0) {
+    daemonUrl = DEFAULT_DAEMON_URL
+  }
+  return { daemonUrl }
+}
+
+export async function main(
+  argv: readonly string[] = process.argv.slice(2),
+  env: NodeJS.ProcessEnv = process.env
+): Promise<void> {
+  let args: CliArgs
+  try {
+    args = parseCliArgs(argv, env)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`cross-agent-teams-channel: ${msg}\n`)
+    process.exit(2)
+  }
+
+  // Fresh csid per startup — no persistence. Multi-instance safe.
+  const csid = randomUUID()
+
+  try {
+    await ensureDaemonHealthy({ daemonUrl: args.daemonUrl, log: process.stderr })
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`cross-agent-teams-channel: ${msg}\n`)
+    process.exit(2)
+  }
+
+  const hostServer = createProxyServer()
+  const stdioTransport = new StdioServerTransport()
+
+  const controller = runReconnectingProxy({
+    daemonUrl: args.daemonUrl,
+    channel_session_id: csid,
+    notificationHandler: (params) => {
+      relayChannelWake(hostServer, params as { content: string; meta: Record<string, string> })
+    },
+    onSequenceComplete: () => {
+      // Announce csid to Claude via host-facing channel notification so Claude
+      // can call bind_channel({channel_session_id}) to bind its own agent row.
+      const hint = buildStartupHint(csid)
+      relayChannelWake(hostServer, hint)
+    }
+  })
+
+  let stopped = false
+  const shutdown = async (): Promise<void> => {
+    if (stopped) return
+    stopped = true
+    try { await controller.stop() } catch { /* best-effort */ }
+    try { await hostServer.close() } catch { /* best-effort */ }
+    process.exit(0)
+  }
+
+  stdioTransport.onclose = () => { void shutdown() }
+
+  await hostServer.connect(stdioTransport)
+
+  process.on('SIGTERM', () => { void shutdown() })
+  process.on('SIGINT', () => { void shutdown() })
+}
+
+// eslint-disable-next-line @typescript-eslint/no-misused-promises
+if (import.meta.url === `file://${process.argv[1]}`) {
+  void main()
+}

package/src/cli.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { startServer } from './daemon/server.js'
+import { wireShutdown } from './daemon/shutdown.js'
+import { acquirePidFile } from './daemon/pid.js'
+import { selectPort } from './daemon/port.js'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+
+function parseArg(name: string, def?: string): string | undefined {
+  const i = process.argv.indexOf(name)
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : def
+}
+
+function defaultHome(): string {
+  return process.env.CROSS_AGENT_TEAMS_MCP_HOME ?? join(homedir(), '.cross-agent-teams-mcp')
+}
+
+async function runDaemon(): Promise<void> {
+  const home = defaultHome()
+  const pidPath = parseArg('--pid-file', join(home, 'daemon.pid'))!
+  const dbPath = parseArg('--db', join(home, 'data.db'))!
+  const token = parseArg('--token')
+  const requested = Number(parseArg('--port', '9100'))
+  const port = requested === 0 ? 0 : await selectPort([requested, requested + 1, requested + 2])
+  const r = acquirePidFile(pidPath, port || requested)
+  if (!r.ok) { console.error('daemon already running pid=' + r.pid); process.exit(1) }
+  const started = await startServer({ dbPath, token, port })
+  wireShutdown(started.app, pidPath)
+  console.log(`listening on ${started.host}:${started.port}`)
+}
+
+function resolveDaemonPort(explicit: string | undefined): number | undefined {
+  if (explicit !== undefined) {
+    const n = Number(explicit)
+    if (Number.isInteger(n) && n > 0) return n
+    return undefined
+  }
+  const pidPath = parseArg('--pid-file', join(defaultHome(), 'daemon.pid'))!
+  if (!existsSync(pidPath)) return undefined
+  try {
+    const parsed = JSON.parse(readFileSync(pidPath, 'utf8')) as { port?: number }
+    if (typeof parsed.port === 'number' && parsed.port > 0) return parsed.port
+  } catch { /* ignore corrupt pid file */ }
+  return undefined
+}
+
+async function runPreRegisterCodexPane(): Promise<void> {
+  const pane = parseArg('--pane')
+  const agentId = parseArg('--agent-id')
+  const ttlRaw = parseArg('--ttl')
+  const tokenExplicit = parseArg('--token')
+  const portExplicit = parseArg('--port')
+
+  if (!pane || !agentId) {
+    console.error('usage: cross-agent-teams-mcp pre-register-codex-pane --pane <pane_id> --agent-id <uuid> [--ttl <seconds>] [--port <n>] [--token <t>]')
+    process.exit(2)
+  }
+
+  const port = resolveDaemonPort(portExplicit)
+  if (!port) {
+    console.error('{"ok":false,"error":"daemon_port_unresolved","detail":"pass --port or start the daemon so the pid file is present"}')
+    process.exit(1)
+  }
+
+  const token = tokenExplicit ?? process.env.CROSS_AGENT_TEAMS_MCP_TOKEN
+  const host = process.env.CROSS_AGENT_TEAMS_MCP_HOST ?? '127.0.0.1'
+  const base = new URL(`http://${host}:${port}/mcp`)
+
+  const requestInit: RequestInit | undefined = token
+    ? { headers: { Authorization: `Bearer ${token}` } }
+    : undefined
+
+  const transport = new StreamableHTTPClientTransport(base, {
+    requestInit,
+  })
+  const client = new Client({ name: 'cross-agent-teams-mcp-cli', version: '0.1.0' })
+
+  try {
+    await client.connect(transport)
+    const args: Record<string, unknown> = {
+      pane_id: pane,
+      xats_agent_id: agentId,
+    }
+    if (ttlRaw !== undefined) {
+      const ttl = Number(ttlRaw)
+      if (!Number.isInteger(ttl) || ttl <= 0) {
+        console.error('{"ok":false,"error":"invalid_ttl"}')
+        process.exit(2)
+      }
+      args.ttl_seconds = ttl
+    }
+    const resp = await client.callTool({
+      name: 'pre_register_codex_pane',
+      arguments: args,
+    })
+    const content = (resp as { content?: Array<{ text?: string }> }).content
+    const text = content?.[0]?.text ?? ''
+    let parsed: unknown
+    try { parsed = JSON.parse(text) } catch { parsed = { raw: text } }
+    const obj = (parsed ?? {}) as Record<string, unknown>
+    if (obj.ok === true) {
+      console.log(JSON.stringify(obj))
+      process.exit(0)
+    }
+    console.error(JSON.stringify(obj))
+    process.exit(1)
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    console.error(JSON.stringify({ ok: false, error: 'cli_failed', detail: msg }))
+    process.exit(1)
+  } finally {
+    try { await transport.close() } catch { /* best-effort */ }
+    try { await client.close() } catch { /* best-effort */ }
+  }
+}
+
+async function main(): Promise<void> {
+  const cmd = process.argv[2]
+  if (cmd === 'daemon') {
+    await runDaemon()
+    return
+  }
+  if (cmd === 'pre-register-codex-pane') {
+    await runPreRegisterCodexPane()
+    return
+  }
+  console.error('usage: cross-agent-teams-mcp <daemon|pre-register-codex-pane> [options]')
+  process.exit(2)
+}
+
+main().catch((e) => { console.error(e?.message ?? e); process.exit(1) })
+
+export {}

package/src/daemon/auth.ts

@@ -0,0 +1,17 @@
+import type { FastifyRequest, FastifyReply } from 'fastify'
+
+export function extractToken(req: FastifyRequest): string | undefined {
+  const h = req.headers['authorization']
+  if (typeof h === 'string' && h.startsWith('Bearer ')) return h.slice(7)
+  const q = (req.query as Record<string, unknown> | undefined)?.token
+  return typeof q === 'string' ? q : undefined
+}
+
+export function makeAuthHook(expected: string | undefined) {
+  return async (req: FastifyRequest, reply: FastifyReply) => {
+    if (req.url.startsWith('/health')) return
+    if (!expected) return
+    const got = extractToken(req)
+    if (got !== expected) return reply.code(401).send({ error: 'invalid_token' })
+  }
+}

package/src/daemon/channel-wake-fanout.ts

@@ -0,0 +1,39 @@
+export type ChannelWakeSink = (payload: unknown) => void
+
+interface Entry {
+  sessionId: string
+  sink: ChannelWakeSink
+}
+
+export class ChannelWakeFanout {
+  private readonly entries = new Map<string, Entry>()
+
+  attach(channel_session_id: string, sink: ChannelWakeSink, sessionId: string): void {
+    this.entries.set(channel_session_id, { sessionId, sink })
+  }
+
+  detach(channel_session_id: string): void {
+    this.entries.delete(channel_session_id)
+  }
+
+  detachBySession(sessionId: string): void {
+    for (const [csid, entry] of this.entries) {
+      if (entry.sessionId === sessionId) this.entries.delete(csid)
+    }
+  }
+
+  send(channel_session_id: string, payload: unknown): boolean {
+    const entry = this.entries.get(channel_session_id)
+    if (!entry) return false
+    try {
+      entry.sink(payload)
+    } catch {
+      // sink failure is the caller's concern; swallow to preserve map state
+    }
+    return true
+  }
+
+  has(channel_session_id: string): boolean {
+    return this.entries.has(channel_session_id)
+  }
+}