cross-agent-teams-mcp 0.2.0

package/src/mcp/get-inbox.ts

@@ -0,0 +1,57 @@
+import type Database from 'better-sqlite3'
+import type { AgentsRepo } from '../storage/agents-repo.js'
+
+export interface InboxMessage {
+  id: string
+  event_id: number
+  from_team: string
+  to_team: string
+  from_agent_id: string
+  from_role: string | null
+  to_agent_id: string | null
+  to_role: string | null
+  subject: string | null
+  body: string
+  need_reply: boolean
+  sent_at: string
+}
+
+export interface InboxResult {
+  messages: InboxMessage[]
+  has_more: boolean
+  last_event_id: number
+}
+
+export class GetInboxService {
+  constructor(private db: Database.Database, private agents: AgentsRepo) {}
+
+  get(args: { caller: string; since_event_id?: number; limit?: number }): InboxResult {
+    const caller = this.agents.findById(args.caller)
+    if (!caller) return { messages: [], has_more: false, last_event_id: args.since_event_id ?? 0 }
+    const callerTeam = caller.team
+    const callerRole = this.db.prepare('SELECT role FROM agents WHERE agent_id=?')
+      .get(args.caller) as { role: string } | undefined
+    const limit = Math.min(args.limit ?? 50, 200)
+    const since = args.since_event_id ?? 0
+    const rows = this.db.prepare(
+      `SELECT m.id, m.event_id, m.from_team, m.to_team, m.from_agent_id, m.to_agent_id, m.to_role, m.subject, m.body, m.need_reply, m.sent_at,
+              a.role as from_role
+         FROM messages m
+         LEFT JOIN agents a ON a.agent_id = m.from_agent_id
+        WHERE m.to_team = ?
+          AND m.event_id > ?
+          AND ( m.to_agent_id = ? OR (m.to_role IS NOT NULL AND m.to_role = ?) )
+        ORDER BY m.event_id ASC
+        LIMIT ?`
+    ).all(callerTeam, since, args.caller, callerRole?.role ?? '__none__', limit + 1) as Array<
+      Omit<InboxMessage, 'need_reply'> & { need_reply: number }
+    >
+    const has_more = rows.length > limit
+    const trimmed = (has_more ? rows.slice(0, limit) : rows).map(row => ({
+      ...row,
+      need_reply: row.need_reply === 1,
+    }))
+    const last_event_id = trimmed.length > 0 ? trimmed[trimmed.length - 1].event_id : since
+    return { messages: trimmed, has_more, last_event_id }
+  }
+}

package/src/mcp/identity.ts

@@ -0,0 +1,8 @@
+export class IdentityMismatchError extends Error {
+  readonly code = 'identity_mismatch'
+  constructor() { super('identity_mismatch') }
+}
+
+export function ensureCallerMatches(sessionId: string, claimedAgentId: string | undefined): void {
+  if (claimedAgentId && claimedAgentId !== sessionId) throw new IdentityMismatchError()
+}

package/src/mcp/pending-contract-events.ts

@@ -0,0 +1,36 @@
+import type Database from 'better-sqlite3'
+import type { AgentsRepo } from '../storage/agents-repo.js'
+
+export interface ContractEventOut {
+  event_id: number
+  contract_name: string
+  version: number
+  diff: unknown | null
+  registered_at: string
+}
+
+export class PendingContractEventsService {
+  constructor(private db: Database.Database, private agents: AgentsRepo) {}
+
+  poll(args: { caller: string; since_event_id?: number; limit?: number }): {
+    events: ContractEventOut[]; has_more: boolean; last_event_id: number
+  } {
+    const caller = this.agents.findById(args.caller)
+    if (!caller) return { events: [], has_more: false, last_event_id: args.since_event_id ?? 0 }
+    const limit = Math.min(args.limit ?? 100, 500)
+    const since = args.since_event_id ?? 0
+    const rows = this.db.prepare(
+      `SELECT event_id, payload, created_at FROM events
+         WHERE to_team=? AND event_type='contract_registered' AND event_id > ?
+         ORDER BY event_id ASC LIMIT ?`
+    ).all(caller.team, since, limit + 1) as Array<{ event_id: number; payload: string; created_at: string }>
+    const has_more = rows.length > limit
+    const trimmed = has_more ? rows.slice(0, limit) : rows
+    const events = trimmed.map(r => {
+      const p = JSON.parse(r.payload) as { name: string; version: number; diff: unknown | null }
+      return { event_id: r.event_id, contract_name: p.name, version: p.version, diff: p.diff, registered_at: r.created_at }
+    })
+    const last_event_id = trimmed.length > 0 ? trimmed[trimmed.length - 1].event_id : since
+    return { events, has_more, last_event_id }
+  }
+}

