cross-agent-teams-mcp 0.2.0

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

@@ -0,0 +1,38 @@
+import type { ChannelWakeFanout } from './channel-wake-fanout.js'
+
+const META_KEY_RE = /^[A-Za-z0-9_]+$/
+
+export interface ChannelWakeInput {
+  content: string
+  meta: Record<string, string>
+}
+
+export type SendChannelWakeResult =
+  | { ok: true }
+  | { ok: false; reason: 'no_subscriber' }
+
+function sanitizeMeta(meta: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(meta)) {
+    if (META_KEY_RE.test(k)) out[k] = v
+  }
+  return out
+}
+
+export function sendChannelWake(
+  fanout: ChannelWakeFanout,
+  channel_session_id: string,
+  input: ChannelWakeInput
+): SendChannelWakeResult {
+  if (!fanout.has(channel_session_id)) return { ok: false, reason: 'no_subscriber' }
+  const payload = {
+    jsonrpc: '2.0' as const,
+    method: 'notifications/channel_wake' as const,
+    params: {
+      content: input.content,
+      meta: sanitizeMeta(input.meta)
+    }
+  }
+  fanout.send(channel_session_id, payload)
+  return { ok: true }
+}

package/src/daemon/cleanup.ts

@@ -0,0 +1,38 @@
+import type Database from 'better-sqlite3'
+
+export interface CleanupOpts {
+  maxAgeDays?: number
+  onlineWindowMs?: number
+  now?: Date
+}
+
+// Online cursor floor per destination team: an agent in team T with recent last_seen_at
+// advances team T's inbox cursor. Events older than 7 days that target team T can be
+// dropped once T's min cursor has moved past their event_id.
+const DELETE_AGED_EVENTS_SQL = `
+  WITH online_cursor AS (
+    SELECT team AS to_team, MIN(last_processed_event_id) AS min_cursor
+    FROM agents
+    WHERE last_seen_at >= :cutoffOnline
+    GROUP BY team
+  )
+  DELETE FROM events
+  WHERE created_at < :ageCutoff
+    AND (
+      events.to_team NOT IN (SELECT to_team FROM online_cursor)
+      OR events.event_id < (
+        SELECT min_cursor FROM online_cursor WHERE online_cursor.to_team = events.to_team
+      )
+    )
+`
+
+export function runCleanup(db: Database.Database, opts: CleanupOpts = {}): { deleted: number } {
+  const now = opts.now ?? new Date()
+  const maxAgeDays = opts.maxAgeDays ?? 7
+  const onlineWindowMs = opts.onlineWindowMs ?? 5 * 60 * 1000
+  const ageCutoff = new Date(now.getTime() - maxAgeDays * 86400 * 1000).toISOString()
+  const cutoffOnline = new Date(now.getTime() - onlineWindowMs).toISOString()
+
+  const info = db.prepare(DELETE_AGED_EVENTS_SQL).run({ ageCutoff, cutoffOnline })
+  return { deleted: Number(info.changes) }
+}

package/src/daemon/errors.ts

@@ -0,0 +1,18 @@
+const STORAGE_CODES = new Set(['SQLITE_FULL','SQLITE_BUSY','SQLITE_IOERR','SQLITE_LOCKED','SQLITE_READONLY'])
+
+export function isStorageError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false
+  const anyErr = err as { name?: string; code?: string }
+  if (anyErr.name === 'SqliteError') return true
+  if (anyErr.code && STORAGE_CODES.has(anyErr.code)) return true
+  return false
+}
+
+export async function wrapStorage<T>(fn: () => Promise<T> | T): Promise<T | { error: 'storage_unavailable' }> {
+  try {
+    return await fn()
+  } catch (err) {
+    if (isStorageError(err)) return { error: 'storage_unavailable' }
+    throw err
+  }
+}

package/src/daemon/pid.ts

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export type AcquireResult =
+  | { ok: true }
+  | { ok: false; reason: 'already_running'; pid: number; port: number }
+
+function isAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true } catch (e) {
+    const err = e as NodeJS.ErrnoException
+    // EPERM means the process exists but we lack permission to signal it; still alive.
+    if (err.code === 'EPERM') return true
+    return false
+  }
+}
+
+export function acquirePidFile(path: string, port: number): AcquireResult {
+  mkdirSync(dirname(path), { recursive: true })
+  if (existsSync(path)) {
+    try {
+      const prev = JSON.parse(readFileSync(path, 'utf8')) as { pid: number; port: number }
+      if (isAlive(prev.pid) && prev.pid !== process.pid) {
+        return { ok: false, reason: 'already_running', pid: prev.pid, port: prev.port }
+      }
+    } catch { /* corrupt file, overwrite */ }
+  }
+  writeFileSync(path, JSON.stringify({ pid: process.pid, port }))
+  return { ok: true }
+}
+
+export function releasePidFile(path: string): void {
+  if (existsSync(path)) rmSync(path, { force: true })
+}

