cross-agent-teams-mcp 0.2.0

package/src/mcp/auto-bind-codex-pane.ts

@@ -0,0 +1,170 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { CodexPanePreRegRepo, CodexPanePreRegRow } from './codex-pane-pre-register-repo.js'
+import type { BindRuntimeIdentityService } from './bind-runtime-identity.js'
+
+const TMUX_LIST_TIMEOUT_MS = 3_000
+const PS_LIST_TIMEOUT_MS = 3_000
+
+export interface PaneTtyEntry {
+  pane_id: string
+  tty: string
+}
+
+export interface AutoBindCodexPaneDeps {
+  listPanes?: () => Promise<PaneTtyEntry[]>
+  ttyProcesses?: (tty: string) => Promise<string[]>
+  now?: () => Date
+}
+
+export interface AutoBindCodexPaneInput {
+  callerAgentId: string
+  repo: CodexPanePreRegRepo
+  bindRuntimeIdentitySvc: BindRuntimeIdentityService
+}
+
+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
+}
+
+async function defaultListPanes(): Promise<PaneTtyEntry[]> {
+  const exec = promisify(execFile)
+  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 defaultTtyProcesses(tty: string): Promise<string[]> {
+  const exec = promisify(execFile)
+  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 parsePid(line: string): number | undefined {
+  const match = line.trim().match(/^(\d+)\s/)
+  if (!match) return undefined
+  const pid = Number(match[1])
+  if (!Number.isInteger(pid) || pid <= 0) return undefined
+  return pid
+}
+
+function isCodexRemoteProcess(line: string): boolean {
+  if (!/codex/i.test(line)) return false
+  if (/codex\s+app-server/i.test(line)) return false
+  return /codex(?:-aarch64-a)?\s+.*--remote/i.test(line) || /codex(?:-aarch64-a)?\s+--remote/i.test(line)
+}
+
+function argvContainsUuid(line: string, uuid: string): boolean {
+  return line.includes(`xats.agent_id="${uuid}"`)
+}
+
+interface Candidate {
+  row: CodexPanePreRegRow
+  pane_id: string
+  ui_pid: number
+}
+
+/**
+ * Scan pending pre-regs, look up tmux panes and their processes, and bind
+ * the caller agent row when exactly one pre-reg maps to a live codex --remote
+ * process whose argv contains the stored UUID.
+ *
+ * Returns true only when bind + consume succeeded.  Any error path returns
+ * false without propagating.
+ */
+// Test hook: allows integration tests to override the tmux/ps probes that
+// would otherwise need a real tmux session.  Production paths pass `deps`
+// explicitly; when they do not, we fall through to these overrides, then to
+// the real child_process-backed defaults.
+export const __testOverrides: AutoBindCodexPaneDeps = {}
+
+export async function autoBindCodexPane(
+  input: AutoBindCodexPaneInput,
+  deps: AutoBindCodexPaneDeps = {}
+): Promise<boolean> {
+  const listPanes = deps.listPanes ?? __testOverrides.listPanes ?? defaultListPanes
+  const ttyProcesses = deps.ttyProcesses ?? __testOverrides.ttyProcesses ?? defaultTtyProcesses
+  const now = deps.now ?? __testOverrides.now ?? (() => new Date())
+
+  try {
+    const nowIso = now().toISOString()
+    input.repo.deleteExpired(nowIso)
+    const pending = input.repo.listUnexpired(nowIso)
+    if (pending.length === 0) return false
+
+    let panes: PaneTtyEntry[]
+    try {
+      panes = await listPanes()
+    } catch {
+      return false
+    }
+
+    const paneIndex = new Map<string, PaneTtyEntry>()
+    for (const pane of panes) {
+      if (pane.pane_id) paneIndex.set(pane.pane_id, pane)
+    }
+
+    const ttyProcessCache = new Map<string, string[]>()
+    const candidates: Candidate[] = []
+
+    for (const row of pending) {
+      const pane = paneIndex.get(row.pane_id)
+      if (!pane || !pane.tty) continue
+      let procs = ttyProcessCache.get(pane.tty)
+      if (procs === undefined) {
+        try {
+          procs = await ttyProcesses(pane.tty)
+        } catch {
+          procs = []
+        }
+        ttyProcessCache.set(pane.tty, procs)
+      }
+      const matching = procs.filter(line =>
+        isCodexRemoteProcess(line) && argvContainsUuid(line, row.xats_agent_id)
+      )
+      if (matching.length !== 1) continue
+      const pid = parsePid(matching[0])
+      if (pid === undefined) continue
+      candidates.push({ row, pane_id: pane.pane_id, ui_pid: pid })
+    }
+
+    if (candidates.length !== 1) return false
+
+    const chosen = candidates[0]
+    const bindResult = await input.bindRuntimeIdentitySvc.bind({
+      callerAgentId: input.callerAgentId,
+      agent: 'codex',
+      ui_pid: chosen.ui_pid,
+    })
+    if (!('ok' in bindResult) || !bindResult.ok) return false
+
+    input.repo.takeByPaneId(chosen.pane_id)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/mcp/auto-poke-fanout.ts

@@ -0,0 +1,129 @@
+import { runQuietGuard } from './poke-guard.js'
+import { isTmuxAvailable } from '../daemon/tmux-cli.js'
+import { scheduleRetry as defaultScheduleRetry, type RetryAgentLookup, type RetryContext } from './poke-retry.js'
+import type { DeliverySpec } from '../lib/delivery-spec.js'
+
+export type AutoPokeSkipReason = 'no_pane' | 'guard_failed' | 'tmux_unavailable' | 'self'
+
+export interface AutoPokeArgs {
+  team: string
+  fromAgentId: string
+  targetAgentId: string
+  paneId: string | null
+  body: string
+}
+
+export type AutoPokeFn = (args: AutoPokeArgs) => Promise<{ ok: true } | { ok: false; reason?: AutoPokeSkipReason }>
+
+export interface AutoPokeRecipient {
+  agent_id: string
+  tmux_pane_id: string | null
+  delivery?: DeliverySpec
+}
+
+export interface FanoutDeps {
+  poke?: AutoPokeFn
+  tmuxAvailable?: () => Promise<boolean>
+}
+
+export interface RetryScheduleCtx {
+  messageId: string
+  sentAt: string
+  lookupAgentFn: (agentId: string) => RetryAgentLookup | undefined
+  scheduleRetryFn?: (ctx: RetryContext) => void
+  updateStatusFn?: RetryContext['updateStatusFn']
+}
+
+export interface FanoutResult {
+  poked: boolean
+  skipReasons: Array<{ agent_id: string; reason: AutoPokeSkipReason }>
+  deliveredAgentIds: string[]
+  retryScheduledCount: number
+}
+
+function hasNonTmuxTransport(recipient: AutoPokeRecipient): boolean {
+  return recipient.delivery !== undefined && recipient.delivery.kind !== 'none'
+}
+
+// Recipients are supplied by the caller; no team filter is applied here, so cross-team fan-out works transparently.
+export async function fanoutAutoPoke(args: {
+  team: string
+  fromAgentId: string
+  recipients: AutoPokeRecipient[]
+  body: string
+  deps: FanoutDeps
+  retry?: RetryScheduleCtx
+}): Promise<FanoutResult> {
+  const pokeFn = args.deps.poke
+  const tmuxAvail = args.deps.tmuxAvailable ?? isTmuxAvailable
+
+  const results = await Promise.all(args.recipients.map(async (r) => {
+    try {
+      const nonTmuxTransport = hasNonTmuxTransport(r)
+      if (r.agent_id === args.fromAgentId) {
+        return { agent_id: r.agent_id, poked: false, reason: 'self' as AutoPokeSkipReason, paneId: null as string | null }
+      }
+      if (!nonTmuxTransport && !r.tmux_pane_id) {
+        return { agent_id: r.agent_id, poked: false, reason: 'no_pane' as AutoPokeSkipReason, paneId: null }
+      }
+      if (!nonTmuxTransport && !(await tmuxAvail())) {
+        return { agent_id: r.agent_id, poked: false, reason: 'tmux_unavailable' as AutoPokeSkipReason, paneId: r.tmux_pane_id }
+      }
+      if (!pokeFn) {
+        return { agent_id: r.agent_id, poked: false, reason: 'tmux_unavailable' as AutoPokeSkipReason, paneId: r.tmux_pane_id }
+      }
+      if (!nonTmuxTransport) {
+        const guard = await runQuietGuard(r.tmux_pane_id!)
+        if (guard === 'fail') {
+          return { agent_id: r.agent_id, poked: false, reason: 'guard_failed' as AutoPokeSkipReason, paneId: r.tmux_pane_id }
+        }
+      }
+      const out = await pokeFn({
+        team: args.team,
+        fromAgentId: args.fromAgentId,
+        targetAgentId: r.agent_id,
+        paneId: r.tmux_pane_id,
+        body: args.body
+      })
+      if (out.ok) return { agent_id: r.agent_id, poked: true, reason: undefined, paneId: r.tmux_pane_id }
+      return {
+        agent_id: r.agent_id,
+        poked: false,
+        reason: (out.reason ?? 'guard_failed') as AutoPokeSkipReason,
+        paneId: r.tmux_pane_id
+      }
+    } catch {
+      return { agent_id: r.agent_id, poked: false, reason: 'guard_failed' as AutoPokeSkipReason, paneId: r.tmux_pane_id }
+    }
+  }))
+
+  let retryScheduledCount = 0
+  if (args.retry && pokeFn) {
+    const scheduleFn = args.retry.scheduleRetryFn ?? defaultScheduleRetry
+    for (const res of results) {
+      if (!res.poked && res.reason === 'guard_failed' && res.paneId) {
+        scheduleFn({
+          agentId: res.agent_id,
+          messageId: args.retry.messageId,
+          fromAgentId: args.fromAgentId,
+          body: args.body,
+          team: args.team,
+          sentAt: args.retry.sentAt,
+          paneId: res.paneId,
+          paneGuardFn: runQuietGuard,
+          pokeFn: async (pokeArgs) => { await pokeFn(pokeArgs) },
+          lookupAgentFn: args.retry.lookupAgentFn,
+          updateStatusFn: args.retry.updateStatusFn
+        })
+        retryScheduledCount += 1
+      }
+    }
+  }
+
+  const poked = results.some(x => x.poked)
+  const skipReasons = results
+    .filter(x => !x.poked && x.reason !== undefined)
+    .map(x => ({ agent_id: x.agent_id, reason: x.reason as AutoPokeSkipReason }))
+  const deliveredAgentIds = results.filter(x => x.poked).map(x => x.agent_id)
+  return { poked, skipReasons, deliveredAgentIds, retryScheduledCount }
+}

package/src/mcp/bind-channel.ts

@@ -0,0 +1,39 @@
+import type Database from 'better-sqlite3'
+import type { ChannelWakeFanout } from '../daemon/channel-wake-fanout.js'
+import { AgentsRepo } from '../storage/agents-repo.js'
+import { CHANNEL_PROXY_ROLE } from './subscribe-channel-wake.js'
+
+export interface BindInput {
+  callerAgentId: string
+  channel_session_id: string
+}
+
+export type BindResult =
+  | { ok: true }
+  | { error: 'unknown_agent' | 'forbidden_role' | 'invalid_channel_session_id' | 'unknown_channel_session' }
+
+export class BindChannelService {
+  private readonly repo: AgentsRepo
+
+  constructor(
+    db: Database.Database,
+    private readonly fanout: ChannelWakeFanout
+  ) {
+    this.repo = new AgentsRepo(db)
+  }
+
+  bind(input: BindInput): BindResult {
+    const csid = input.channel_session_id?.trim()
+    if (!csid) return { error: 'invalid_channel_session_id' }
+    const caller = this.repo.getById(input.callerAgentId)
+    if (!caller) return { error: 'unknown_agent' }
+    if (caller.role === CHANNEL_PROXY_ROLE) return { error: 'forbidden_role' }
+    if (!this.fanout.has(csid)) return { error: 'unknown_channel_session' }
+    this.repo.setClient(input.callerAgentId, 'claude-code')
+    this.repo.setDelivery(input.callerAgentId, {
+      kind: 'claude-channel',
+      channel_session_id: csid,
+    })
+    return { ok: true }
+  }
+}

package/src/mcp/bind-runtime-identity.ts

@@ -0,0 +1,43 @@
+import type Database from 'better-sqlite3'
+import {
+  bindRuntimeIdentity,
+  type BindRuntimeIdentityInput,
+  type BindRuntimeIdentityResult,
+} from '../daemon/runtime-identity.js'
+import { AgentsRepo } from '../storage/agents-repo.js'
+
+export interface BindRuntimeIdentityServiceInput extends BindRuntimeIdentityInput {
+  callerAgentId: string
+}
+
+export type BindRuntimeIdentityServiceResult =
+  | ({ ok: true } & Omit<Extract<BindRuntimeIdentityResult, { ok: true }>, 'ok'>)
+  | Extract<BindRuntimeIdentityResult, { error: string }>
+  | { error: 'unknown_agent' }
+
+export class BindRuntimeIdentityService {
+  private readonly repo: AgentsRepo
+
+  constructor(db: Database.Database) {
+    this.repo = new AgentsRepo(db)
+  }
+
+  async bind(
+    input: BindRuntimeIdentityServiceInput
+  ): Promise<BindRuntimeIdentityServiceResult> {
+    const caller = this.repo.getById(input.callerAgentId)
+    if (!caller) return { error: 'unknown_agent' }
+
+    const result = await bindRuntimeIdentity(input)
+    if (!('ok' in result) || !result.ok) return result
+
+    this.repo.setRuntimeBinding(input.callerAgentId, {
+      tmux_pane_id: result.tmux_pane_id,
+      runtime_ui_pid: result.ui_pid ?? null,
+      runtime_tty: result.tty,
+      runtime_verification_mode: result.verification_mode,
+    })
+
+    return result
+  }
+}

package/src/mcp/broadcast-to-role.ts

@@ -0,0 +1,127 @@
+import type Database from 'better-sqlite3'
+import { randomUUID } from 'node:crypto'
+import { ONLINE_MS, type AgentsRepo } from '../storage/agents-repo.js'
+import type { EventsOutbox } from '../storage/events-outbox.js'
+import type { FanoutDeps, AutoPokeSkipReason } from './auto-poke-fanout.js'
+import { runFanoutWithRetry } from './fanout-with-retry.js'
+import { parseDeliveryRow } from '../lib/delivery-spec.js'
+import { recordInitialDeliveryStatuses } from './delivery-status.js'
+
+export type BroadcastToRoleDeps = FanoutDeps
+
+export interface BroadcastToRoleInput {
+  from: string
+  to_role: string
+  body: string
+  subject?: string
+  auto_poke?: boolean
+}
+
+interface SuccessResult {
+  message_id: string
+  event_id: number
+  recipients: string[]
+  poked: boolean
+  poke_skip_reasons?: Array<{ agent_id: string; reason: AutoPokeSkipReason }>
+  retry_scheduled: boolean
+  retry_delays_s?: number[]
+}
+
+export type BroadcastToRoleResult = SuccessResult | { error: 'unknown_recipient' }
+
+export class BroadcastToRoleService {
+  constructor(
+    private db: Database.Database,
+    private agents: AgentsRepo,
+    private events: EventsOutbox,
+    private deps: BroadcastToRoleDeps = {}
+  ) {}
+
+  async broadcast(input: BroadcastToRoleInput): Promise<BroadcastToRoleResult> {
+    const fromRow = this.agents.findById(input.from)
+    if (!fromRow) return { error: 'unknown_recipient' }
+    const cutoffIso = new Date(Date.now() - ONLINE_MS).toISOString()
+    const rawRows = this.db.prepare(
+      `SELECT
+         agent_id,
+         tmux_pane_id,
+         delivery_kind,
+         delivery_payload
+       FROM agents
+       WHERE team=? AND role=? AND agent_id != ? AND last_seen_at > ?`
+    ).all(fromRow.team, input.to_role, input.from, cutoffIso) as Array<{
+      agent_id: string
+      tmux_pane_id: string | null
+      delivery_kind: string
+      delivery_payload: string | null
+    }>
+    const rows = rawRows.map((row) => ({
+      agent_id: row.agent_id,
+      tmux_pane_id: row.tmux_pane_id,
+      delivery: parseDeliveryRow(row),
+    }))
+    if (rows.length === 0) return { error: 'unknown_recipient' }
+
+    const recipients = rows.map(r => r.agent_id)
+    const baseId = randomUUID()
+    const inserted = this.insert(fromRow.team, input, recipients, baseId)
+
+    if (input.auto_poke === false) {
+      recordInitialDeliveryStatuses(this.db, {
+        messageId: inserted.message_id,
+        recipients,
+        delivered: new Set(),
+        skipped: [],
+        autoPokeDisabled: true,
+      })
+      return {
+        message_id: inserted.message_id,
+        event_id: inserted.event_id,
+        recipients,
+        poked: false,
+        retry_scheduled: false
+      }
+    }
+
+    const envelope = await runFanoutWithRetry({
+      db: this.db,
+      team: fromRow.team,
+      fromAgentId: input.from,
+      recipients: rows,
+      body: input.body,
+      deps: this.deps,
+      messageId: inserted.message_id,
+      sentAt: inserted.sent_at
+    })
+    return {
+      message_id: inserted.message_id,
+      event_id: inserted.event_id,
+      recipients,
+      ...envelope
+    }
+  }
+
+  private insert(team: string, input: BroadcastToRoleInput, recipients: string[], baseId: string):
+    { message_id: string; event_id: number; sent_at: string } {
+    const tx = this.db.transaction(() => {
+      const event_id = this.events.append({
+        from_team: team,
+        to_team: team,
+        event_type: 'message_sent',
+        actor_agent_id: input.from,
+        payload: { to_role: input.to_role, recipients, subject: input.subject ?? null }
+      })
+      const sent_at = new Date().toISOString()
+      const stmt = this.db.prepare(
+        `INSERT INTO messages (id, event_id, from_team, to_team, from_agent_id, to_agent_id, to_role, subject, body, need_reply, sent_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?)`
+      )
+      for (let i = 0; i < recipients.length; i++) {
+        const id = i === 0 ? baseId : `${baseId}-${i}`
+        stmt.run(id, event_id, team, team, input.from, recipients[i], input.to_role, input.subject ?? null, input.body, 0, sent_at)
+      }
+      return { message_id: baseId, event_id, sent_at }
+    })
+    return tx()
+  }
+}

package/src/mcp/broadcast.ts

@@ -0,0 +1,115 @@
+import type Database from 'better-sqlite3'
+import { randomUUID } from 'node:crypto'
+import { ONLINE_MS, type AgentsRepo } from '../storage/agents-repo.js'
+import type { AutoPokeSkipReason, FanoutDeps } from './auto-poke-fanout.js'
+import { runFanoutWithRetry } from './fanout-with-retry.js'
+import { parseDeliveryRow } from '../lib/delivery-spec.js'
+import { recordInitialDeliveryStatuses } from './delivery-status.js'
+
+export type BroadcastDeps = FanoutDeps
+
+export interface BroadcastInput {
+  from: string
+  body: string
+  subject?: string
+  auto_poke?: boolean
+}
+
+interface SuccessResult {
+  message_id: string
+  event_id: number
+  recipients: string[]
+  poked: boolean
+  poke_skip_reasons?: Array<{ agent_id: string; reason: AutoPokeSkipReason }>
+  retry_scheduled: boolean
+  retry_delays_s?: number[]
+}
+
+export type BroadcastResult = SuccessResult | { error: 'unknown_recipient' }
+
+export class BroadcastService {
+  constructor(
+    private db: Database.Database,
+    private agents: AgentsRepo,
+    private deps: BroadcastDeps = {}
+  ) {}
+
+  async broadcast(input: BroadcastInput): Promise<BroadcastResult> {
+    const fromRow = this.agents.findById(input.from)
+    if (!fromRow) return { error: 'unknown_recipient' }
+    const cutoffIso = new Date(Date.now() - ONLINE_MS).toISOString()
+    const rawRows = this.db.prepare(
+      `SELECT
+         agent_id,
+         tmux_pane_id,
+         delivery_kind,
+         delivery_payload
+       FROM agents
+       WHERE team=? AND agent_id != ? AND last_seen_at > ?`
+    ).all(fromRow.team, input.from, cutoffIso) as Array<{
+      agent_id: string
+      tmux_pane_id: string | null
+      delivery_kind: string
+      delivery_payload: string | null
+    }>
+    const rows = rawRows.map((row) => ({
+      agent_id: row.agent_id,
+      tmux_pane_id: row.tmux_pane_id,
+      delivery: parseDeliveryRow(row),
+    }))
+    if (rows.length === 0) return { error: 'unknown_recipient' }
+    const recipients = rows.map(r => r.agent_id)
+    const baseId = randomUUID()
+    const inserted = this.insertBroadcast(fromRow.team, input.from, recipients, input.body, input.subject, baseId)
+
+    if (input.auto_poke === false) {
+      recordInitialDeliveryStatuses(this.db, {
+        messageId: inserted.message_id,
+        recipients,
+        delivered: new Set(),
+        skipped: [],
+        autoPokeDisabled: true,
+      })
+      return { ...inserted, recipients, poked: false, retry_scheduled: false }
+    }
+
+    const envelope = await runFanoutWithRetry({
+      db: this.db,
+      team: fromRow.team,
+      fromAgentId: input.from,
+      recipients: rows,
+      body: input.body,
+      deps: this.deps,
+      messageId: inserted.message_id,
+      sentAt: inserted.sent_at
+    })
+    return {
+      message_id: inserted.message_id,
+      event_id: inserted.event_id,
+      recipients,
+      ...envelope
+    }
+  }
+
+  private insertBroadcast(team: string, from: string, recipients: string[], body: string,
+                          subject: string | undefined, baseId: string): { message_id: string; event_id: number; sent_at: string } {
+    const tx = this.db.transaction(() => {
+      const event_id = Number(this.db.prepare(
+        `INSERT INTO events (from_team, to_team, event_type, actor_agent_id, payload, created_at) VALUES (?,?,?,?,?,?)`
+      ).run(team, team, 'message_sent', from,
+        JSON.stringify({ to_role: '*broadcast*', recipients, subject: subject ?? null }),
+        new Date().toISOString()).lastInsertRowid)
+      const sent_at = new Date().toISOString()
+      const insert = this.db.prepare(
+        `INSERT INTO messages (id, event_id, from_team, to_team, from_agent_id, to_agent_id, to_role, subject, body, need_reply, sent_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?)`
+      )
+      for (let i = 0; i < recipients.length; i++) {
+        const id = i === 0 ? baseId : `${baseId}-${i}`
+        insert.run(id, event_id, team, team, from, recipients[i], '*broadcast*', subject ?? null, body, 0, sent_at)
+      }
+      return { message_id: baseId, event_id, sent_at }
+    })
+    return tx()
+  }
+}