package/src/mcp/poke-guard.ts

@@ -0,0 +1,32 @@
+import { capturePaneTail as _capture } from '../daemon/tmux-cli.js'
+
+const DEFAULT_QUIET_MS = 2000
+const GUARD_TAIL_LINES = 8
+
+type CaptureFn = (paneId: string, lines?: number) => Promise<string>
+
+let _captureImpl: CaptureFn = _capture
+
+export function __setCapturePaneTail(fn: CaptureFn): void {
+  _captureImpl = fn
+}
+
+export function __resetCapturePaneTail(): void {
+  _captureImpl = _capture
+}
+
+export function resolveQuietMs(opt?: number): number {
+  if (typeof opt === 'number' && Number.isInteger(opt) && opt > 0) return opt
+  const raw = process.env.POKE_QUIET_MS
+  if (raw === undefined) return DEFAULT_QUIET_MS
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_QUIET_MS
+}
+
+export async function runQuietGuard(paneId: string, quietMs?: number): Promise<'pass' | 'fail'> {
+  const ms = resolveQuietMs(quietMs)
+  const before = await _captureImpl(paneId, GUARD_TAIL_LINES)
+  await new Promise(r => setTimeout(r, ms))
+  const after = await _captureImpl(paneId, GUARD_TAIL_LINES)
+  return before === after ? 'pass' : 'fail'
+}

package/src/mcp/poke-retry.ts

