Hall Chat MVP - Multi-Agent Collaboration for ClawUI

Status: Draft | Priority: High | Target: v1.0 | Date: 2026-03-31

Overview

Hall Chat enables multiple AI agents to collaborate on tasks in a shared workspace — similar to a team chat room, but with structured task cards, execution queues, and handoff protocols. Reference Implementation: OpenClaw Control Center’s Collaboration Hall (/src/runtime/collaboration-hall-*)

Problem Statement

Currently in ClawUI:

Each agent works in isolation
Agents cannot delegate tasks to each other
No shared context or task coordination
Users manually copy information between agents

We need: A shared “hall” where agents can discuss, delegate, execute, and hand off work in a structured way.

Core Concepts

Hall

A virtual collaboration space for a project or task. Contains:

Participants (agents + operator)
Task Cards
Message History

Task Card

A unit of work tracked in the hall:

interface TaskCard {
  taskCardId: string;
  title: string;
  description: string;
  stage: 'discussion' | 'execution' | 'review' | 'done';
  currentOwner?: string;          // participantId
  plannedExecutionOrder: string[]; // Queue of participantIds
  currentExecutionItem?: {
    task: string;
    doneWhen: string;
    handoffToParticipantId?: string;
  };
  blockers: string[];
  requiresInputFrom: string[];
  proposal?: string;
  decision?: string;
  doneWhen?: string;
}

Participant

An agent or human in the hall:

interface Participant {
  participantId: string;          // e.g., "agent:donnie"
  displayName: string;            // e.g., "Donnie"
  agentId?: string;                // OpenClaw agent ID
  semanticRole: 'planner' | 'coder' | 'reviewer' | 'manager' | 'generalist';
  active: boolean;
  aliases: string[];
}

Message

A communication in the hall:

interface HallMessage {
  messageId: string;
  authorParticipantId: string;
  authorLabel: string;
  content: string;
  kind: 'proposal' | 'decision' | 'status' | 'handoff' | 'greeting';
  mentionTargets?: string[];
  timestamp: string;
}

MVP Features (v1.0)

P0 - Must Have

Feature	Description
Create Hall	Create a new hall for a project
Add Participants	Register agents as participants
Post Message	Send a message to the hall
List Messages	View message history
List Task Cards	View all tasks in hall
Create Task Card	Start a new task
Update Task Card	Modify task state
SSE Streaming	Real-time updates to UI

P1 - Should Have

Feature	Description
@Mention Routing	Route messages to specific agents
Execution Queue	Ordered handoff between agents
Structured Handoff	Formal work transfer protocol
Task Stage Transitions	discussion → execution → review → done

P2 - Nice to Have

Feature	Description
Hall Summary	AI-generated recap of hall state
Artifact Sharing	Share code/doc links between participants
Hall Rules	Custom collaboration guidelines

User Flows

Flow 1: Discussion → Execution

Operator: "We need to build a new API endpoint"
        ↓
Hall: Message posted
        ↓
Agent A (planner): "I suggest we start with the auth module"
        ↓
Agent B (coder): "I'll handle the endpoint implementation"
        ↓
Operator: "Sounds good. @coder please execute"
        ↓
Hall: Task moves to execution stage
        ↓
Agent B: *works on implementation*
        ↓
Agent B: "Done, @reviewer please check"
        ↓
Agent C (reviewer): "LGTM, ready for merge"
        ↓
Hall: Task moves to done

Flow 2: Handoff Between Agents

Agent A (current owner): "I've finished my part"
        ↓
Structured Handoff Packet:
{
  goal: "Implement user auth",
  currentResult: "JWT middleware working",
  doneWhen: "All tests pass",
  blockers: [],
  artifactRefs: [{ location: "/auth/jwt.ts" }]
}
        ↓
Hall: Automatically routes to next owner in queue
        ↓
Agent B (next owner): "Got it, continuing from where you left off"
        ↓
Agent B: *continues work*

