co-aqua-chat-interface

A dependency-free, vanilla JavaScript chat interface component inspired by the VS Code / Copilot UX. Available as an npm package, the component provides a deterministic, accessible, and easily embeddable chat experience for web applications, browser-based IDEs, and extensions.

Features

• 🎨 Modern UI - Clean, accessible chat interface with thinking indicators and tool visualization
• 🔌 External Agent Integration - Control surface for connecting to Strands Agents, OpenAI, Anthropic, and custom backends
• 📡 Multi-Protocol Support - WebSocket, SSE (Server-Sent Events), and HTTP modes
• 🔄 Streaming - Real-time streaming for assistant responses, reasoning, and tool outputs
• 💾 Session Management - Create, switch, archive, and delete conversations
• 🎯 Zero Dependencies - Pure vanilla JavaScript, no framework required

Control Surface for External Agents

This library includes a complete control surface for bi-directional communication with external agent backends:

• ✅ BackendBridge - WebSocket/SSE/HTTP communication layer with reconnection
• ✅ UiBindings - Automatic UI event emission and backend event handling
• ✅ Event Schemas - Structured UiEvent and BackendEvent types
• ✅ Graceful Degradation - UI works with or without backend connectivity

📖 See CONTROL_SURFACE.md for complete documentation, including:

• Quick start examples
• Event schemas and API reference
• Backend integration guides (Strands, OpenAI, Anthropic)
• FastAPI and Node.js backend examples
• Streaming modes and session management

Planning References

• Product definition: plans/product-definition.md
• Architecture: plans/architecture.md
• User stories: plans/user-stories.md
• Development plan: plans/dev-plan.md
• Control surface: CONTROL_SURFACE.md

Getting Started

Installation

npm install co-aqua-chat-interface

Basic Usage

import { createChatColumn } from 'co-aqua-chat-interface';
import 'co-aqua-chat-interface/styles';

const root = document.getElementById('chat-root');
const controller = createChatColumn(root, {
  config: { debug: true }
});

// Create a new session
const sessionId = controller.createNewSession();
controller.switchToSession(sessionId);

// Add a message
controller.appendUserMessage(sessionId, "Hello!");

With External Agent Backend

import { 
  createChatColumn, 
  createBackendBridge, 
  createUiBindings,
  createEventBus 
} from 'co-aqua-chat-interface';
import 'co-aqua-chat-interface/styles';

// Create chat column
const controller = createChatColumn(root);
const eventBus = createEventBus({ dev: true });

// Connect to backend
const bridge = createBackendBridge({
  connection: {
    mode: 'websocket',
    url: 'ws://localhost:8000/ws'
  },
  eventBus
});

// Create UI bindings
const bindings = createUiBindings({
  controller,
  eventBus,
  backendBridge: bridge
});

await bridge.connect();

See CONTROL_SURFACE.md for complete integration guide.

Development

Development tasks follow the detailed plan in plans/dev-plan.md. Initial setup requires Node.js 22 and npm.

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Build for production
npm run build