@@ -0,0 +1,159 @@
+export const RETRY_DELAYS_MS = [30_000, 180_000, 600_000] as const
+export const RETRY_DELAYS_S = [30, 180, 600] as const
+
+export interface RetryPokeArgs {
+  team: string
+  fromAgentId: string
+  targetAgentId: string
+  paneId: string
+  body: string
+}
+
+export interface RetryAgentLookup {
+  agent_id: string
+  tmux_pane_id: string | null
+  last_seen_at: string
+}
+
+export interface RetryContext {
+  agentId: string
+  messageId: string
+  fromAgentId: string
+  body: string
+  team: string
+  sentAt: string
+  paneId: string
+  paneGuardFn: (paneId: string) => Promise<'pass' | 'fail'>
+  pokeFn: (args: RetryPokeArgs) => Promise<void>
+  lookupAgentFn: (agentId: string) => RetryAgentLookup | undefined
+  updateStatusFn?: (args: {
+    agentId: string
+    wake_status: 'delivered' | 'retrying' | 'skipped' | 'failed'
+    skip_reason?: 'guard_failed' | 'no_pane' | 'recipient_active' | 'retry_exhausted' | null
+    retry_attempts?: number
+    delivered_at?: string | null
+  }) => void
+}
+
+interface RetryEntry {
+  timer?: ReturnType<typeof setTimeout>
+  attempt: number
+  ctx: RetryContext
+}
+
+const retryMap = new Map<string, RetryEntry>()
+
+function keyOf(ctx: RetryContext): string {
+  return `${ctx.messageId}:${ctx.agentId}`
+}
+
+// Retry tick resolves the recipient via ctx.lookupAgentFn (caller-provided), which is team-agnostic; cross-team retries are supported.
+export function scheduleRetry(ctx: RetryContext): void {
+  const key = keyOf(ctx)
+  cancelRetry(key)
+  retryMap.set(key, { attempt: 0, ctx })
+  enqueueNext(key)
+}
+
+function enqueueNext(key: string): void {
+  const entry = retryMap.get(key)
+  if (!entry) return
+  if (entry.attempt >= RETRY_DELAYS_MS.length) {
+    retryMap.delete(key)
+    return
+  }
+  const delay = RETRY_DELAYS_MS[entry.attempt]
+  entry.timer = setTimeout(() => { void tick(key) }, delay)
+}
+
+async function tick(key: string): Promise<void> {
+  const entry = retryMap.get(key)
+  if (!entry) return
+  const { ctx } = entry
+  try {
+    const agent = ctx.lookupAgentFn(ctx.agentId)
+    if (!agent || !agent.tmux_pane_id) {
+      ctx.updateStatusFn?.({
+        agentId: ctx.agentId,
+        wake_status: 'failed',
+        skip_reason: 'no_pane',
+        retry_attempts: entry.attempt,
+      })
+      retryMap.delete(key)
+      return
+    }
+    if (new Date(agent.last_seen_at).getTime() > new Date(ctx.sentAt).getTime()) {
+      ctx.updateStatusFn?.({
+        agentId: ctx.agentId,
+        wake_status: 'skipped',
+        skip_reason: 'recipient_active',
+        retry_attempts: entry.attempt,
+      })
+      retryMap.delete(key)
+      return
+    }
+    const guard = await ctx.paneGuardFn(agent.tmux_pane_id)
+    if (guard === 'pass') {
+      await ctx.pokeFn({
+        team: ctx.team,
+        fromAgentId: ctx.fromAgentId,
+        targetAgentId: ctx.agentId,
+        paneId: agent.tmux_pane_id,
+        body: ctx.body
+      })
+      ctx.updateStatusFn?.({
+        agentId: ctx.agentId,
+        wake_status: 'delivered',
+        skip_reason: null,
+        retry_attempts: entry.attempt + 1,
+        delivered_at: new Date().toISOString(),
+      })
+      retryMap.delete(key)
+      return
+    }
+    entry.attempt += 1
+    if (entry.attempt >= RETRY_DELAYS_MS.length) {
+      ctx.updateStatusFn?.({
+        agentId: ctx.agentId,
+        wake_status: 'failed',
+        skip_reason: 'retry_exhausted',
+        retry_attempts: entry.attempt,
+      })
+      retryMap.delete(key)
+      return
+    }
+    ctx.updateStatusFn?.({
+      agentId: ctx.agentId,
+      wake_status: 'retrying',
+      skip_reason: 'guard_failed',
+      retry_attempts: entry.attempt,
+    })
+    enqueueNext(key)
+  } catch {
+    ctx.updateStatusFn?.({
+      agentId: ctx.agentId,
+      wake_status: 'failed',
+      skip_reason: 'retry_exhausted',
+      retry_attempts: entry.attempt,
+    })
+    retryMap.delete(key)
+  }
+}
+
+export function cancelRetry(key: string): void {
+  const entry = retryMap.get(key)
+  if (!entry) return
+  if (entry.timer) clearTimeout(entry.timer)
+  retryMap.delete(key)
+}
+
+export function clearAllRetries(): void {
+  for (const [, v] of retryMap) if (v.timer) clearTimeout(v.timer)
+  retryMap.clear()
+}
+
+export function __peekRetryMap(): Map<string, { attempt: number; ctx: RetryContext }> {
+  const view = new Map<string, { attempt: number; ctx: RetryContext }>()
+  for (const [k, v] of retryMap) view.set(k, { attempt: v.attempt, ctx: v.ctx })
+  return view
+}

package/src/mcp/poke.ts

