cross-agent-teams-mcp 0.2.0

package/src/mcp/codex-appserver-dispatch.ts

@@ -0,0 +1,169 @@
+import type { DeliveryCodexAppserver } from '../lib/delivery-spec.js'
+import {
+  JsonRpcSocketClient,
+  defaultWebSocketFactory,
+  describeError,
+  resolveAuthToken,
+  safeClose,
+  type CodexWebSocketFactory,
+  type JsonRpcResponse,
+  type WebSocketLike,
+} from './codex-appserver-rpc.js'
+export type { WebSocketLike } from './codex-appserver-rpc.js'
+
+type Json = unknown
+
+export interface CodexAppserverDispatchDeps {
+  env?: NodeJS.ProcessEnv
+  webSocketFactory?: CodexWebSocketFactory
+}
+
+export type CodexAppserverDispatchResult =
+  | {
+      ok: true
+      transport_used: 'codex-appserver'
+      thread_id: string
+    }
+  | {
+      error:
+        | 'missing_auth_token'
+        | 'codex_connect_failed'
+        | 'codex_initialize_failed'
+        | 'codex_resume_failed'
+        | 'codex_turn_start_failed'
+      detail?: unknown
+      transport_used?: 'codex-appserver'
+    }
+
+async function requestStep(
+  client: JsonRpcSocketClient,
+  method: string,
+  params: Json
+): Promise<
+  | { ok: JsonRpcResponse }
+  | {
+      error:
+        | 'codex_initialize_failed'
+        | 'codex_resume_failed'
+        | 'codex_turn_start_failed'
+      detail: unknown
+    }
+> {
+  try {
+    const response = await client.request(method, params)
+    if (response.error) {
+      const mappedError =
+        method === 'initialize'
+          ? 'codex_initialize_failed'
+          : method === 'thread/resume'
+            ? 'codex_resume_failed'
+            : 'codex_turn_start_failed'
+      return { error: mappedError, detail: response.error }
+    }
+    return { ok: response }
+  } catch (error) {
+    const mappedError =
+      method === 'initialize'
+        ? 'codex_initialize_failed'
+        : method === 'thread/resume'
+          ? 'codex_resume_failed'
+          : 'codex_turn_start_failed'
+    return { error: mappedError, detail: describeError(error) }
+  }
+}
+
+export async function dispatchCodexAppserverPoke(
+  input: {
+    delivery: DeliveryCodexAppserver
+    content: string
+  },
+  deps: CodexAppserverDispatchDeps = {}
+): Promise<CodexAppserverDispatchResult> {
+  const authToken = resolveAuthToken(
+    input.delivery.auth_token_ref,
+    deps.env ?? process.env
+  )
+  if ('error' in authToken) return authToken
+
+  const headers = authToken.ok === undefined
+    ? undefined
+    : { Authorization: `Bearer ${authToken.ok}` }
+
+  let ws: WebSocketLike
+  try {
+    ws = (deps.webSocketFactory ?? defaultWebSocketFactory)({
+      url: input.delivery.ws_url,
+      headers,
+    })
+  } catch (error) {
+    return {
+      error: 'codex_connect_failed',
+      detail: describeError(error),
+      transport_used: 'codex-appserver',
+    }
+  }
+
+  const client = new JsonRpcSocketClient(ws)
+  try {
+    await client.waitForOpen()
+
+    const init = await requestStep(client, 'initialize', {
+      clientInfo: {
+        name: 'cross-agent-teams-mcp',
+        title: null,
+        version: '0.1.0',
+      },
+      capabilities: {
+        experimentalApi: true,
+        optOutNotificationMethods: null,
+      },
+    })
+    if ('error' in init) {
+      return {
+        error: init.error,
+        detail: init.detail,
+        transport_used: 'codex-appserver',
+      }
+    }
+
+    client.notify('initialized')
+
+    const resume = await requestStep(client, 'thread/resume', {
+      threadId: input.delivery.thread_id,
+      persistExtendedHistory: false,
+    })
+    if ('error' in resume) {
+      return {
+        error: resume.error,
+        detail: resume.detail,
+        transport_used: 'codex-appserver',
+      }
+    }
+
+    const turnStart = await requestStep(client, 'turn/start', {
+      threadId: input.delivery.thread_id,
+      input: [{ type: 'text', text: input.content, text_elements: [] }],
+    })
+    if ('error' in turnStart) {
+      return {
+        error: turnStart.error,
+        detail: turnStart.detail,
+        transport_used: 'codex-appserver',
+      }
+    }
+
+    return {
+      ok: true,
+      transport_used: 'codex-appserver',
+      thread_id: input.delivery.thread_id,
+    }
+  } catch (error) {
+    return {
+      error: 'codex_connect_failed',
+      detail: describeError(error),
+      transport_used: 'codex-appserver',
+    }
+  } finally {
+    safeClose(ws)
+  }
+}