package/src/daemon/port.ts

@@ -0,0 +1,16 @@
+import { createServer } from 'node:net'
+
+function tryBind(port: number, host: string): Promise<boolean> {
+  return new Promise(resolve => {
+    const s = createServer()
+    s.once('error', () => resolve(false))
+    s.listen(port, host, () => s.close(() => resolve(true)))
+  })
+}
+
+export async function selectPort(candidates: number[], host = '127.0.0.1'): Promise<number> {
+  for (const p of candidates) {
+    if (await tryBind(p, host)) return p
+  }
+  throw new Error(`ports ${candidates[0]}-${candidates[candidates.length - 1]} unavailable`)
+}

package/src/daemon/runtime-identity.ts

@@ -0,0 +1,238 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { DetectAgentKind } from './tmux-pane-detect.js'
+
+const TMUX_LIST_TIMEOUT_MS = 3_000
+const PS_LIST_TIMEOUT_MS = 3_000
+
+export interface BindRuntimeIdentityInput {
+  agent: DetectAgentKind
+  ui_pid?: number
+  ui_tty?: string
+  tmux_pane_id?: string
+  process_pattern?: string
+}
+
+export type BindRuntimeIdentityResult =
+  | {
+      ok: true
+      tmux_pane_id: string
+      verification_mode: 'verified_pid_tty_pane' | 'verified_tty_pane'
+      tty: string
+      ui_pid?: number
+    }
+  | { error: 'invalid_runtime_identity' }
+  | { error: 'invalid_process_pattern' }
+  | { error: 'invalid_ui_pid' }
+  | { error: 'pid_not_found' }
+  | { error: 'pid_has_no_tty' }
+  | { error: 'agent_process_mismatch' }
+  | { error: 'invalid_ui_tty' }
+  | { error: 'tmux_unavailable'; detail: string }
+  | { error: 'tmux_pane_not_found' }
+  | { error: 'pid_pane_tty_mismatch'; detail: { pid_tty: string; pane_tty: string } }
+  | { error: 'tty_maps_to_no_agent_process' }
+  | { error: 'ambiguous_tty_match'; candidates: Array<{ pane_id: string; tty: string }> }
+
+export interface BindRuntimeIdentityDeps {
+  execFile?: typeof execFile
+}
+
+interface PaneRow {
+  pane_id: string
+  tty: string
+}
+
+function normalizeTty(raw: string | undefined): string | undefined {
+  const value = raw?.trim()
+  if (!value) return undefined
+  const normalized = value.replace(/^\/dev\//, '')
+  if (!normalized || normalized === '?') return undefined
+  return normalized
+}
+
+function commandPattern(args: BindRuntimeIdentityInput): RegExp | null {
+  if (args.agent === 'custom') {
+    const raw = args.process_pattern?.trim()
+    if (!raw) return null
+    return new RegExp(raw, 'i')
+  }
+  if (args.agent === 'codex') {
+    return /(^|[\s/])(codex|codex-aarch64-a)([\s]|$)/i
+  }
+  if (args.agent === 'claude-code') {
+    return /(^|[\s/])claude([\s]|$)/i
+  }
+  return /(^|[\s/])opencode([\s]|$)/i
+}
+
+async function listPanes(execLike: typeof execFile): Promise<PaneRow[]> {
+  const exec = promisify(execLike)
+  const { stdout } = await exec(
+    'tmux',
+    ['list-panes', '-a', '-F', '#{pane_id}\t#{pane_tty}'],
+    { timeout: TMUX_LIST_TIMEOUT_MS }
+  )
+  return stdout
+    .split('\n')
+    .map(line => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const [pane_id, pane_tty] = line.split('\t')
+      return {
+        pane_id,
+        tty: normalizeTty(pane_tty) ?? '',
+      }
+    })
+}
+
+async function readPidInfo(
+  execLike: typeof execFile,
+  pid: number
+): Promise<{ found: boolean; tty?: string; command?: string }> {
+  const exec = promisify(execLike)
+  try {
+    const { stdout } = await exec(
+      'ps',
+      ['-p', String(pid), '-o', 'tty=,command='],
+      { timeout: PS_LIST_TIMEOUT_MS }
+    )
+    const line = stdout
+      .split('\n')
+      .map(value => value.trim())
+      .find(Boolean)
+    if (!line) return { found: false }
+    const match = line.match(/^(\S+)\s+(.*)$/)
+    if (!match) return { found: false }
+    return {
+      found: true,
+      tty: normalizeTty(match[1]),
+      command: match[2]?.trim(),
+    }
+  } catch {
+    return { found: false }
+  }
+}
+
+async function ttyProcesses(
+  execLike: typeof execFile,
+  tty: string
+): Promise<string[]> {
+  const exec = promisify(execLike)
+  const { stdout } = await exec(
+    'ps',
+    ['-t', tty, '-o', 'pid=,ppid=,stat=,command='],
+    { timeout: PS_LIST_TIMEOUT_MS }
+  )
+  return stdout
+    .split('\n')
+    .map(line => line.trimEnd())
+    .filter(Boolean)
+}
+
+function matchAgentProcess(
+  agent: DetectAgentKind,
+  lines: string[],
+  pattern: RegExp
+): boolean {
+  return lines.some((line) => {
+    if (isHelperProcess(agent, line)) return false
+    return pattern.test(line)
+  })
+}
+
+function isHelperProcess(agent: DetectAgentKind, command: string): boolean {
+  if (agent !== 'codex') return false
+  return /codex\s+app-server/i.test(command) ||
+    /Codex Computer Use\.app/i.test(command) ||
+    /SkyComputerUseClient/i.test(command)
+}
+
+export async function bindRuntimeIdentity(
+  input: BindRuntimeIdentityInput,
+  deps: BindRuntimeIdentityDeps = {}
+): Promise<BindRuntimeIdentityResult> {
+  const execLike = deps.execFile ?? execFile
+  const pattern = commandPattern(input)
+  if (!pattern) return { error: 'invalid_process_pattern' }
+
+  let panes: PaneRow[]
+  try {
+    panes = await listPanes(execLike)
+  } catch (error) {
+    return {
+      error: 'tmux_unavailable',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  if (input.ui_pid !== undefined) {
+    if (!Number.isInteger(input.ui_pid) || input.ui_pid <= 0) {
+      return { error: 'invalid_ui_pid' }
+    }
+    const pidInfo = await readPidInfo(execLike, input.ui_pid)
+    if (!pidInfo.found) return { error: 'pid_not_found' }
+    if (
+      !pidInfo.command ||
+      isHelperProcess(input.agent, pidInfo.command) ||
+      !pattern.test(pidInfo.command)
+    ) {
+      return { error: 'agent_process_mismatch' }
+    }
+    if (!pidInfo.tty) return { error: 'pid_has_no_tty' }
+    const candidates = panes.filter(pane => pane.tty === pidInfo.tty)
+    if (candidates.length === 0) return { error: 'tmux_pane_not_found' }
+    if (candidates.length > 1) {
+      return {
+        error: 'ambiguous_tty_match',
+        candidates: candidates.map(candidate => ({
+          pane_id: candidate.pane_id,
+          tty: candidate.tty,
+        })),
+      }
+    }
+    const candidate = candidates[0]
+    const explicitPane = input.tmux_pane_id?.trim()
+    if (explicitPane && explicitPane !== candidate.pane_id) {
+      return {
+        error: 'pid_pane_tty_mismatch',
+        detail: {
+          pid_tty: pidInfo.tty,
+          pane_tty: candidate.tty,
+        },
+      }
+    }
+    return {
+      ok: true,
+      tmux_pane_id: candidate.pane_id,
+      verification_mode: 'verified_pid_tty_pane',
+      tty: pidInfo.tty,
+      ui_pid: input.ui_pid,
+    }
+  }
+
+  const tty = normalizeTty(input.ui_tty)
+  const paneId = input.tmux_pane_id?.trim()
+  if (!tty || !paneId) return { error: 'invalid_runtime_identity' }
+  const pane = panes.find(candidate => candidate.pane_id === paneId)
+  if (!pane) return { error: 'tmux_pane_not_found' }
+  if (pane.tty !== tty) {
+    return {
+      error: 'pid_pane_tty_mismatch',
+      detail: {
+        pid_tty: tty,
+        pane_tty: pane.tty,
+      },
+    }
+  }
+  const processes = await ttyProcesses(execLike, tty)
+  if (!matchAgentProcess(input.agent, processes, pattern)) {
+    return { error: 'tty_maps_to_no_agent_process' }
+  }
+  return {
+    ok: true,
+    tmux_pane_id: paneId,
+    verification_mode: 'verified_tty_pane',
+    tty,
+  }
+}

package/src/daemon/server.ts

@@ -0,0 +1,64 @@
+import Fastify, { type FastifyInstance } from 'fastify'
+import { openDb } from '../storage/db.js'
+import { applySchema } from '../storage/schema.js'
+import { makeAuthHook } from './auth.js'
+import { mountMcp } from '../mcp/transport.js'
+import { runCleanup } from './cleanup.js'
+import { SseFanout } from './sse-fanout.js'
+import { ChannelWakeFanout } from './channel-wake-fanout.js'
+import { clearAllRetries } from '../mcp/poke-retry.js'
+
+export interface ServerOpts {
+  dbPath: string
+  token?: string
+  cleanupIntervalMs?: number
+  fanout?: SseFanout
+  channelWakeFanout?: ChannelWakeFanout
+}
+export interface StartOpts extends ServerOpts { port: number; host?: string }
+
+const DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 120_000
+
+function parsePositiveInt(raw: string | undefined, fallback: number): number {
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : fallback
+}
+
+export async function buildServer(opts: ServerOpts): Promise<FastifyInstance> {
+  const keepAliveTimeout = parsePositiveInt(process.env.KEEP_ALIVE_TIMEOUT_MS, DEFAULT_KEEP_ALIVE_TIMEOUT_MS)
+  const app = Fastify({ logger: false, keepAliveTimeout })
+  app.server.headersTimeout = keepAliveTimeout + 1000
+  const db = openDb(opts.dbPath)
+  applySchema(db)
+  const startedAt = Date.now()
+  const version = '0.1.0'
+  const fanout = opts.fanout ?? new SseFanout()
+  const channelWakeFanout = opts.channelWakeFanout ?? new ChannelWakeFanout()
+  app.addHook('onRequest', makeAuthHook(opts.token))
+  app.get('/health', async () => ({ ok: true, version, uptime_seconds: Math.floor((Date.now() - startedAt) / 1000) }))
+  mountMcp(app, db, fanout, channelWakeFanout)
+
+  const cleanupIntervalMs = opts.cleanupIntervalMs
+    ?? Number(process.env.CLEANUP_INTERVAL_MS ?? 60 * 60 * 1000)
+  const interval = setInterval(() => {
+    try { runCleanup(db) } catch { /* best-effort */ }
+  }, cleanupIntervalMs)
+  if (typeof interval.unref === 'function') interval.unref()
+
+  app.addHook('onClose', async () => {
+    clearInterval(interval)
+    clearAllRetries()
+    fanout.stopAll()
+    db.close()
+  })
+  return app
+}
+
+export async function startServer(opts: StartOpts): Promise<{ app: FastifyInstance; port: number; host: string }> {
+  const app = await buildServer(opts)
+  const host = opts.host ?? '127.0.0.1'
+  await app.listen({ port: opts.port, host })
+  const addr = app.server.address()
+  const port = addr && typeof addr === 'object' ? addr.port : opts.port
+  return { app, port, host }
+}

package/src/daemon/shutdown.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance } from 'fastify'
+import { releasePidFile } from './pid.js'
+
+export function wireShutdown(app: FastifyInstance, pidPath: string): void {
+  const handler = async (_signal: NodeJS.Signals) => {
+    try { await app.close() } catch { /* ignore */ }
+    releasePidFile(pidPath)
+    process.exit(0)
+  }
+  process.once('SIGTERM', handler)
+  process.once('SIGINT', handler)
+}

package/src/daemon/sse-fanout.ts

@@ -0,0 +1,96 @@
+import type Database from 'better-sqlite3'
+
+export interface SseSink {
+  send(msg: Record<string, unknown>): void
+  sendHeartbeat(): void
+  close(): void
+}
+
+interface Session { agent_id: string; team: string; sink: SseSink }
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000
+
+function resolveHeartbeatIntervalMs(opt?: number): number {
+  if (typeof opt === 'number' && opt > 0) return opt
+  const n = Number(process.env.HEARTBEAT_INTERVAL_MS)
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_HEARTBEAT_INTERVAL_MS
+}
+
+export class SseFanout {
+  private sessions = new Map<string, Session>()
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined
+  private readonly heartbeatIntervalMs: number
+
+  constructor(opts: { heartbeatIntervalMs?: number } = {}) {
+    this.heartbeatIntervalMs = resolveHeartbeatIntervalMs(opts.heartbeatIntervalMs)
+  }
+
+  attach(agent_id: string, team: string, sink: SseSink): void {
+    const prior = this.sessions.get(agent_id)
+    if (prior && prior.sink !== sink) {
+      try { prior.sink.close() } catch { /* ignore */ }
+    }
+    const wasEmpty = this.sessions.size === 0
+    this.sessions.set(agent_id, { agent_id, team, sink })
+    if (wasEmpty) this.startHeartbeat()
+  }
+
+  rebind(agent_id: string, team: string): void {
+    const s = this.sessions.get(agent_id)
+    if (!s) return
+    this.sessions.set(agent_id, { agent_id, team, sink: s.sink })
+  }
+
+  detach(agent_id: string): void {
+    const s = this.sessions.get(agent_id)
+    if (s) { try { s.sink.close() } catch { /* ignore */ } this.sessions.delete(agent_id) }
+    if (this.sessions.size === 0) this.stopHeartbeat()
+  }
+
+  stopAll(): void {
+    this.stopHeartbeat()
+    for (const s of this.sessions.values()) { try { s.sink.close() } catch { /* ignore */ } }
+    this.sessions.clear()
+  }
+
+  peek(): Array<{ agent_id: string; team: string }> {
+    return Array.from(this.sessions.values()).map(s => ({ agent_id: s.agent_id, team: s.team }))
+  }
+
+  emitContractEvent(
+    db: Database.Database,
+    args: { to_team: string; contract_name: string; version: number; event_id: number; diff: unknown | null }
+  ): void {
+    const subs = db.prepare(
+      `SELECT agent_id FROM contract_subscriptions WHERE team=? AND contract_name=?`
+    ).all(args.to_team, args.contract_name) as Array<{ agent_id: string }>
+    const subscribedSet = new Set(subs.map(s => s.agent_id))
+    for (const session of this.sessions.values()) {
+      if (session.team !== args.to_team) continue
+      if (!subscribedSet.has(session.agent_id)) continue
+      try {
+        session.sink.send({
+          type: 'contract_event',
+          event_id: args.event_id,
+          contract_name: args.contract_name,
+          version: args.version,
+          diff: args.diff
+        })
+      } catch { /* broken sink; swallow */ }
+    }
+  }
+
+  private startHeartbeat(): void {
+    if (this.heartbeatTimer) return
+    this.heartbeatTimer = setInterval(() => {
+      for (const s of this.sessions.values()) {
+        try { s.sink.sendHeartbeat() } catch { /* ignore */ }
+      }
+    }, this.heartbeatIntervalMs)
+    if (typeof this.heartbeatTimer.unref === 'function') this.heartbeatTimer.unref()
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = undefined }
+  }
+}