@@ -0,0 +1,190 @@
+import type Database from 'better-sqlite3'
+import { randomBytes } from 'node:crypto'
+import { parseDeliveryRow, type DeliverySpec } from '../lib/delivery-spec.js'
+import {
+  isTmuxAvailable,
+  capturePaneTail,
+  loadBuffer,
+  pasteBuffer,
+  sendEnter
+} from '../daemon/tmux-cli.js'
+import type { ChannelWakeFanout } from '../daemon/channel-wake-fanout.js'
+import { dispatchPoke, type TmuxPokeResult } from './transport-dispatch.js'
+
+// allowCrossTeam is for internal auto-poke callers only; MCP tool entry MUST NOT pass it.
+export interface PokeDeps {
+  db: Database.Database
+  callerAgentId: string | null
+  allowCrossTeam?: boolean
+  channelWakeFanout?: ChannelWakeFanout
+}
+
+export interface PokeInput {
+  target_agent_id: string
+  prompt: string
+}
+
+export type PokeResult =
+  | {
+      ok: true
+      transport_used: 'claude-channel'
+      channel_session_id: string
+    }
+  | {
+      ok: true
+      transport_used: 'tmux-poke'
+      pane_id: string
+      pane_tail_before: string
+      pane_tail_after: string
+    }
+  | {
+      ok: true
+      transport_used: 'codex-appserver'
+      thread_id: string
+    }
+  | {
+      error: string
+      detail?: unknown
+      transport_used?: 'tmux-poke' | 'codex-appserver'
+    }
+
+interface TargetRow {
+  agent_id: string
+  client: import('../lib/client-kind.js').ClientKind | null
+  team: string
+  tmux_pane_id: string | null
+  delivery_kind: string
+  delivery_payload: string | null
+}
+
+export const PROMPT_MAX_BYTES = 8192
+export const PASTE_SETTLE_MS = 400
+export const TAIL_LINES = 8
+
+type TmuxStage = 'capture_before' | 'load_buffer' | 'paste_buffer' | 'send_keys' | 'capture_after'
+
+interface StageError {
+  stage: TmuxStage
+  cause: unknown
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function errorMessage(cause: unknown): string {
+  if (cause && typeof cause === 'object') {
+    const err = cause as { stderr?: string | Buffer; message?: string }
+    if (err.stderr) {
+      const s = typeof err.stderr === 'string' ? err.stderr : err.stderr.toString('utf8')
+      if (s.length > 0) return s
+    }
+    if (err.message) return err.message
+  }
+  return String(cause)
+}
+
+export function classifyTmuxError(err: StageError): { error: string; detail: unknown } {
+  const msg = errorMessage(err.cause)
+  const lower = msg.toLowerCase()
+  if (lower.includes("can't find pane") || lower.includes('pane not found') || lower.includes('no such pane')) {
+    return { error: 'pane_dead', detail: msg }
+  }
+  return { error: 'tmux_cmd_failed', detail: { stage: err.stage, stderr: msg } }
+}
+
+async function runStage<T>(stage: TmuxStage, fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn()
+  } catch (cause) {
+    throw { stage, cause } as StageError
+  }
+}
+
+async function tmuxPokeImpl(args: { pane_id: string; content: string }): Promise<TmuxPokeResult> {
+  if (!(await isTmuxAvailable())) {
+    return { error: 'tmux_unavailable', detail: 'tmux binary not available on PATH' }
+  }
+  const bufName = `poke-${randomBytes(3).toString('hex')}`
+  try {
+    const pane_tail_before = await runStage('capture_before', () => capturePaneTail(args.pane_id, TAIL_LINES))
+    await runStage('load_buffer', () => loadBuffer(bufName, args.content))
+    await runStage('paste_buffer', () => pasteBuffer(bufName, args.pane_id))
+    await delay(PASTE_SETTLE_MS)
+    await runStage('send_keys', () => sendEnter(args.pane_id))
+    await delay(PASTE_SETTLE_MS)
+    const pane_tail_after = await runStage('capture_after', () => capturePaneTail(args.pane_id, TAIL_LINES))
+    return { ok: true, pane_tail_before, pane_tail_after }
+  } catch (e) {
+    return classifyTmuxError(e as StageError)
+  }
+}
+
+export async function poke(deps: PokeDeps, input: PokeInput): Promise<PokeResult> {
+  if (!deps.callerAgentId) return { error: 'unknown_agent' }
+
+  const promptLen = Buffer.byteLength(input.prompt, 'utf8')
+  if (promptLen > PROMPT_MAX_BYTES) {
+    return { error: 'prompt_too_long', detail: { max: PROMPT_MAX_BYTES, got: promptLen } }
+  }
+
+  const target = deps.db
+    .prepare(
+      `SELECT
+         agent_id,
+         client,
+         team,
+         tmux_pane_id,
+         delivery_kind,
+         delivery_payload
+       FROM agents
+       WHERE agent_id = ?`
+    )
+    .get(input.target_agent_id) as TargetRow | undefined
+  if (!target) return { error: 'unknown_target' }
+
+  if (target.agent_id === deps.callerAgentId) return { error: 'self_poke_denied' }
+
+  const callerRow = deps.db
+    .prepare(`SELECT team FROM agents WHERE agent_id = ?`)
+    .get(deps.callerAgentId) as { team: string } | undefined
+  if (!callerRow) return { error: 'unknown_agent' }
+  if (callerRow.team !== target.team && !deps.allowCrossTeam) {
+    return { error: 'cross_team_denied' }
+  }
+
+  // Legacy callers may not have ChannelWakeFanout. Keep the historical tmux-only
+  // fallback for plain targets, but still allow non-tmux transports that are
+  // fully described by the target row itself.
+  const fanout = deps.channelWakeFanout
+  const delivery = parseDeliveryRow(target) as DeliverySpec
+  if (!fanout) {
+    if (delivery.kind === 'codex-appserver') {
+      return dispatchPoke(
+        { tmuxPoke: tmuxPokeImpl },
+        { client: target.client, delivery, tmux_pane_id: target.tmux_pane_id },
+        { content: input.prompt, meta: {} }
+      )
+    }
+
+    // Legacy tmux-only path preserved when no fanout supplied by caller.
+    if (!target.tmux_pane_id) return { error: 'tmux_pane_not_set' }
+    const tr = await tmuxPokeImpl({ pane_id: target.tmux_pane_id, content: input.prompt })
+    if ('ok' in tr && tr.ok) {
+      return {
+        ok: true,
+        transport_used: 'tmux-poke',
+        pane_id: target.tmux_pane_id,
+        pane_tail_before: tr.pane_tail_before,
+        pane_tail_after: tr.pane_tail_after
+      }
+    }
+    return { ...(tr as { error: string; detail?: unknown }), transport_used: 'tmux-poke' }
+  }
+
+  return dispatchPoke(
+    { channelWakeFanout: fanout, tmuxPoke: tmuxPokeImpl },
+    { client: target.client, delivery, tmux_pane_id: target.tmux_pane_id },
+    { content: input.prompt, meta: {} }
+  )
+}