package/src/mcp/codex-appserver-rpc.ts

@@ -0,0 +1,227 @@
+type Json = unknown
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: number
+  method: string
+  params: Json
+}
+
+interface JsonRpcNotification {
+  jsonrpc: '2.0'
+  method: string
+  params?: Json
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: number
+  result?: Json
+  error?: { code: number; message: string; data?: Json }
+}
+
+type MessageEventLike = { data: unknown }
+type ErrorEventLike = { error?: unknown; message?: string }
+type CloseEventLike = { code?: number; reason?: string }
+
+export interface WebSocketLike {
+  addEventListener(
+    type: 'open' | 'message' | 'error' | 'close',
+    listener: (event: unknown) => void
+  ): void
+  removeEventListener?(
+    type: 'open' | 'message' | 'error' | 'close',
+    listener: (event: unknown) => void
+  ): void
+  send(data: string): void
+  close(): void
+}
+
+export interface CodexWebSocketFactoryArgs {
+  url: string
+  headers?: Record<string, string>
+}
+
+export type CodexWebSocketFactory = (
+  args: CodexWebSocketFactoryArgs
+) => WebSocketLike
+
+type PendingResolver = {
+  resolve: (value: JsonRpcResponse) => void
+  reject: (reason?: unknown) => void
+}
+
+export function defaultWebSocketFactory(
+  args: CodexWebSocketFactoryArgs
+): WebSocketLike {
+  const ctor = globalThis.WebSocket as unknown as new (
+    url: string,
+    options?: { headers?: Record<string, string> }
+  ) => WebSocketLike
+  return new ctor(
+    args.url,
+    args.headers === undefined ? undefined : { headers: args.headers }
+  )
+}
+
+export function describeError(error: unknown): string {
+  if (error instanceof Error && error.message.length > 0) return error.message
+  if (typeof error === 'string' && error.length > 0) return error
+  if (error && typeof error === 'object') {
+    const record = error as Record<string, unknown>
+    const message = record.message
+    if (typeof message === 'string' && message.length > 0) return message
+    const reason = record.reason
+    if (typeof reason === 'string' && reason.length > 0) return reason
+  }
+  return String(error)
+}
+
+function closeDetail(event: CloseEventLike): string {
+  const code = typeof event.code === 'number' ? event.code : 'unknown'
+  const reason = typeof event.reason === 'string' && event.reason.length > 0
+    ? event.reason
+    : 'socket_closed'
+  return `close ${code}: ${reason}`
+}
+
+function decodeMessageData(data: unknown): string {
+  if (typeof data === 'string') return data
+  if (data instanceof ArrayBuffer) {
+    return new TextDecoder().decode(new Uint8Array(data))
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new TextDecoder().decode(data)
+  }
+  return String(data)
+}
+
+export function safeClose(ws: WebSocketLike): void {
+  try {
+    ws.close()
+  } catch {
+    return
+  }
+}
+
+export function resolveAuthToken(
+  authTokenRef: string | undefined,
+  env: NodeJS.ProcessEnv
+): { ok: string | undefined } | { error: 'missing_auth_token'; detail: { ref: string } } {
+  if (authTokenRef === undefined) return { ok: undefined }
+  const token = env[authTokenRef]?.trim()
+  if (!token) {
+    return {
+      error: 'missing_auth_token',
+      detail: { ref: authTokenRef },
+    }
+  }
+  return { ok: token }
+}
+
+export class JsonRpcSocketClient {
+  private nextId = 1
+  private readonly pending = new Map<number, PendingResolver>()
+  private openState:
+    | { kind: 'pending'; promise: Promise<void> }
+    | { kind: 'open' }
+    | { kind: 'failed'; error: unknown }
+
+  constructor(private readonly ws: WebSocketLike) {
+    this.openState = {
+      kind: 'pending',
+      promise: new Promise<void>((resolve, reject) => {
+        const onOpen = () => {
+          cleanup()
+          this.openState = { kind: 'open' }
+          resolve()
+        }
+        const onError = (event: unknown) => {
+          cleanup()
+          const detail = event as ErrorEventLike
+          const error = detail.error ?? detail.message ?? 'websocket_error'
+          this.openState = { kind: 'failed', error }
+          reject(error)
+        }
+        const onClose = (event: unknown) => {
+          cleanup()
+          const closeEvent = event as CloseEventLike
+          const error = closeDetail(closeEvent)
+          this.openState = { kind: 'failed', error }
+          reject(error)
+        }
+        const cleanup = () => {
+          this.ws.removeEventListener?.('open', onOpen)
+          this.ws.removeEventListener?.('error', onError)
+          this.ws.removeEventListener?.('close', onClose)
+        }
+        this.ws.addEventListener('open', onOpen)
+        this.ws.addEventListener('error', onError)
+        this.ws.addEventListener('close', onClose)
+      }),
+    }
+
+    this.ws.addEventListener('message', (event) => {
+      let message: JsonRpcResponse
+      try {
+        message = JSON.parse(decodeMessageData((event as MessageEventLike).data))
+      } catch {
+        return
+      }
+      if (typeof message.id !== 'number') return
+      const pending = this.pending.get(message.id)
+      if (!pending) return
+      this.pending.delete(message.id)
+      pending.resolve(message)
+    })
+
+    this.ws.addEventListener('error', (event) => {
+      if (this.openState.kind !== 'open') return
+      const detail = event as ErrorEventLike
+      const error = detail.error ?? detail.message ?? 'websocket_error'
+      this.rejectAll(error)
+    })
+
+    this.ws.addEventListener('close', (event) => {
+      if (this.openState.kind !== 'open') return
+      this.rejectAll(closeDetail(event as CloseEventLike))
+    })
+  }
+
+  async waitForOpen(): Promise<void> {
+    if (this.openState.kind === 'open') return
+    if (this.openState.kind === 'failed') throw this.openState.error
+    await this.openState.promise
+  }
+
+  request(method: string, params: Json): Promise<JsonRpcResponse> {
+    const id = this.nextId++
+    const request: JsonRpcRequest = { jsonrpc: '2.0', id, method, params }
+    return new Promise<JsonRpcResponse>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      try {
+        this.ws.send(JSON.stringify(request))
+      } catch (error) {
+        this.pending.delete(id)
+        reject(error)
+      }
+    })
+  }
+
+  notify(method: string, params?: Json): void {
+    const notification: JsonRpcNotification = {
+      jsonrpc: '2.0',
+      method,
+      ...(params === undefined ? {} : { params }),
+    }
+    this.ws.send(JSON.stringify(notification))
+  }
+
+  private rejectAll(error: unknown): void {
+    const pending = [...this.pending.values()]
+    this.pending.clear()
+    for (const entry of pending) {
+      entry.reject(error)
+    }
+  }
+}

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

