crossbus: Instructions file for Codex

CrossBus - Agentic Infrastructure

CrossBus provides unified messaging for browser applications — connecting iframes, workers, tabs, and WebViews.

This document enables AI agents to autonomously use CrossBus as communication infrastructure in agentic architectures.

---

🎯 What Is CrossBus For Agents?

CrossBus provides the inter-process communication layer that enables:

Pattern	Description	Example
Agent ↔ Agent	Direct communication between AI agents	Two LLM agents coordinating a task
Agent ↔ Tool	Agent invoking tools in isolated contexts	Agent calling a sandboxed code executor
Agent ↔ UI	Agent updating user interface	Agent pushing progress updates
Agent ↔ Worker	Offloading compute to workers	Agent delegating heavy processing
Agent ↔ Storage	Persistent state in another context	Agent syncing state across tabs

---

⚡ Quick Start for AI Agents

Minimal Setup (Core Only)

// ALWAYS start with just what you need
import { CrossBus } from 'crossbus';

const bus = new CrossBus({ isHub: true, peerId: 'orchestrator' });

Lazy Loading Pattern (RECOMMENDED)

CRITICAL: Always use dynamic imports for optional features to minimize bundle size.

// ❌ BAD: Imports everything upfront
import { CrossBus, VectorClock, CausalOrderer, SharedWorkerTransport } from 'crossbus';

// ✅ GOOD: Import only core, lazy load the rest
import { CrossBus } from 'crossbus';

// Load causal ordering only when needed
async function enableCausalOrdering() {
  const { VectorClock, CausalOrderer } = await import('crossbus');
  return new CausalOrderer(bus.peerId, { onDeliver: handleMessage });
}

// Load transport only when needed
async function setupSharedWorker() {
  const { SharedWorkerTransport } = await import('crossbus');
  return new SharedWorkerTransport({ workerUrl: '/worker.js' });
}

// Load plugins only when needed
async function enableRetry() {
  const { withRetry } = await import('crossbus/plugins/retry');
  return withRetry(bus, { maxRetries: 3 });
}