Technical Architecture

Components

┌──────────────────────────────────────────────────────┐
│                   ClawUI Frontend                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │  Hall List  │  │Hall Detail  │  │Task Card UI │   │
│  └──────┬──────┘  └─────┬───────┘  └─────┬───────┘   │
└─────────┼───────────────┼────────────────┼───────────┘
          │               │                │
          │         SSE Streaming          │
          │               │                │
┌─────────┼───────────────┼────────────────┼───────────┐
│         │     Hall API (REST/WebSocket)  │           │
│         │               │                │           │
│  ┌──────▼───────────────▼────────────────▼───────┐   │
│  │              Hall Service                     │   │
│  │  ┌─────────────┐  ┌─────────────────────────┐ │   │
│  │  │Hall Store   │  │Hall Orchestrator        │ │   │
│  │  └─────────────┘  └─────────────────────────┘ │   │
│  └───────────────────────────────────────────────┘   │
│                          │                           │
│  ┌───────────────────────▼───────────────────────┐   │
│  │           Agent Runtime Dispatch              │   │
│  │  (Connects to OpenClaw agent sessions)        │   │
│  └───────────────────────────────────────────────┘   │
│                          │                           │
│  ┌───────────────────────▼───────────────────────┐   │
│  │              NATS Event Bus                   │   │
│  │  (Existing infrastructure)                    │   │
│  └───────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘

Data Model

Hall

interface CollaborationHall {
  hallId: string;
  projectId?: string;
  title: string;
  participants: Participant[];
  createdAt: string;
  updatedAt: string;
}

HallMessage (stored in Hall)

interface HallMessage {
  messageId: string;
  hallId: string;
  taskCardId?: string;
  authorParticipantId: string;
  authorLabel: string;
  content: string;
  kind: 'proposal' | 'decision' | 'status' | 'handoff' | 'greeting';
  mentionTargets?: string[];
  payload?: {
    sessionKey?: string;
    artifactRefs?: ArtifactRef[];
    executionOrder?: string[];
    decision?: string;
    proposal?: string;
    doneWhen?: string;
    nextOwnerParticipantId?: string;
  };
  timestamp: string;
}

TaskCard (stored in Hall)

interface TaskCard {
  taskCardId: string;
  hallId: string;
  taskId?: string;          // Link to external task
  title: string;
  description: string;
  stage: 'discussion' | 'execution' | 'review' | 'done';
  status: 'pending' | 'in_progress' | 'blocked' | 'completed';
  currentOwnerParticipantId?: string;
  plannedExecutionOrder: string[];  // Queue of participantIds
  currentExecutionItem?: {
    participantId: string;
    task: string;
    doneWhen: string;
    handoffToParticipantId?: string;
  };
  plannedExecutionItems: Array<{
    participantId: string;
    task: string;
    handoffToParticipantId?: string;
  }>;
  blockers: string[];
  requiresInputFrom: string[];
  mentionedParticipantIds: string[];
  proposal?: string;
  decision?: string;
  doneWhen?: string;
  latestSummary?: string;
  sessionKeys: string[];     // Linked agent sessions
  artifacts: ArtifactRef[];
  createdAt: string;
  updatedAt: string;
}

API Endpoints

Method	Endpoint	Description
POST	`/api/halls`	Create a new hall
GET	`/api/halls`	List all halls
GET	`/api/halls/:hallId`	Get hall details
DELETE	`/api/halls/:hallId`	Delete hall
POST	`/api/halls/:hallId/participants`	Add participant
GET	`/api/halls/:hallId/messages`	List messages (paginated)
POST	`/api/halls/:hallId/messages`	Post a message
GET	`/api/halls/:hallId/tasks`	List task cards
POST	`/api/halls/:hallId/tasks`	Create task card
PATCH	`/api/halls/:hallId/tasks/:taskCardId`	Update task card
POST	`/api/halls/:hallId/tasks/:taskCardId/execute`	Trigger execution
GET	`/api/halls/:hallId/stream`	SSE stream for real-time updates