@@ -0,0 +1,57 @@
+import type Database from 'better-sqlite3'
+
+export interface CodexPanePreRegRow {
+  pane_id: string
+  xats_agent_id: string
+  expires_at: string
+}
+
+export interface UpsertInput {
+  pane_id: string
+  xats_agent_id: string
+  expires_at: string
+}
+
+export class CodexPanePreRegRepo {
+  constructor(private readonly db: Database.Database) {}
+
+  upsert(input: UpsertInput): void {
+    this.db
+      .prepare(
+        `INSERT INTO codex_pane_pre_registrations (pane_id, xats_agent_id, expires_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(pane_id) DO UPDATE SET
+           xats_agent_id = excluded.xats_agent_id,
+           expires_at = excluded.expires_at`
+      )
+      .run(input.pane_id, input.xats_agent_id, input.expires_at)
+  }
+
+  listUnexpired(now: string): CodexPanePreRegRow[] {
+    return this.db
+      .prepare(
+        `SELECT pane_id, xats_agent_id, expires_at
+         FROM codex_pane_pre_registrations
+         WHERE expires_at > ?`
+      )
+      .all(now) as CodexPanePreRegRow[]
+  }
+
+  takeByPaneId(pane_id: string): CodexPanePreRegRow | undefined {
+    const row = this.db
+      .prepare(
+        `DELETE FROM codex_pane_pre_registrations
+         WHERE pane_id = ?
+         RETURNING pane_id, xats_agent_id, expires_at`
+      )
+      .get(pane_id) as CodexPanePreRegRow | undefined
+    return row
+  }
+
+  deleteExpired(now: string): number {
+    const res = this.db
+      .prepare(`DELETE FROM codex_pane_pre_registrations WHERE expires_at <= ?`)
+      .run(now)
+    return res.changes
+  }
+}

