refactor: Replace REST API with WebSocket-only architecture

- Remove all REST endpoints, replace with WebSocket message-based API
- Add WebSocket gateway with Hub and Client for connection management
- Add WebSocket handlers for Task, Agent, and Orchestrator services
- Add task subscription support for real-time ACP notifications
- Update all documentation to reflect WebSocket-first architecture
- Replace docs/openapi.yaml with docs/asyncapi.yaml
- Update e2e tests to use WebSocket via websocat

WebSocket endpoint: ws://localhost:8080/ws
Message format: {id, type, action, payload, timestamp}

Available actions:
- Board: board.list, board.create, board.get, board.update, board.delete
- Column: column.list, column.create, column.get
- Task: task.list, task.create, task.get, task.update, task.delete,
        task.move, task.state, task.subscribe, task.unsubscribe
- Agent: agent.list, agent.launch, agent.status, agent.logs, agent.stop,
         agent.prompt, agent.cancel, agent.session, agent.types
- Orchestrator: orchestrator.status, orchestrator.queue, orchestrator.trigger,
                orchestrator.start, orchestrator.stop, orchestrator.prompt,
                orchestrator.complete
- Health: health.check
This commit is contained in:
jcfs
2026-01-10 23:01:05 +00:00
parent acee9f4278
commit 35915ff0cb
24 changed files with 3595 additions and 1918 deletions
+75 -30
View File
@@ -25,7 +25,7 @@ The system runs as a **unified Go binary** that includes:
- **Task Service**: Manages tasks, boards, and columns with SQLite persistence
- **Agent Manager**: Manages Docker container lifecycle and ACP message streaming
- **Orchestrator**: Coordinates agent launches and monitors execution
- **HTTP API**: RESTful endpoints for all operations (Port 8080)
- **WebSocket API**: Real-time bidirectional communication for all operations (Port 8080)
### Agent Communication Protocol (ACP)
@@ -78,39 +78,84 @@ make build
KANDEV_DB_PATH=/path/to/kandev.db ./bin/kandev
```
### API Usage
### WebSocket API Usage
```bash
# Create a board
curl -X POST http://localhost:8080/api/v1/boards \
-H "Content-Type: application/json" \
-d '{"name": "My Project", "description": "Project tasks"}'
**Connection**: `ws://localhost:8080/ws`
# Create a column
curl -X POST http://localhost:8080/api/v1/boards/{board_id}/columns \
-H "Content-Type: application/json" \
-d '{"name": "To Do"}'
#### Message Envelope
# Create a task
curl -X POST http://localhost:8080/api/v1/boards/{board_id}/columns/{column_id}/tasks \
-H "Content-Type: application/json" \
-d '{"title": "Fix login bug", "description": "Users cannot login"}'
```json
{
"id": "correlation-uuid",
"type": "request|response|notification|error",
"action": "action.name",
"payload": {},
"timestamp": "2026-01-10T10:30:00Z"
}
```
# Launch an agent for a task
curl -X POST http://localhost:8080/api/v1/agents/launch \
-H "Content-Type: application/json" \
-d '{
"task_id": "{task_id}",
"agent_type": "augment-agent",
"workspace_path": "/path/to/project",
"env": {
"AUGMENT_SESSION_AUTH": "...",
"TASK_DESCRIPTION": "What is 2+2?"
#### Key Message Actions
- `board.create` - Create board
- `board.list` - List boards
- `column.create` - Create column
- `task.create` - Create task
- `agent.launch` - Launch agent
- `agent.status` - Get agent status
- `orchestrator.start` - Start task execution
#### Example Usage (JavaScript)
```javascript
const ws = new WebSocket('ws://localhost:8080/ws');
// Create a board
ws.send(JSON.stringify({
id: crypto.randomUUID(),
type: 'request',
action: 'board.create',
payload: { name: 'My Project', description: 'Project tasks' }
}));
// Create a task
ws.send(JSON.stringify({
id: crypto.randomUUID(),
type: 'request',
action: 'task.create',
payload: {
board_id: '{board_id}',
column_id: '{column_id}',
title: 'Fix login bug',
description: 'Users cannot login'
}
}));
// Launch an agent
ws.send(JSON.stringify({
id: crypto.randomUUID(),
type: 'request',
action: 'agent.launch',
payload: {
task_id: '{task_id}',
agent_type: 'augment-agent',
workspace_path: '/path/to/project',
env: {
AUGMENT_SESSION_AUTH: '...',
TASK_DESCRIPTION: 'What is 2+2?'
}
}'
}
}));
# Check agent status
curl http://localhost:8080/api/v1/agents/{agent_id}/status
// Handle responses and notifications
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.type === 'response') {
console.log('Response:', msg.payload);
} else if (msg.type === 'notification') {
// Real-time updates: acp.progress, acp.log, task.updated, etc.
console.log('Notification:', msg.action, msg.payload);
}
};
```
See [apps/backend/NEXT_STEPS.md](apps/backend/NEXT_STEPS.md) for detailed API reference and next steps.
@@ -171,11 +216,11 @@ go vet ./...
- [x] Agent lifecycle management with Docker
- [x] ACP message streaming from containers
- [x] Session resumption for multi-turn agent conversations
- [x] RESTful API for all operations
- [x] WebSocket-first API for all operations
- [x] Real-time bidirectional communication
🚧 **In Progress**
- [ ] WebSocket support for real-time streaming to frontend
- [ ] Authentication and authorization
- [ ] Frontend UI