package/src/daemon/tmux-cli.ts

@@ -0,0 +1,61 @@
+import { execFile, spawn } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const pExecFile = promisify(execFile)
+
+let _isTmuxAvailable: boolean | null = null
+
+export async function isTmuxAvailable(): Promise<boolean> {
+  if (_isTmuxAvailable !== null) return _isTmuxAvailable
+  try {
+    await pExecFile('tmux', ['-V'])
+    _isTmuxAvailable = true
+  } catch {
+    _isTmuxAvailable = false
+  }
+  return _isTmuxAvailable
+}
+
+const TMUX_CAPTURE_TIMEOUT_MS = 5_000
+
+export async function capturePaneTail(paneId: string, lines = 8): Promise<string> {
+  const { stdout } = await pExecFile(
+    'tmux',
+    ['capture-pane', '-t', paneId, '-p', '-S', `-${lines}`],
+    { timeout: TMUX_CAPTURE_TIMEOUT_MS }
+  )
+  return stdout
+}
+
+export function loadBuffer(bufferName: string, prompt: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('tmux', ['load-buffer', '-b', bufferName, '-'])
+    let stderr = ''
+    child.on('error', reject)
+    if (child.stderr) {
+      child.stderr.on('data', (b: Buffer) => { stderr += b.toString('utf8') })
+    }
+    child.on('close', (code: number) => {
+      if (code === 0) resolve()
+      else reject(new Error(`load-buffer exit ${code}: ${stderr}`))
+    })
+    child.stdin.write(Buffer.from(prompt, 'utf8'))
+    child.stdin.end()
+  })
+}
+
+export async function pasteBuffer(bufferName: string, paneId: string): Promise<void> {
+  await pExecFile('tmux', ['paste-buffer', '-b', bufferName, '-t', paneId, '-p', '-d'])
+}
+
+export async function sendEnter(paneId: string): Promise<void> {
+  await pExecFile('tmux', ['send-keys', '-t', paneId, 'Enter'])
+}
+
+export function _resetTmuxAvailableCache(): void {
+  _isTmuxAvailable = null
+}
+
+export function _setTmuxAvailableForTest(value: boolean): void {
+  _isTmuxAvailable = value
+}