package/src/mcp/delivery-status.ts

@@ -0,0 +1,114 @@
+import type Database from 'better-sqlite3'
+import type { AutoPokeSkipReason } from './auto-poke-fanout.js'
+
+export type WakeStatus = 'delivered' | 'retrying' | 'skipped' | 'failed'
+export type DeliverySkipReason =
+  | AutoPokeSkipReason
+  | 'auto_poke_disabled'
+  | 'recipient_active'
+  | 'retry_exhausted'
+
+export interface DeliveryStatusRow {
+  agent_id: string
+  wake_status: WakeStatus
+  skip_reason: DeliverySkipReason | null
+  retry_attempts: number
+  updated_at: string
+  delivered_at: string | null
+}
+
+export function recordInitialDeliveryStatuses(
+  db: Database.Database,
+  args: {
+    messageId: string
+    recipients: string[]
+    delivered: Set<string>
+    skipped: Array<{ agent_id: string; reason: AutoPokeSkipReason }>
+    autoPokeDisabled?: boolean
+  }
+): void {
+  const now = new Date().toISOString()
+  const skipped = new Map(args.skipped.map(x => [x.agent_id, x.reason]))
+  const stmt = db.prepare(
+    `INSERT INTO message_delivery_status
+       (message_id, agent_id, wake_status, skip_reason, retry_attempts, updated_at, delivered_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(message_id, agent_id) DO UPDATE SET
+       wake_status=excluded.wake_status,
+       skip_reason=excluded.skip_reason,
+       retry_attempts=excluded.retry_attempts,
+       updated_at=excluded.updated_at,
+       delivered_at=excluded.delivered_at`
+  )
+  const tx = db.transaction(() => {
+    for (const agentId of args.recipients) {
+      const reason = args.autoPokeDisabled ? 'auto_poke_disabled' : skipped.get(agentId)
+      const delivered = args.delivered.has(agentId)
+      const status: WakeStatus = delivered
+        ? 'delivered'
+        : reason === 'guard_failed' ? 'retrying' : 'skipped'
+      stmt.run(
+        args.messageId,
+        agentId,
+        status,
+        delivered ? null : reason,
+        0,
+        now,
+        delivered ? now : null
+      )
+    }
+  })
+  tx()
+}
+
+export function updateDeliveryStatus(
+  db: Database.Database,
+  messageId: string,
+  agentId: string,
+  args: {
+    wake_status: WakeStatus
+    skip_reason?: DeliverySkipReason | null
+    retry_attempts?: number
+    delivered_at?: string | null
+  }
+): void {
+  const now = new Date().toISOString()
+  db.prepare(
+    `UPDATE message_delivery_status
+     SET wake_status=?,
+         skip_reason=?,
+         retry_attempts=COALESCE(?, retry_attempts),
+         updated_at=?,
+         delivered_at=?
+     WHERE message_id=? AND agent_id=?`
+  ).run(
+    args.wake_status,
+    args.skip_reason ?? null,
+    args.retry_attempts ?? null,
+    now,
+    args.delivered_at === undefined ? null : args.delivered_at,
+    messageId,
+    agentId
+  )
+}
+
+export class GetDeliveryStatusService {
+  constructor(private db: Database.Database) {}
+
+  get(args: { caller: string; message_id: string }):
+    | { message_id: string; statuses: DeliveryStatusRow[] }
+    | { error: 'unknown_message' } {
+    const owned = this.db.prepare(
+      `SELECT 1 AS ok FROM messages WHERE id=? AND from_agent_id=? LIMIT 1`
+    ).get(args.message_id, args.caller) as { ok: number } | undefined
+    if (!owned) return { error: 'unknown_message' }
+
+    const rows = this.db.prepare(
+      `SELECT agent_id, wake_status, skip_reason, retry_attempts, updated_at, delivered_at
+       FROM message_delivery_status
+       WHERE message_id=?
+       ORDER BY agent_id ASC`
+    ).all(args.message_id) as DeliveryStatusRow[]
+    return { message_id: args.message_id, statuses: rows }
+  }
+}