package/src/mcp/pre-register-codex-pane.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+import type { CodexPanePreRegRepo } from './codex-pane-pre-register-repo.js'
+
+export const preRegisterCodexPaneInputSchema = z
+  .object({
+    pane_id: z
+      .string()
+      .min(1)
+      .refine(v => v.startsWith('%'), {
+        message: 'pane_id must be a tmux pane id starting with "%"',
+      }),
+    xats_agent_id: z.string().min(1),
+    ttl_seconds: z.number().int().positive().optional(),
+  })
+  .strict()
+
+export type PreRegisterCodexPaneInput = z.infer<typeof preRegisterCodexPaneInputSchema>
+
+export type PreRegisterCodexPaneResult =
+  | { ok: true; expires_at: string }
+  | { error: 'invalid_arguments'; detail: string }
+
+const DEFAULT_TTL_SECONDS = 120
+const MIN_TTL_SECONDS = 1
+const MAX_TTL_SECONDS = 600
+
+function clampTtl(ttl: number | undefined): number {
+  const raw = ttl ?? DEFAULT_TTL_SECONDS
+  if (raw < MIN_TTL_SECONDS) return MIN_TTL_SECONDS
+  if (raw > MAX_TTL_SECONDS) return MAX_TTL_SECONDS
+  return raw
+}
+
+export class PreRegisterCodexPaneService {
+  constructor(
+    private readonly repo: CodexPanePreRegRepo,
+    private readonly now: () => Date = () => new Date()
+  ) {}
+
+  register(args: unknown): PreRegisterCodexPaneResult {
+    const parsed = preRegisterCodexPaneInputSchema.safeParse(args)
+    if (!parsed.success) {
+      return {
+        error: 'invalid_arguments',
+        detail: parsed.error.issues
+          .map(issue => {
+            const path = issue.path.join('.')
+            return path ? `${path}: ${issue.message}` : issue.message
+          })
+          .join('; '),
+      }
+    }
+
+    const now = this.now()
+    const ttl = clampTtl(parsed.data.ttl_seconds)
+    const expires_at = new Date(now.getTime() + ttl * 1000).toISOString()
+    this.repo.deleteExpired(now.toISOString())
+    this.repo.upsert({
+      pane_id: parsed.data.pane_id,
+      xats_agent_id: parsed.data.xats_agent_id,
+      expires_at,
+    })
+    return { ok: true, expires_at }
+  }
+}

