Collaboration Hub Developer

Build and modify the AILANG Collaboration Hub - a React-based UI for multi-agent coordination.

Quick Start

Starting the server:

ailang serve                    # Start on default port 1957
ailang serve --port 8080        # Use custom port

After making UI changes:

cd ui && npm run build                              # Build React app
cp -r ui/dist/* internal/server/dist/               # Copy to server
ailang serve                                        # Restart server

When to Use This Skill

Use this skill when the user asks to:

• Add features to the monitoring dashboard
• Modify the approval queue UI
• Update the message center or thread list
• Make changes to the React frontend
• Style or theme the Collaboration Hub
• Add new tabs or components

Architecture Overview

Backend (Go):

• internal/server/server.go - HTTP server, REST API, WebSocket
• internal/server/monitor.go - Process monitoring endpoints
• internal/server/telemetry.go - Real-time telemetry WebSocket

Frontend (React + TypeScript + Vite):

ui/
├── src/
│   ├── App.tsx                 # Main app, tabs, agent selector
│   ├── main.tsx                # React entry point
│   ├── types/index.ts          # TypeScript interfaces
│   ├── styles/                 # CSS variables and themes
│   └── components/
│       ├── MessageCenter/      # Thread-based messaging
│       │   ├── MessageCenter.tsx    # Main container, WebSocket
│       │   ├── ThreadList.tsx       # Conversation list sidebar
│       │   └── ConversationView.tsx # Message display and input
│       ├── ApprovalQueue/      # Effect approval workflow
│       │   └── ApprovalQueue.tsx    # Pending + history
│       └── Monitor/            # Process monitoring
│           └── Monitor.tsx          # Live stats, telemetry
├── dist/                       # Built assets (after npm run build)
└── package.json

Database:

• SQLite at ~/.ailang/state/collaboration.db
• Tables: threads, messages, approvals

Key Components

App.tsx

• Tab navigation (Messages, Approvals, Monitor)
• Agent selector dropdown
• Approval state management with history
• WebSocket URL construction

MessageCenter.tsx

• WebSocket connection management
• Thread CRUD operations
• Message sending with workspace support
• Unread counts tracking

ConversationView.tsx

• Thread header with title and agent badge
• Message list with auto-scroll
• Markdown rendering for agent responses
• Message input with kind selector

ThreadList.tsx

• Conversation list with status dots
• New thread creation form
• Unread badge display
• Timestamp formatting

ApprovalQueue.tsx

• Pending approval cards with effect deltas
• Expand/collapse details
• Approve/reject with notes
• Review history section (collapsible)

Monitor.tsx

• Process grid with live stats
• Telemetry overlay (tokens, cost)
• History section for completed processes
• Source badges (ui, eval, cli, agent)

CSS Variables

The UI uses CSS custom properties defined in ui/src/styles/:

/* Colors */
--color-primary: #25C2A0;
--color-success: #10B981;
--color-warning: #F59E0B;
--color-danger: #EF4444;

/* Backgrounds */
--bg-base: #0D1117;
--bg-surface: #161B22;
--bg-elevated: #21262D;
--bg-hover: #30363D;

/* Text */
--text-primary: #E6EDF3;
--text-secondary: #8B949E;
--text-tertiary: #6E7681;

/* Spacing */
--space-1 through --space-8

/* Typography */
--text-xs through --text-xl
--font-medium, --font-semibold, --font-bold

REST API Endpoints

Threads:

• GET /api/threads - List all threads
• POST /api/threads - Create thread
• GET /api/threads/:id/messages - Get messages

Messages:

• POST /api/messages - Send message

Approvals:

• GET /api/approvals?status=pending - Pending approvals
• GET /api/approvals?status=approved - Approved history
• GET /api/approvals?status=rejected - Rejected history
• POST /api/approvals/:id/approve - Approve with notes
• POST /api/approvals/:id/reject - Reject with notes

Monitor:

• GET /api/monitor - Process stats + history

WebSocket:

• ws://localhost:1957/ws - Real-time events
  • new_message - New message in thread
  • thread_state - Thread status change
  • telemetry - Live process metrics

TypeScript Interfaces

Key types in ui/src/types/index.ts:

interface Thread {
  id: string;
  title: string;
  status: 'active' | 'paused' | 'resolved' | 'archived';
  target_agent?: string;
  last_seq: number;
  // ...
}

interface Message {
  id: string;
  thread_id: string;
  kind: 'directive' | 'status' | 'result' | 'approval_request';
  content: string;
  sender_type: 'human' | 'agent';
  // ...
}

interface Approval {
  id: string;
  status: 'pending' | 'approved' | 'rejected';
  proposal: string;
  impact: 'low' | 'medium' | 'high';
  estimated_cost: number;
  effect_delta_json: string;
  reviewed_by?: string;
  review_notes?: string;
  // ...
}

Common Tasks

Adding a New Tab

1. Add tab state in App.tsx:

   const [activeTab, setActiveTab] = useState<'messages' | 'approvals' | 'monitor' | 'newtab'>
   

2. Add tab button in nav:

   <button className={`tab ${activeTab === 'newtab' ? 'active' : ''}`}
           onClick={() => setActiveTab('newtab')}>
     New Tab
   </button>
   

3. Add component render:

   {activeTab === 'newtab' && <NewComponent />}
   

Adding a New API Endpoint

1. Add handler in internal/server/server.go
2. Register route in setupRoutes()
3. Add TypeScript interface if needed
4. Create fetch function in component

Styling Components

Use CSS-in-JS pattern with <style> tags:

<div className="my-component">
  {/* content */}
  <style>{`
    .my-component {
      background: var(--bg-surface);
      padding: var(--space-4);
      border-radius: var(--radius-md);
    }
  `}</style>
</div>

Development Workflow

1. Make changes in ui/src/
2. Build: cd ui && npm run build
3. Copy: cp -r ui/dist/* internal/server/dist/
4. Test: ailang serve and open browser
5. Iterate as needed

For hot reload during development:

cd ui && npm run dev  # Runs Vite dev server on :5173
# But you'll need to proxy API calls - easier to just rebuild

Troubleshooting

Server won't start:

• Check if port 1957 is in use: lsof -i :1957
• Use different port: ailang serve --port 8080

UI changes not appearing:

• Rebuild: cd ui && npm run build
• Copy to dist: cp -r ui/dist/* internal/server/dist/
• Hard refresh browser: Cmd+Shift+R

WebSocket not connecting:

• Check browser console for errors
• Verify server is running on correct port
• Check CORS if using different origins