package/src/mcp/diff-contracts.ts

@@ -0,0 +1,25 @@
+import type Database from 'better-sqlite3'
+import type { AgentsRepo } from '../storage/agents-repo.js'
+import { diffSchema, type ContractDiff } from '../lib/schema-diff.js'
+
+export type DiffContractsResult =
+  | ContractDiff
+  | { error: 'unknown_contract' | 'unknown_version' | 'unknown_agent' }
+
+export class DiffContractsService {
+  constructor(private db: Database.Database, private agents: AgentsRepo) {}
+
+  diff(args: { caller: string; name: string; from_version: number; to_version: number }): DiffContractsResult {
+    const caller = this.agents.findById(args.caller)
+    if (!caller) return { error: 'unknown_agent' }
+    const from = this.db.prepare('SELECT schema FROM contracts WHERE team=? AND name=? AND version=?')
+      .get(caller.team, args.name, args.from_version) as { schema: string } | undefined
+    const to = this.db.prepare('SELECT schema FROM contracts WHERE team=? AND name=? AND version=?')
+      .get(caller.team, args.name, args.to_version) as { schema: string } | undefined
+    if (!from || !to) {
+      const exists = this.db.prepare('SELECT 1 FROM contracts WHERE team=? AND name=? LIMIT 1').get(caller.team, args.name)
+      return exists ? { error: 'unknown_version' } : { error: 'unknown_contract' }
+    }
+    return diffSchema(JSON.parse(from.schema), JSON.parse(to.schema))
+  }
+}

package/src/mcp/echo.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const echoSchema = { msg: z.string() }
+
+export async function echoHandler(args: { msg: string }): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const out = { msg: args.msg, echoed_at: new Date().toISOString() }
+  return { content: [{ type: 'text', text: JSON.stringify(out) }] }
+}

package/src/mcp/fanout-with-retry.ts