package/src/mcp/register-agent.ts

@@ -0,0 +1,84 @@
+import type Database from 'better-sqlite3'
+import {
+  validateDeliveryForWrite,
+  type DeliveryValidationReason,
+} from '../lib/delivery-spec.js'
+import type { ClientKind } from '../lib/client-kind.js'
+import { deriveDefaultTeam } from '../lib/default-team.js'
+import { AgentsRepo } from '../storage/agents-repo.js'
+
+export { deriveDefaultTeam } from '../lib/default-team.js'
+
+export interface RegisterInput {
+  connection_id: string
+  client?: ClientKind
+  client_name?: string
+  model: string
+  name: string
+  role?: string
+  team?: string
+  project_dir?: string
+  tmux_pane_id?: string
+  delivery?: unknown
+  claude_ui_pid?: number
+  runtime_ui_pid?: number
+}
+
+export type RegisterResult =
+  | { agent_id: string; team: string }
+  | { error: 'agent_id_collision' }
+  | { error: 'invalid_delivery'; reason: DeliveryValidationReason }
+  | { error: 'claude_ui_pid_requires_channel_proxy' }
+
+function identityKey(team: string, name: string): string {
+  return `${team}\u0000${name}`
+}
+
+export class RegisterAgentService {
+  private readonly repo: AgentsRepo
+  private readonly connections = new Map<string, string>()
+
+  constructor(db: Database.Database) { this.repo = new AgentsRepo(db) }
+
+  register(input: RegisterInput): RegisterResult {
+    const validated =
+      input.delivery === undefined
+        ? undefined
+        : validateDeliveryForWrite(input.delivery)
+    if (validated && 'error' in validated) return validated
+
+    const role = input.role ?? 'default'
+    if (input.claude_ui_pid !== undefined && role !== '__channel_proxy__') {
+      return { error: 'claude_ui_pid_requires_channel_proxy' }
+    }
+
+    const team = deriveDefaultTeam({
+      team: input.team,
+      project_dir: input.project_dir,
+    })
+    const key = identityKey(team, input.name)
+    const bound = this.connections.get(key)
+    if (bound && bound !== input.connection_id) return { error: 'agent_id_collision' }
+    this.connections.set(key, input.connection_id)
+    return this.repo.register({
+      client: input.client,
+      client_name: input.client_name,
+      model: input.model,
+      name: input.name,
+      role,
+      team,
+      tmux_pane_id: input.tmux_pane_id,
+      delivery: validated?.ok,
+      claude_ui_pid: input.claude_ui_pid,
+      runtime_ui_pid: input.runtime_ui_pid,
+    })
+  }
+
+  releaseConnection(agent_id: string, connection_id: string): void {
+    // Release by connection_id — scan and unbind any identity key mapped to this connection.
+    for (const [k, cid] of this.connections) {
+      if (cid === connection_id) this.connections.delete(k)
+    }
+    void agent_id
+  }
+}