cross-agent-teams-mcp 0.2.0

package/src/daemon/tmux-pane-detect.ts

@@ -0,0 +1,276 @@
+import { execFile } from 'node:child_process'
+import { normalize, sep } from 'node:path'
+import { promisify } from 'node:util'
+
+const pExecFile = promisify(execFile)
+
+export type DetectAgentKind = 'codex' | 'claude-code' | 'opencode' | 'custom'
+
+export interface DetectTmuxPaneInput {
+  agent: DetectAgentKind
+  cwd?: string
+  tty?: string
+  title_contains?: string
+  process_pattern?: string
+}
+
+export interface DetectTmuxPaneCandidate {
+  pane_id: string
+  session_name: string
+  window_index: number
+  pane_index: number
+  active: boolean
+  tty: string
+  current_path: string
+  current_command: string
+  title: string
+  matched_processes: string[]
+  score: number
+}
+
+export type DetectTmuxPaneResult =
+  | { ok: true; pane: DetectTmuxPaneCandidate; candidates: DetectTmuxPaneCandidate[] }
+  | { error: 'not_found'; candidates: [] }
+  | { error: 'ambiguous_match'; candidates: DetectTmuxPaneCandidate[] }
+  | { error: 'tmux_unavailable'; detail: string }
+
+export interface DetectTmuxPaneDeps {
+  execFile?: typeof execFile
+}
+
+interface PaneRow {
+  pane_id: string
+  session_name: string
+  window_index: number
+  pane_index: number
+  active: boolean
+  tty: string
+  current_path: string
+  current_command: string
+  title: string
+}
+
+const TMUX_LIST_TIMEOUT_MS = 3_000
+const PS_LIST_TIMEOUT_MS = 3_000
+
+function normalizeTty(raw: string | undefined): string | undefined {
+  const value = raw?.trim()
+  if (!value) return undefined
+  return value.replace(/^\/dev\//, '')
+}
+
+function normalizePath(raw: string | undefined): string | undefined {
+  const value = raw?.trim()
+  if (!value) return undefined
+  return normalize(value)
+}
+
+function pathRelated(candidatePath: string, inputPath: string): 'exact' | 'ancestor' | 'descendant' | 'none' {
+  const candidate = normalize(candidatePath)
+  const input = normalize(inputPath)
+  if (candidate === input) return 'exact'
+  if (candidate.startsWith(`${input}${sep}`)) return 'descendant'
+  if (input.startsWith(`${candidate}${sep}`)) return 'ancestor'
+  return 'none'
+}
+
+function commandPattern(args: DetectTmuxPaneInput): RegExp {
+  if (args.agent === 'custom') {
+    const raw = args.process_pattern?.trim()
+    if (!raw) throw new Error('process_pattern is required when agent=custom')
+    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
+}
+
+function commandHintScore(agent: DetectAgentKind, command: string): number {
+  if (agent === 'codex' && /codex/i.test(command)) return 6
+  if (agent === 'opencode' && /opencode/i.test(command)) return 6
+  if (agent === 'claude-code' && /^(\d+\.)+\d+$/.test(command)) return 4
+  return 0
+}
+
+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)
+}
+
+function parsePaneRows(stdout: string): PaneRow[] {
+  return stdout
+    .split('\n')
+    .map(line => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const [
+        pane_id,
+        session_name,
+        window_index,
+        pane_index,
+        pane_active,
+        pane_tty,
+        pane_current_path,
+        pane_current_command,
+        pane_title,
+      ] = line.split('\t')
+      return {
+        pane_id,
+        session_name,
+        window_index: Number(window_index),
+        pane_index: Number(pane_index),
+        active: pane_active === '1',
+        tty: normalizeTty(pane_tty) ?? '',
+        current_path: pane_current_path ?? '',
+        current_command: pane_current_command ?? '',
+        title: pane_title ?? '',
+      }
+    })
+  }
+
+async function listPanes(execLike: typeof execFile): Promise<PaneRow[]> {
+  const exec = promisify(execLike)
+  const { stdout } = await exec(
+    'tmux',
+    [
+      'list-panes',
+      '-a',
+      '-F',
+      '#{pane_id}\t#{session_name}\t#{window_index}\t#{pane_index}\t#{pane_active}\t#{pane_tty}\t#{pane_current_path}\t#{pane_current_command}\t#{pane_title}',
+    ],
+    { timeout: TMUX_LIST_TIMEOUT_MS }
+  )
+  return parsePaneRows(stdout)
+}
+
+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 collectCandidates(
+  panes: PaneRow[],
+  ttyMap: Map<string, string[]>,
+  input: DetectTmuxPaneInput
+): DetectTmuxPaneCandidate[] {
+  const ttyFilter = normalizeTty(input.tty)
+  const cwdFilter = normalizePath(input.cwd)
+  const titleFilter = input.title_contains?.trim().toLowerCase()
+  const pattern = commandPattern(input)
+  const candidates: DetectTmuxPaneCandidate[] = []
+
+  for (const pane of panes) {
+    if (ttyFilter && pane.tty !== ttyFilter) continue
+    if (cwdFilter) {
+      const relation = pathRelated(pane.current_path, cwdFilter)
+      if (relation === 'none') continue
+    }
+    if (titleFilter && !pane.title.toLowerCase().includes(titleFilter)) continue
+
+    const matched_processes = (ttyMap.get(pane.tty) ?? []).filter((line) => {
+      if (isHelperProcess(input.agent, line)) return false
+      return pattern.test(line)
+    })
+    if (matched_processes.length === 0) continue
+
+    let score = matched_processes.length * 10
+    if (pane.active) score += 3
+    score += commandHintScore(input.agent, pane.current_command)
+    if (ttyFilter) score += 100
+    if (cwdFilter) {
+      const relation = pathRelated(pane.current_path, cwdFilter)
+      if (relation === 'exact') score += 60
+      else if (relation === 'descendant') score += 45
+      else if (relation === 'ancestor') score += 30
+    }
+    if (titleFilter) score += 15
+
+    candidates.push({
+      pane_id: pane.pane_id,
+      session_name: pane.session_name,
+      window_index: pane.window_index,
+      pane_index: pane.pane_index,
+      active: pane.active,
+      tty: pane.tty,
+      current_path: pane.current_path,
+      current_command: pane.current_command,
+      title: pane.title,
+      matched_processes,
+      score,
+    })
+  }
+
+  return candidates.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score
+    if (a.pane_id < b.pane_id) return -1
+    if (a.pane_id > b.pane_id) return 1
+    return 0
+  })
+}
+
+export async function detectTmuxPane(
+  input: DetectTmuxPaneInput,
+  deps: DetectTmuxPaneDeps = {}
+): Promise<DetectTmuxPaneResult> {
+  const execLike = deps.execFile ?? execFile
+  let panes: PaneRow[]
+  try {
+    panes = await listPanes(execLike)
+  } catch (error) {
+    return {
+      error: 'tmux_unavailable',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  const ttyMap = new Map<string, string[]>()
+  for (const pane of panes) {
+    if (!pane.tty || ttyMap.has(pane.tty)) continue
+    try {
+      ttyMap.set(pane.tty, await ttyProcesses(execLike, pane.tty))
+    } catch {
+      ttyMap.set(pane.tty, [])
+    }
+  }
+
+  let candidates: DetectTmuxPaneCandidate[]
+  try {
+    candidates = collectCandidates(panes, ttyMap, input)
+  } catch (error) {
+    return {
+      error: 'not_found',
+      candidates: [],
+    }
+  }
+
+  if (candidates.length === 0) return { error: 'not_found', candidates: [] }
+
+  const topScore = candidates[0].score
+  const top = candidates.filter(candidate => candidate.score === topScore)
+  if (top.length > 1) {
+    return {
+      error: 'ambiguous_match',
+      candidates,
+    }
+  }
+
+  return {
+    ok: true,
+    pane: candidates[0],
+    candidates,
+  }
+}

package/src/lib/client-kind.ts

@@ -0,0 +1 @@
+export type ClientKind = 'codex' | 'claude-code' | 'opencode' | 'custom'

package/src/lib/default-team.ts

@@ -0,0 +1,18 @@
+import { basename } from 'node:path'
+
+export interface DeriveDefaultTeamInput {
+  team?: string
+  project_dir?: string
+}
+
+export function deriveDefaultTeam(input: DeriveDefaultTeamInput): string {
+  const explicitTeam = input.team?.trim()
+  if (explicitTeam) return explicitTeam
+
+  if (input.project_dir !== undefined) {
+    const projectTeam = basename(input.project_dir).trim().toLowerCase()
+    if (projectTeam) return projectTeam
+  }
+
+  return 'default'
+}

package/src/lib/delivery-spec.ts

@@ -0,0 +1,172 @@
+export type DeliveryNone = {
+  kind: 'none';
+};
+
+export type DeliveryClaudeChannel = {
+  kind: 'claude-channel';
+  channel_session_id: string;
+};
+
+export type DeliveryCodexAppserver = {
+  kind: 'codex-appserver';
+  thread_id: string;
+  ws_url: string;
+  auth_token_ref?: string;
+};
+
+export type DeliverySpec =
+  | DeliveryNone
+  | DeliveryClaudeChannel
+  | DeliveryCodexAppserver;
+
+export type DeliveryKind = DeliverySpec['kind'];
+
+export const DELIVERY_KINDS: readonly DeliveryKind[] = [
+  'none',
+  'claude-channel',
+  'codex-appserver',
+] as const;
+
+export type DeliveryRow = {
+  delivery_kind: string;
+  delivery_payload: string | null;
+};
+
+export function parseDeliveryRow(row: DeliveryRow): DeliverySpec {
+  const kind = row.delivery_kind;
+  if (kind === 'none') {
+    return { kind: 'none' };
+  }
+  if (!(DELIVERY_KINDS as readonly string[]).includes(kind)) {
+    throw new Error('corrupt_delivery_payload');
+  }
+  let payload: unknown;
+  try {
+    payload = row.delivery_payload == null ? {} : JSON.parse(row.delivery_payload);
+  } catch {
+    throw new Error('corrupt_delivery_payload');
+  }
+  if (typeof payload !== 'object' || payload === null) {
+    throw new Error('corrupt_delivery_payload');
+  }
+  const record = payload as Record<string, unknown>;
+  if (kind === 'claude-channel') {
+    const csid = record.channel_session_id;
+    if (typeof csid !== 'string' || csid.length === 0) {
+      throw new Error('corrupt_delivery_payload');
+    }
+    return { kind: 'claude-channel', channel_session_id: csid };
+  }
+  if (kind === 'codex-appserver') {
+    const threadId = record.thread_id;
+    if (typeof threadId !== 'string' || threadId.length === 0) {
+      throw new Error('corrupt_delivery_payload');
+    }
+    const wsUrl = record.ws_url;
+    if (typeof wsUrl !== 'string' || wsUrl.length === 0) {
+      throw new Error('corrupt_delivery_payload');
+    }
+    const hasAuthTokenRef = Object.prototype.hasOwnProperty.call(record, 'auth_token_ref');
+    if (hasAuthTokenRef) {
+      const authTokenRef = record.auth_token_ref;
+      if (typeof authTokenRef !== 'string' || authTokenRef.length === 0) {
+        throw new Error('corrupt_delivery_payload');
+      }
+      return {
+        kind: 'codex-appserver',
+        thread_id: threadId,
+        ws_url: wsUrl,
+        auth_token_ref: authTokenRef,
+      };
+    }
+    return { kind: 'codex-appserver', thread_id: threadId, ws_url: wsUrl };
+  }
+  throw new Error('corrupt_delivery_payload');
+}
+
+export function serializeDelivery(spec: DeliverySpec): DeliveryRow {
+  if (spec.kind === 'none') {
+    return { delivery_kind: 'none', delivery_payload: null };
+  }
+  const { kind, ...rest } = spec;
+  return {
+    delivery_kind: kind,
+    delivery_payload: JSON.stringify(rest),
+  };
+}
+
+export type DeliveryValidationReason =
+  | 'unknown_kind'
+  | 'missing_channel_session_id'
+  | 'invalid_thread_id'
+  | 'invalid_ws_url'
+  | 'invalid_auth_token_ref';
+
+export type ValidateDeliveryResult =
+  | { ok: DeliverySpec }
+  | { error: 'invalid_delivery'; reason: DeliveryValidationReason };
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function readTrimmedString(
+  input: Record<string, unknown>,
+  key: string
+): string | undefined {
+  const value = input[key];
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : '';
+}
+
+export function validateDeliveryForWrite(input: unknown): ValidateDeliveryResult {
+  if (typeof input !== 'object' || input === null) {
+    return { error: 'invalid_delivery', reason: 'unknown_kind' };
+  }
+  const record = input as Record<string, unknown>;
+  const kind = record.kind;
+  if (kind === 'none') {
+    return { ok: { kind: 'none' } };
+  }
+  if (kind === 'claude-channel') {
+    const csid = readTrimmedString(record, 'channel_session_id');
+    if (csid === undefined || csid.length === 0) {
+      return { error: 'invalid_delivery', reason: 'missing_channel_session_id' };
+    }
+    return { ok: { kind: 'claude-channel', channel_session_id: csid } };
+  }
+  if (kind === 'codex-appserver') {
+    const threadId = readTrimmedString(record, 'thread_id');
+    if (threadId === undefined || threadId.length === 0 || !UUID_RE.test(threadId)) {
+      return { error: 'invalid_delivery', reason: 'invalid_thread_id' };
+    }
+
+    const wsUrl = readTrimmedString(record, 'ws_url');
+    if (wsUrl === undefined || wsUrl.length === 0) {
+      return { error: 'invalid_delivery', reason: 'invalid_ws_url' };
+    }
+    try {
+      const parsed = new URL(wsUrl);
+      if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+        return { error: 'invalid_delivery', reason: 'invalid_ws_url' };
+      }
+    } catch {
+      return { error: 'invalid_delivery', reason: 'invalid_ws_url' };
+    }
+
+    const authTokenRef = readTrimmedString(record, 'auth_token_ref');
+    if (authTokenRef === '') {
+      return { error: 'invalid_delivery', reason: 'invalid_auth_token_ref' };
+    }
+
+    return {
+      ok: {
+        kind: 'codex-appserver',
+        thread_id: threadId,
+        ws_url: wsUrl,
+        ...(authTokenRef === undefined ? {} : { auth_token_ref: authTokenRef }),
+      },
+    };
+  }
+  return { error: 'invalid_delivery', reason: 'unknown_kind' };
+}

package/src/lib/schema-diff.ts

@@ -0,0 +1,79 @@
+export interface ContractDiff {
+  added_fields: Array<{ path: string; type_summary: string }>
+  removed_fields: Array<{ path: string; type_summary: string }>
+  changed_fields: Array<{
+    path: string
+    from: { type?: string; required?: boolean; enum?: unknown[]; raw: unknown }
+    to:   { type?: string; required?: boolean; enum?: unknown[]; raw: unknown }
+  }>
+  breaking: boolean
+}
+
+type Schema = Record<string, unknown> & {
+  type?: string
+  properties?: Record<string, Schema>
+  required?: string[]
+  enum?: unknown[]
+}
+
+function typeSummary(s: Schema | undefined): string {
+  if (!s) return 'unknown'
+  if (typeof s.type === 'string') return s.type
+  return 'unknown'
+}
+
+function isRequired(parent: Schema, key: string): boolean {
+  return Array.isArray(parent.required) && parent.required.includes(key)
+}
+
+function walk(
+  fromParent: Schema, toParent: Schema, basePath: string,
+  added: ContractDiff['added_fields'], removed: ContractDiff['removed_fields'], changed: ContractDiff['changed_fields']
+): void {
+  const fp = fromParent.properties ?? {}
+  const tp = toParent.properties ?? {}
+  const keys = new Set<string>([...Object.keys(fp), ...Object.keys(tp)])
+  for (const key of keys) {
+    const path = `${basePath}/properties/${key}`
+    const fromChild = fp[key]
+    const toChild = tp[key]
+    if (fromChild && !toChild) {
+      removed.push({ path, type_summary: typeSummary(fromChild) })
+      continue
+    }
+    if (!fromChild && toChild) {
+      added.push({ path, type_summary: typeSummary(toChild) })
+      continue
+    }
+    if (fromChild && toChild) {
+      const fromType = typeof fromChild.type === 'string' ? fromChild.type : undefined
+      const toType = typeof toChild.type === 'string' ? toChild.type : undefined
+      const fromReq = isRequired(fromParent, key)
+      const toReq = isRequired(toParent, key)
+      const typeDiff = fromType !== toType
+      const reqDiff = fromReq !== toReq
+      if (typeDiff || reqDiff) {
+        changed.push({
+          path,
+          from: { type: fromType, required: fromReq, enum: fromChild.enum, raw: fromChild },
+          to:   { type: toType,   required: toReq,   enum: toChild.enum,   raw: toChild }
+        })
+      }
+      if (toChild.type === 'object' || fromChild.type === 'object') {
+        walk(fromChild, toChild, path, added, removed, changed)
+      }
+    }
+  }
+}
+
+export function diffSchema(from: Schema, to: Schema): ContractDiff {
+  const added: ContractDiff['added_fields'] = []
+  const removed: ContractDiff['removed_fields'] = []
+  const changed: ContractDiff['changed_fields'] = []
+  walk(from, to, '', added, removed, changed)
+  const breaking =
+    removed.length > 0 ||
+    changed.some(c => c.from.required === false && c.to.required === true) ||
+    changed.some(c => !!c.from.type && !!c.to.type && c.from.type !== c.to.type)
+  return { added_fields: added, removed_fields: removed, changed_fields: changed, breaking }
+}

package/src/mcp/agent-public-row.ts

@@ -0,0 +1,52 @@
+import type { AgentListRow } from '../storage/agents-repo.js'
+import type { DeliverySpec } from '../lib/delivery-spec.js'
+
+export type PublicDelivery =
+  | { kind: 'none' }
+  | { kind: 'codex-appserver' }
+  | { kind: 'claude-channel'; channel_session_id: string }
+
+export interface PublicAgentListRow {
+  agent_id: string
+  client: AgentListRow['client']
+  client_name: AgentListRow['client_name']
+  team: string
+  role: string
+  name: string
+  model: string | null
+  tmux_pane_id: string | null
+  delivery: PublicDelivery
+  channel_session_id: string | null
+  last_seen_at: string
+  online: boolean
+}
+
+function projectDelivery(delivery: DeliverySpec): PublicDelivery {
+  if (delivery.kind === 'claude-channel') {
+    return {
+      kind: 'claude-channel',
+      channel_session_id: delivery.channel_session_id,
+    }
+  }
+  return { kind: delivery.kind }
+}
+
+export function toPublicAgentRow(row: AgentListRow): PublicAgentListRow {
+  return {
+    agent_id: row.agent_id,
+    client: row.client,
+    client_name: row.client_name,
+    team: row.team,
+    role: row.role,
+    name: row.name,
+    model: row.model,
+    tmux_pane_id: row.tmux_pane_id,
+    delivery: projectDelivery(row.delivery),
+    channel_session_id:
+      row.delivery.kind === 'claude-channel'
+        ? row.delivery.channel_session_id
+        : null,
+    last_seen_at: row.last_seen_at,
+    online: row.online,
+  }
+}

package/src/mcp/auto-bind-channel.ts

@@ -0,0 +1,106 @@
+import type Database from 'better-sqlite3'
+import type { ChannelWakeFanout } from '../daemon/channel-wake-fanout.js'
+import { CHANNEL_PROXY_ROLE } from './subscribe-channel-wake.js'
+
+const LIVE_WINDOW_MS = 5 * 60 * 1000
+
+export interface AutoBindInput {
+  callerAgentId: string
+  ui_pid: number
+}
+
+export interface LookupInput {
+  ui_pid: number
+}
+
+export interface AutoBindSuccess {
+  ok: true
+  channel_session_id: string
+}
+
+export interface AutoBindMiss {
+  ok: false
+  reason: 'no_proxy_row' | 'proxy_payload_corrupt' | 'sink_not_live'
+}
+
+export type AutoBindResult = AutoBindSuccess | AutoBindMiss
+
+export interface LookupSuccess {
+  ok: true
+  channel_session_id: string
+}
+
+export interface LookupMiss {
+  ok: false
+  reason: 'no_proxy_row' | 'proxy_payload_corrupt'
+}
+
+export type LookupResult = LookupSuccess | LookupMiss
+
+interface ProxyRow {
+  delivery_payload: string | null
+}
+
+/**
+ * Best-effort: match a live __channel_proxy__ row keyed on claude_ui_pid, and
+ * write the caller's delivery to that proxy's csid.  Failure returns `ok:false`
+ * with a reason — the caller treats this as "no auto-bind performed" and leaves
+ * existing delivery unchanged.
+ */
+export class AutoBindChannelService {
+  constructor(
+    private readonly db: Database.Database,
+    private readonly fanout: ChannelWakeFanout
+  ) {}
+
+  lookup(input: LookupInput): LookupResult {
+    return this.findLiveProxyCsid(input)
+  }
+
+  run(input: AutoBindInput): AutoBindResult {
+    const found = this.findLiveProxyCsid({ ui_pid: input.ui_pid })
+    if (!found.ok) return found
+    const csid = found.channel_session_id
+    if (!this.fanout.has(csid)) return { ok: false, reason: 'sink_not_live' }
+    this.db
+      .prepare(
+        `UPDATE agents
+         SET delivery_kind = 'claude-channel',
+             delivery_payload = json_object('channel_session_id', ?)
+         WHERE agent_id = ?`
+      )
+      .run(csid, input.callerAgentId)
+    return { ok: true, channel_session_id: csid }
+  }
+
+  private findLiveProxyCsid(input: LookupInput): LookupResult {
+    const cutoff = new Date(Date.now() - LIVE_WINDOW_MS).toISOString()
+    const row = this.db
+      .prepare(
+        `SELECT delivery_payload
+         FROM agents
+         WHERE role = ?
+           AND claude_ui_pid = ?
+           AND last_seen_at > ?
+         ORDER BY last_seen_at DESC
+         LIMIT 1`
+      )
+      .get(CHANNEL_PROXY_ROLE, input.ui_pid, cutoff) as ProxyRow | undefined
+    if (!row) return { ok: false, reason: 'no_proxy_row' }
+    const csid = extractCsid(row.delivery_payload)
+    if (!csid) return { ok: false, reason: 'proxy_payload_corrupt' }
+    return { ok: true, channel_session_id: csid }
+  }
+}
+
+function extractCsid(payload: string | null): string | null {
+  if (payload === null) return null
+  try {
+    const parsed = JSON.parse(payload) as Record<string, unknown>
+    const csid = parsed.channel_session_id
+    if (typeof csid !== 'string' || csid.length === 0) return null
+    return csid
+  } catch {
+    return null
+  }
+}