@@ -0,0 +1,56 @@
+import type Database from 'better-sqlite3'
+import { fanoutAutoPoke, type AutoPokeRecipient, type AutoPokeSkipReason, type FanoutDeps } from './auto-poke-fanout.js'
+import { RETRY_DELAYS_S } from './poke-retry.js'
+import { recordInitialDeliveryStatuses, updateDeliveryStatus } from './delivery-status.js'
+
+export interface FanoutResultEnvelope {
+  poked: boolean
+  poke_skip_reasons?: Array<{ agent_id: string; reason: AutoPokeSkipReason }>
+  retry_scheduled: boolean
+  retry_delays_s?: number[]
+}
+
+// Shared fan-out + retry wiring used by both BroadcastService (all-team) and BroadcastToRoleService (same-team role-scoped).
+// Same recipient-lookup SQL (agent_id-only, team-agnostic) keeps cross-team retry behaviour consistent.
+export async function runFanoutWithRetry(args: {
+  db: Database.Database
+  team: string
+  fromAgentId: string
+  recipients: AutoPokeRecipient[]
+  body: string
+  deps: FanoutDeps
+  messageId: string
+  sentAt: string
+}): Promise<FanoutResultEnvelope> {
+  const { db } = args
+  const fanout = await fanoutAutoPoke({
+    team: args.team,
+    fromAgentId: args.fromAgentId,
+    recipients: args.recipients,
+    body: args.body,
+    deps: args.deps,
+    retry: {
+      messageId: args.messageId,
+      sentAt: args.sentAt,
+      lookupAgentFn: (agentId: string) => db.prepare(
+        'SELECT agent_id, tmux_pane_id, last_seen_at FROM agents WHERE agent_id=?'
+      ).get(agentId) as { agent_id: string; tmux_pane_id: string | null; last_seen_at: string } | undefined,
+      updateStatusFn: (status) => {
+        updateDeliveryStatus(db, args.messageId, status.agentId, status)
+      }
+    }
+  })
+  recordInitialDeliveryStatuses(db, {
+    messageId: args.messageId,
+    recipients: args.recipients.map(r => r.agent_id),
+    delivered: new Set(fanout.deliveredAgentIds),
+    skipped: fanout.skipReasons
+  })
+  const retry_scheduled = fanout.retryScheduledCount > 0
+  return {
+    poked: fanout.poked,
+    poke_skip_reasons: fanout.skipReasons,
+    retry_scheduled,
+    ...(retry_scheduled ? { retry_delays_s: [...RETRY_DELAYS_S] } : {})
+  }
+}

package/src/mcp/get-contract.ts

@@ -0,0 +1,24 @@
+import type Database from 'better-sqlite3'
+import type { AgentsRepo } from '../storage/agents-repo.js'
+
+export type GetContractResult =
+  | { name: string; version: number; schema: Record<string, unknown>; format: string; note: string | null; registered_at: string }
+  | { error: 'unknown_contract' | 'unknown_version' | 'unknown_agent' }
+
+export class GetContractService {
+  constructor(private db: Database.Database, private agents: AgentsRepo) {}
+
+  get(args: { caller: string; name: string; version?: number }): GetContractResult {
+    const caller = this.agents.findById(args.caller)
+    if (!caller) return { error: 'unknown_agent' }
+    const row = args.version
+      ? this.db.prepare('SELECT * FROM contracts WHERE team=? AND name=? AND version=?').get(caller.team, args.name, args.version)
+      : this.db.prepare('SELECT * FROM contracts WHERE team=? AND name=? ORDER BY version DESC LIMIT 1').get(caller.team, args.name)
+    if (!row) {
+      const exists = this.db.prepare('SELECT 1 FROM contracts WHERE team=? AND name=? LIMIT 1').get(caller.team, args.name)
+      return exists ? { error: 'unknown_version' } : { error: 'unknown_contract' }
+    }
+    const r = row as { name: string; version: number; schema: string; format: string; note: string | null; registered_at: string }
+    return { name: r.name, version: r.version, schema: JSON.parse(r.schema), format: r.format, note: r.note, registered_at: r.registered_at }
+  }
+}