NATS Subjects

halls.{hallId}.messages    # New messages
halls.{hallId}.tasks      # Task updates
halls.{hallId}.presence    # Participant presence

Implementation Phases

Phase 1: Foundation (MVP)

Phase 2: Task Coordination

Phase 3: Agent Integration

Runtime dispatch to OpenClaw agents
Agent session linking
Streaming responses from agents
Structured handoff protocol

Phase 4: Polish

Hall summaries
Artifact sharing
Custom hall rules
UI components refinement

UI Mockups (Text)

Hall List View

┌─────────────────────────────────────────┐
│ Halls                            [+ New]│
├─────────────────────────────────────────┤
│ 📋 Backend API Development              │
│    3 participants • 5 tasks • 2 active  │
│                                         │
│ 📋 Frontend Components                  │
│    2 participants • 3 tasks • 1 active  │
└─────────────────────────────────────────┘

Hall Detail View

┌─────────────────────────────────────────┐
│ ← Back                   [Participants] │
├─────────────────────────────────────────┤
│ Backend API Development                 │
├─────────────────────────────────────────┤
│ Participants: Donnie, Bruce, Reviewer   │
├─────────────────────────────────────────┤
│ ┌─ Task: Auth Endpoint ──────────────┐  │
│ │ Stage: execution │ Owner: Bruce    │  │
│ │ Queue: Bruce → Reviewer → Done     │  │
│ └────────────────────────────────────┘  │
├─────────────────────────────────────────┤
│ Messages:                               │
│                                         │
│ Donnie: Let's start with JWT auth       │
│ Bruce: I'll handle the middleware       │
│ Donnie: @Bruce please execute           │
│ Bruce: Working on it now...             │
│                                         │
├─────────────────────────────────────────┤
│ [Type a message...]              [Send] │
└─────────────────────────────────────────┘

Open Questions

Persistence — Redis only, or PostgreSQL?
Agent Discovery — How do we know which agents exist?
Authorization — Who can create halls? Add participants?
Scaling — Multiple halls vs single hall per project?
History — How long to keep messages?

Reference Files

These are the source files from OpenClaw Control Center that implement Hall Chat:

/Users/gremlin/Dev/openclaw-control-center/src/runtime/
├── collaboration-hall-orchestrator.ts    # Main orchestration logic
├── collaboration-hall-store.ts           # Hall persistence
├── collaboration-hall-summary-store.ts   # Hall summaries
├── hall-runtime-dispatch.ts              # Agent runtime dispatch
├── hall-handoff.ts                       # Structured handoff protocol
├── hall-mention-router.ts              # @mention routing
├── hall-role-resolver.ts                # Role resolution
├── hall-speaker-policy.ts               # Who speaks when
├── hall-discussion-domain.ts            # Domain inference
└── hall-execution-lock.ts              # Execution locking

Key reading order:

hall-runtime-dispatch.ts — How agents get dispatched and return responses
collaboration-hall-orchestrator.ts — Main flow and state machine
hall-handoff.ts — Structured handoff format
hall-speaker-policy.ts — Discussion queue management

Last updated: 2026-03-31

​Hall Chat MVP - Multi-Agent Collaboration for ClawUI

​Overview

​Problem Statement

​Core Concepts

​Hall

​Task Card

​Participant

​Message

​MVP Features (v1.0)

​P0 - Must Have

​P1 - Should Have

​P2 - Nice to Have

​User Flows

​Flow 1: Discussion → Execution

​Flow 2: Handoff Between Agents

​Technical Architecture

​Components

​Data Model

​API Endpoints

​NATS Subjects

​Implementation Phases

​Phase 1: Foundation (MVP)

​Phase 2: Task Coordination

​Phase 3: Agent Integration

​Phase 4: Polish

​UI Mockups (Text)

​Hall List View

​Hall Detail View

​Open Questions

​Reference Files