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:
@@ -3,7 +3,7 @@
|
||||
> **For Agent Developers**: This document explains how to build agents that integrate with Kandev using the Agent Communication Protocol (ACP).
|
||||
>
|
||||
> **For System Architecture**: See [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
> **For REST API**: See [docs/openapi.yaml](docs/openapi.yaml)
|
||||
> **For WebSocket API**: See [docs/asyncapi.yaml](docs/asyncapi.yaml)
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -483,81 +483,147 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":
|
||||
|
||||
---
|
||||
|
||||
## REST API Integration
|
||||
## WebSocket API Integration
|
||||
|
||||
All agent control operations use WebSocket messages with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "request|response",
|
||||
"action": "action.name",
|
||||
"payload": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Launch Agent
|
||||
|
||||
```bash
|
||||
POST /api/v1/agents/launch
|
||||
```
|
||||
**Action**: `agent.launch`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"task_id": "uuid",
|
||||
"agent_type": "augment-agent",
|
||||
"workspace_path": "/absolute/path/to/project",
|
||||
"env": {
|
||||
"AUGMENT_SESSION_AUTH": "{...}",
|
||||
"TASK_DESCRIPTION": "Fix the bug in auth/login.go"
|
||||
},
|
||||
"priority": 1,
|
||||
"metadata": {}
|
||||
"id": "uuid",
|
||||
"type": "request",
|
||||
"action": "agent.launch",
|
||||
"payload": {
|
||||
"task_id": "uuid",
|
||||
"agent_type": "augment-agent",
|
||||
"workspace_path": "/absolute/path/to/project",
|
||||
"env": {
|
||||
"AUGMENT_SESSION_AUTH": "{...}",
|
||||
"TASK_DESCRIPTION": "Fix the bug in auth/login.go"
|
||||
},
|
||||
"priority": 1,
|
||||
"metadata": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "instance-uuid",
|
||||
"task_id": "uuid",
|
||||
"agent_type": "augment-agent",
|
||||
"container_id": "docker-id",
|
||||
"status": "starting",
|
||||
"started_at": "2026-01-10T12:00:00Z"
|
||||
"id": "uuid",
|
||||
"type": "response",
|
||||
"action": "agent.launch",
|
||||
"payload": {
|
||||
"id": "instance-uuid",
|
||||
"task_id": "uuid",
|
||||
"agent_type": "augment-agent",
|
||||
"container_id": "docker-id",
|
||||
"status": "starting",
|
||||
"started_at": "2026-01-10T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Send Prompt (Mid-Execution)
|
||||
|
||||
```bash
|
||||
POST /api/v1/agents/:instanceId/prompt
|
||||
```
|
||||
**Action**: `agent.prompt`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"message": "Please also add unit tests"
|
||||
"id": "uuid",
|
||||
"type": "request",
|
||||
"action": "agent.prompt",
|
||||
"payload": {
|
||||
"instance_id": "instance-uuid",
|
||||
"message": "Please also add unit tests"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cancel Agent
|
||||
|
||||
```bash
|
||||
POST /api/v1/agents/:instanceId/cancel
|
||||
```
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"reason": "User requested cancellation"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Agent Status
|
||||
|
||||
```bash
|
||||
GET /api/v1/agents/:instanceId/status
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "instance-uuid",
|
||||
"status": "running",
|
||||
"progress": 50,
|
||||
"started_at": "2026-01-10T12:00:00Z",
|
||||
"finished_at": null
|
||||
"id": "uuid",
|
||||
"type": "response",
|
||||
"action": "agent.prompt",
|
||||
"payload": {
|
||||
"status": "accepted"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cancel Agent
|
||||
|
||||
**Action**: `agent.cancel`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "request",
|
||||
"action": "agent.cancel",
|
||||
"payload": {
|
||||
"instance_id": "instance-uuid",
|
||||
"reason": "User requested cancellation"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "response",
|
||||
"action": "agent.cancel",
|
||||
"payload": {
|
||||
"status": "cancelled"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Agent Status
|
||||
|
||||
**Action**: `agent.status`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "request",
|
||||
"action": "agent.status",
|
||||
"payload": {
|
||||
"instance_id": "instance-uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "response",
|
||||
"action": "agent.status",
|
||||
"payload": {
|
||||
"id": "instance-uuid",
|
||||
"status": "running",
|
||||
"progress": 50,
|
||||
"started_at": "2026-01-10T12:00:00Z",
|
||||
"finished_at": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -565,23 +631,61 @@ Statuses: `starting`, `running`, `completed`, `failed`, `stopped`
|
||||
|
||||
### Get Agent Logs
|
||||
|
||||
```bash
|
||||
GET /api/v1/agents/:instanceId/logs?tail=100
|
||||
```
|
||||
**Action**: `agent.logs`
|
||||
|
||||
### Get Session Info
|
||||
|
||||
```bash
|
||||
GET /api/v1/agents/:instanceId/session
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "request",
|
||||
"action": "agent.logs",
|
||||
"payload": {
|
||||
"instance_id": "instance-uuid",
|
||||
"tail": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"instance_id": "instance-uuid",
|
||||
"task_id": "task-uuid",
|
||||
"session_id": "abc123",
|
||||
"status": "running"
|
||||
"id": "uuid",
|
||||
"type": "response",
|
||||
"action": "agent.logs",
|
||||
"payload": {
|
||||
"logs": ["line1", "line2", "..."]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Session Info
|
||||
|
||||
**Action**: `agent.session`
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "request",
|
||||
"action": "agent.session",
|
||||
"payload": {
|
||||
"instance_id": "instance-uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"type": "response",
|
||||
"action": "agent.session",
|
||||
"payload": {
|
||||
"instance_id": "instance-uuid",
|
||||
"task_id": "task-uuid",
|
||||
"session_id": "abc123",
|
||||
"status": "running"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -594,29 +698,48 @@ Agents can resume previous sessions for follow-up conversations.
|
||||
### How It Works
|
||||
|
||||
1. First task completes, session ID stored in task metadata
|
||||
2. Retrieve session ID from task: `GET /tasks/:taskId` → `metadata.auggie_session_id`
|
||||
2. Retrieve session ID via WebSocket `task.get` action → `metadata.auggie_session_id`
|
||||
3. Launch new task with `AUGGIE_SESSION_ID` environment variable
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# Get session ID from completed task
|
||||
SESSION_ID=$(curl -s http://localhost:8080/api/v1/tasks/$TASK_ID | \
|
||||
jq -r '.metadata.auggie_session_id')
|
||||
```javascript
|
||||
// WebSocket connection
|
||||
const ws = new WebSocket('ws://localhost:8080/api/v1/ws');
|
||||
|
||||
# Launch with resumption
|
||||
curl -X POST http://localhost:8080/api/v1/agents/launch \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"task_id": "'$NEW_TASK_ID'",
|
||||
"agent_type": "augment-agent",
|
||||
"workspace_path": "/path/to/project",
|
||||
"env": {
|
||||
"AUGMENT_SESSION_AUTH": "'"$(cat ~/.augment/session.json | jq -c)"'",
|
||||
"AUGGIE_SESSION_ID": "'$SESSION_ID'",
|
||||
"TASK_DESCRIPTION": "What changes did you make in the previous task?"
|
||||
}
|
||||
}'
|
||||
// Get session ID from completed task
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'task.get',
|
||||
payload: { task_id: previousTaskId }
|
||||
}));
|
||||
|
||||
// Handle response and launch with resumption
|
||||
ws.onmessage = (event) => {
|
||||
const response = JSON.parse(event.data);
|
||||
|
||||
if (response.action === 'task.get') {
|
||||
const sessionId = response.payload.metadata.auggie_session_id;
|
||||
|
||||
// Launch agent with session resumption
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'agent.launch',
|
||||
payload: {
|
||||
task_id: newTaskId,
|
||||
agent_type: 'augment-agent',
|
||||
workspace_path: '/path/to/project',
|
||||
env: {
|
||||
AUGMENT_SESSION_AUTH: JSON.stringify(sessionAuth),
|
||||
AUGGIE_SESSION_ID: sessionId,
|
||||
TASK_DESCRIPTION: 'What changes did you make in the previous task?'
|
||||
}
|
||||
}
|
||||
}));
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
The agent will load the previous context and continue the conversation.
|
||||
@@ -779,7 +902,7 @@ See `apps/backend/` for complete working examples:
|
||||
## Additional Resources
|
||||
|
||||
- **System Architecture**: [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
- **REST API Specification**: [docs/openapi.yaml](docs/openapi.yaml)
|
||||
- **WebSocket API Specification**: [docs/asyncapi.yaml](docs/asyncapi.yaml)
|
||||
- **Agent Registry**: `apps/backend/internal/agent/registry/defaults.go`
|
||||
- **agentctl Implementation**: `apps/backend/internal/agentctl/`
|
||||
- **ACP Protocol Types**: `apps/backend/pkg/acp/jsonrpc/`
|
||||
|
||||
+171
-61
@@ -11,10 +11,10 @@ Kandev is a kanban board with AI agent orchestration. Three main components:
|
||||
│ Web UI (Next.js 16 + React 19) │
|
||||
│ http://localhost:3000 │
|
||||
└───────────────────────┬──────────────────────────────────┘
|
||||
│ HTTP/WebSocket
|
||||
│ WebSocket (ws://localhost:8080/ws)
|
||||
┌───────────────────────▼──────────────────────────────────┐
|
||||
│ Backend (Go + Gin + SQLite) │
|
||||
│ http://localhost:8080 │
|
||||
│ ws://localhost:8080/ws │
|
||||
│ │
|
||||
│ [Task Service] [Agent Manager] [Orchestrator] │
|
||||
│ [Event Bus: In-Memory/NATS] │
|
||||
@@ -55,7 +55,8 @@ make test
|
||||
|
||||
### Backend (`apps/backend/`)
|
||||
- **Language**: Go 1.21+
|
||||
- **Framework**: Gin (HTTP), Gorilla WebSocket
|
||||
- **Framework**: Gin, Gorilla WebSocket
|
||||
- **Protocol**: WebSocket (message-based API)
|
||||
- **Database**: SQLite (WAL mode)
|
||||
- **Container**: Docker client
|
||||
- **Logging**: Zap
|
||||
@@ -91,18 +92,18 @@ make test
|
||||
│ ├── acp/ # ACP protocol types
|
||||
│ └── api/v1/ # API models
|
||||
└── docs/
|
||||
└── openapi.yaml # REST API specification
|
||||
└── asyncapi.yaml # WebSocket API specification
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. User creates task in web UI
|
||||
2. POST `/api/v1/tasks` → SQLite
|
||||
2. WebSocket `task.create` message → SQLite
|
||||
3. User launches agent for task
|
||||
4. Backend spawns Docker container
|
||||
4. WebSocket `agent.launch` message → Backend spawns Docker container
|
||||
5. Agent streams progress via ACP
|
||||
6. Events published to event bus
|
||||
7. WebSocket pushes updates to UI
|
||||
7. WebSocket notifications pushed to UI (`task.updated`, `agent.updated`)
|
||||
|
||||
## Backend Services
|
||||
|
||||
@@ -123,24 +124,93 @@ make test
|
||||
- **Responsibility**: Queue tasks, coordinate execution
|
||||
- **Features**: Task queue, agent launch, monitoring
|
||||
|
||||
## API Endpoints
|
||||
## WebSocket Message Types
|
||||
|
||||
**Base**: `http://localhost:8080/api/v1`
|
||||
**Connection**: `ws://localhost:8080/ws`
|
||||
|
||||
| Endpoint | Purpose |
|
||||
|----------|---------|
|
||||
| `GET /health` | Health check |
|
||||
| `/boards` | Board CRUD |
|
||||
| `/columns` | Column CRUD |
|
||||
| `/tasks` | Task CRUD, move, state changes |
|
||||
| `/agents/launch` | Launch agent for task |
|
||||
| `/agents/:id/status` | Agent status |
|
||||
| `/agents/:id/logs` | Agent logs |
|
||||
| `/agents/:id/prompt` | Send prompt (ACP) |
|
||||
| `/agents/types` | List agent types |
|
||||
| `/orchestrator/*` | Queue, trigger, status |
|
||||
### Message Envelope
|
||||
```json
|
||||
{
|
||||
"id": "correlation-uuid",
|
||||
"type": "request|response|notification|error",
|
||||
"action": "action.name",
|
||||
"payload": {},
|
||||
"timestamp": "2026-01-10T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Full API**: See `docs/openapi.yaml`
|
||||
### Request/Response Pattern
|
||||
- Requests include `id` for correlation
|
||||
- Responses include matching `id`
|
||||
- Notifications have no `id` (one-way)
|
||||
|
||||
### Message Actions
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `health.check` | Health check |
|
||||
| `board.list` | List boards |
|
||||
| `board.create` | Create board |
|
||||
| `board.get` | Get board |
|
||||
| `board.update` | Update board |
|
||||
| `board.delete` | Delete board |
|
||||
| `column.list` | List columns |
|
||||
| `column.create` | Create column |
|
||||
| `task.list` | List tasks |
|
||||
| `task.create` | Create task |
|
||||
| `task.get` | Get task |
|
||||
| `task.update` | Update task |
|
||||
| `task.delete` | Delete task |
|
||||
| `task.move` | Move task |
|
||||
| `task.state` | Update state |
|
||||
| `task.subscribe` | Subscribe to task updates |
|
||||
| `task.unsubscribe` | Unsubscribe from task updates |
|
||||
| `agent.list` | List agents |
|
||||
| `agent.launch` | Launch agent |
|
||||
| `agent.status` | Get status |
|
||||
| `agent.logs` | Get logs |
|
||||
| `agent.stop` | Stop agent |
|
||||
| `agent.prompt` | Send prompt |
|
||||
| `agent.cancel` | Cancel agent |
|
||||
| `agent.session` | Get session |
|
||||
| `agent.types` | List types |
|
||||
| `orchestrator.status` | Get status |
|
||||
| `orchestrator.queue` | Get queue |
|
||||
| `orchestrator.trigger` | Trigger task |
|
||||
| `orchestrator.start` | Start task |
|
||||
| `orchestrator.stop` | Stop task |
|
||||
| `orchestrator.prompt` | Send prompt |
|
||||
| `orchestrator.complete` | Complete task |
|
||||
|
||||
### Notification Types (Server → Client)
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `acp.progress` | Agent progress update |
|
||||
| `acp.log` | Agent log message |
|
||||
| `acp.result` | Agent result |
|
||||
| `acp.error` | Agent error |
|
||||
| `acp.status` | Agent status change |
|
||||
| `acp.heartbeat` | Keep-alive |
|
||||
| `task.updated` | Task was updated |
|
||||
| `agent.updated` | Agent status changed |
|
||||
|
||||
### Error Response Format
|
||||
```json
|
||||
{
|
||||
"id": "correlation-uuid",
|
||||
"type": "error",
|
||||
"action": "original.action",
|
||||
"payload": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human readable message",
|
||||
"details": {}
|
||||
},
|
||||
"timestamp": "2026-01-10T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Full API**: See `docs/asyncapi.yaml`
|
||||
|
||||
## Agent Communication Protocol (ACP)
|
||||
|
||||
@@ -198,53 +268,93 @@ Agents use JSON-RPC 2.0 over stdout for bidirectional communication.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### WebSocket Usage Example (JavaScript)
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8080/ws');
|
||||
|
||||
// Send request
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'board.create',
|
||||
payload: { name: 'My Project' }
|
||||
}));
|
||||
|
||||
// Handle messages
|
||||
ws.onmessage = (event) => {
|
||||
const msg = JSON.parse(event.data);
|
||||
if (msg.type === 'response') {
|
||||
console.log('Response:', msg.payload);
|
||||
} else if (msg.type === 'notification') {
|
||||
console.log('Notification:', msg.action, msg.payload);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Create and Launch Agent
|
||||
|
||||
```bash
|
||||
# Create board
|
||||
BOARD_ID=$(curl -s -X POST http://localhost:8080/api/v1/boards \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"My Project"}' | jq -r '.id')
|
||||
```javascript
|
||||
// Create board
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'board.create',
|
||||
payload: { name: 'My Project' }
|
||||
}));
|
||||
|
||||
# Create task
|
||||
TASK_ID=$(curl -s -X POST http://localhost:8080/api/v1/tasks \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"board_id":"'$BOARD_ID'","title":"Fix bug"}' | jq -r '.id')
|
||||
// Create task (after receiving board.create response)
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'task.create',
|
||||
payload: { board_id: BOARD_ID, title: 'Fix bug' }
|
||||
}));
|
||||
|
||||
# Launch agent
|
||||
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":"'"$(cat ~/.augment/session.json | jq -c)"'",
|
||||
"TASK_DESCRIPTION":"Fix the bug"
|
||||
// Launch agent (after receiving task.create response)
|
||||
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: sessionAuth,
|
||||
TASK_DESCRIPTION: 'Fix the bug'
|
||||
}
|
||||
}'
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
### Session Resumption
|
||||
|
||||
```bash
|
||||
# Get session ID from completed task
|
||||
SESSION_ID=$(curl -s http://localhost:8080/api/v1/tasks/$TASK_ID | \
|
||||
jq -r '.metadata.auggie_session_id')
|
||||
```javascript
|
||||
// Get session ID from completed task
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'agent.session',
|
||||
payload: { task_id: TASK_ID }
|
||||
}));
|
||||
|
||||
# Launch with resumption
|
||||
curl -X POST http://localhost:8080/api/v1/agents/launch \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"task_id":"'$NEW_TASK_ID'",
|
||||
"agent_type":"augment-agent",
|
||||
"workspace_path":"/path/to/project",
|
||||
"env":{
|
||||
"AUGMENT_SESSION_AUTH":"'"$(cat ~/.augment/session.json | jq -c)"'",
|
||||
"AUGGIE_SESSION_ID":"'$SESSION_ID'",
|
||||
"TASK_DESCRIPTION":"Follow-up question"
|
||||
// Launch with resumption (after receiving session response)
|
||||
ws.send(JSON.stringify({
|
||||
id: crypto.randomUUID(),
|
||||
type: 'request',
|
||||
action: 'agent.launch',
|
||||
payload: {
|
||||
task_id: NEW_TASK_ID,
|
||||
agent_type: 'augment-agent',
|
||||
workspace_path: '/path/to/project',
|
||||
env: {
|
||||
AUGMENT_SESSION_AUTH: sessionAuth,
|
||||
AUGGIE_SESSION_ID: SESSION_ID,
|
||||
TASK_DESCRIPTION: 'Follow-up question'
|
||||
}
|
||||
}'
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
## Database
|
||||
@@ -306,7 +416,7 @@ make test-web
|
||||
| `Makefile` | Build orchestration |
|
||||
| `ARCHITECTURE.md` | This file |
|
||||
| `AGENTS.md` | Agent protocol details |
|
||||
| `docs/openapi.yaml` | REST API spec |
|
||||
| `docs/asyncapi.yaml` | WebSocket API spec |
|
||||
| `apps/backend/cmd/kandev/main.go` | Entry point |
|
||||
| `apps/backend/internal/agent/registry/defaults.go` | Agent type registry |
|
||||
| `apps/backend/internal/task/repository/sqlite.go` | Database schema |
|
||||
@@ -314,7 +424,7 @@ make test-web
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Update docs when changing API (AGENTS.md + openapi.yaml)
|
||||
1. Update docs when changing API (AGENTS.md + asyncapi.yaml)
|
||||
2. Run tests: `make test`
|
||||
3. Format code: `make fmt`
|
||||
4. Test full stack: `make dev-backend` + `make dev-web`
|
||||
@@ -322,5 +432,5 @@ make test-web
|
||||
---
|
||||
|
||||
**For Agent Protocol Details**: See `AGENTS.md`
|
||||
**For API Reference**: See `docs/openapi.yaml`
|
||||
**For API Reference**: See `docs/asyncapi.yaml`
|
||||
**Last Updated**: 2026-01-10
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
// Package main is the unified entry point for Kandev.
|
||||
// This single binary runs all services together with shared infrastructure.
|
||||
// All communication happens over WebSocket - no REST API.
|
||||
package main
|
||||
|
||||
import (
|
||||
@@ -21,27 +22,30 @@ import (
|
||||
// Event bus
|
||||
"github.com/kandev/kandev/internal/events/bus"
|
||||
|
||||
// WebSocket gateway
|
||||
gateways "github.com/kandev/kandev/internal/gateway/websocket"
|
||||
|
||||
// Agent Manager packages
|
||||
agentapi "github.com/kandev/kandev/internal/agent/api"
|
||||
"github.com/kandev/kandev/internal/agent/credentials"
|
||||
"github.com/kandev/kandev/internal/agent/docker"
|
||||
"github.com/kandev/kandev/internal/agent/lifecycle"
|
||||
"github.com/kandev/kandev/internal/agent/registry"
|
||||
agentwshandlers "github.com/kandev/kandev/internal/agent/wshandlers"
|
||||
|
||||
// Orchestrator packages
|
||||
"github.com/kandev/kandev/internal/orchestrator"
|
||||
orchestratorapi "github.com/kandev/kandev/internal/orchestrator/api"
|
||||
"github.com/kandev/kandev/internal/orchestrator/executor"
|
||||
orchestratorstreaming "github.com/kandev/kandev/internal/orchestrator/streaming"
|
||||
orchestratorwshandlers "github.com/kandev/kandev/internal/orchestrator/wshandlers"
|
||||
|
||||
// Task Service packages
|
||||
taskapi "github.com/kandev/kandev/internal/task/api"
|
||||
"github.com/kandev/kandev/internal/task/repository"
|
||||
taskservice "github.com/kandev/kandev/internal/task/service"
|
||||
taskwshandlers "github.com/kandev/kandev/internal/task/wshandlers"
|
||||
|
||||
// ACP
|
||||
"github.com/kandev/kandev/pkg/acp/protocol"
|
||||
v1 "github.com/kandev/kandev/pkg/api/v1"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
)
|
||||
|
||||
func main() {
|
||||
@@ -177,13 +181,43 @@ func main() {
|
||||
serviceCfg := orchestrator.DefaultServiceConfig()
|
||||
orchestratorSvc := orchestrator.NewService(serviceCfg, eventBus, nil, agentManagerClient, taskRepoAdapter, log)
|
||||
|
||||
// WebSocket hub for ACP streaming
|
||||
wsHub := orchestratorstreaming.NewHub(log)
|
||||
go wsHub.Run(ctx)
|
||||
// ============================================
|
||||
// WEBSOCKET GATEWAY (All communication via WebSocket)
|
||||
// ============================================
|
||||
log.Info("Initializing WebSocket Gateway...")
|
||||
|
||||
// Wire ACP handler to broadcast to WebSocket clients
|
||||
// Create the unified WebSocket gateway
|
||||
gateway := gateways.NewGateway(log)
|
||||
|
||||
// Register WebSocket message handlers for each service
|
||||
taskWSHandlers := taskwshandlers.NewHandlers(taskSvc, log)
|
||||
taskWSHandlers.RegisterHandlers(gateway.Dispatcher)
|
||||
log.Info("Registered Task Service WebSocket handlers")
|
||||
|
||||
orchestratorWSHandlers := orchestratorwshandlers.NewHandlers(orchestratorSvc, log)
|
||||
orchestratorWSHandlers.RegisterHandlers(gateway.Dispatcher)
|
||||
log.Info("Registered Orchestrator WebSocket handlers")
|
||||
|
||||
if lifecycleMgr != nil && agentRegistry != nil {
|
||||
agentWSHandlers := agentwshandlers.NewHandlers(lifecycleMgr, agentRegistry, log)
|
||||
agentWSHandlers.RegisterHandlers(gateway.Dispatcher)
|
||||
log.Info("Registered Agent Manager WebSocket handlers")
|
||||
}
|
||||
|
||||
// Start the WebSocket hub
|
||||
go gateway.Hub.Run(ctx)
|
||||
|
||||
// Wire ACP handler to broadcast to WebSocket clients as notifications
|
||||
orchestratorSvc.RegisterACPHandler(func(taskID string, msg *protocol.Message) {
|
||||
wsHub.Broadcast(taskID, msg)
|
||||
// Convert ACP message to WebSocket notification
|
||||
action := "acp." + string(msg.Type)
|
||||
notification, _ := ws.NewNotification(action, map[string]interface{}{
|
||||
"task_id": taskID,
|
||||
"type": msg.Type,
|
||||
"data": msg.Data,
|
||||
"timestamp": msg.Timestamp,
|
||||
})
|
||||
gateway.Hub.BroadcastToTask(taskID, notification)
|
||||
})
|
||||
|
||||
// Wire ACP handler to extract session_id from session_info messages and store in task metadata
|
||||
@@ -219,42 +253,24 @@ func main() {
|
||||
log.Info("Orchestrator initialized")
|
||||
|
||||
// ============================================
|
||||
// HTTP SERVER
|
||||
// HTTP SERVER (WebSocket endpoint only)
|
||||
// ============================================
|
||||
if cfg.Logging.Level != "debug" {
|
||||
gin.SetMode(gin.ReleaseMode)
|
||||
}
|
||||
router := gin.New()
|
||||
router.Use(gin.Recovery())
|
||||
router.Use(orchestratorapi.RequestLogger(log))
|
||||
router.Use(orchestratorapi.CORS())
|
||||
router.Use(corsMiddleware())
|
||||
|
||||
// API v1 routes
|
||||
v1Group := router.Group("/api/v1")
|
||||
// WebSocket endpoint - the only way to communicate with the backend
|
||||
gateway.SetupRoutes(router)
|
||||
|
||||
// Task Service routes
|
||||
taskapi.SetupRoutes(v1Group, taskSvc, log)
|
||||
|
||||
// Orchestrator routes
|
||||
orchGroup := v1Group.Group("/orchestrator")
|
||||
orchestratorapi.SetupRoutes(orchGroup, orchestratorSvc, log)
|
||||
|
||||
// WebSocket routes for orchestrator
|
||||
wsHandler := orchestratorstreaming.NewWSHandler(wsHub, orchestratorSvc, log)
|
||||
orchestratorstreaming.SetupWebSocketRoutes(orchGroup, wsHandler)
|
||||
|
||||
// Agent Manager routes (if available)
|
||||
if lifecycleMgr != nil && agentRegistry != nil && dockerClient != nil {
|
||||
// Note: ACP is now handled via agentctl inside containers, so we pass nil for the ACP manager
|
||||
agentapi.SetupRoutes(v1Group, lifecycleMgr, agentRegistry, dockerClient, nil, log)
|
||||
}
|
||||
|
||||
// Health check
|
||||
// Health check (simple HTTP for load balancers/monitoring)
|
||||
router.GET("/health", func(c *gin.Context) {
|
||||
c.JSON(http.StatusOK, gin.H{
|
||||
"status": "ok",
|
||||
"service": "kandev",
|
||||
"mode": "unified",
|
||||
"mode": "websocket-only",
|
||||
})
|
||||
})
|
||||
|
||||
@@ -272,17 +288,15 @@ func main() {
|
||||
|
||||
// Start server
|
||||
go func() {
|
||||
log.Info("HTTP server listening", zap.Int("port", port))
|
||||
log.Info("WebSocket server listening", zap.Int("port", port))
|
||||
if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
|
||||
log.Fatal("Failed to start HTTP server", zap.Error(err))
|
||||
log.Fatal("Failed to start server", zap.Error(err))
|
||||
}
|
||||
}()
|
||||
|
||||
// Print routes summary
|
||||
log.Info("Routes configured",
|
||||
zap.String("tasks", "/api/v1/tasks, /api/v1/boards"),
|
||||
zap.String("orchestrator", "/api/v1/orchestrator"),
|
||||
zap.String("agents", "/api/v1/agents"),
|
||||
log.Info("WebSocket-only API configured",
|
||||
zap.String("websocket", "/ws"),
|
||||
zap.String("health", "/health"),
|
||||
)
|
||||
|
||||
@@ -427,3 +441,20 @@ func (a *lifecycleAdapter) ListAgentTypes(ctx context.Context) ([]*v1.AgentType,
|
||||
func (a *lifecycleAdapter) PromptAgent(ctx context.Context, agentInstanceID string, prompt string) error {
|
||||
return a.mgr.PromptAgent(ctx, agentInstanceID, prompt)
|
||||
}
|
||||
|
||||
// corsMiddleware returns a CORS middleware for WebSocket connections
|
||||
func corsMiddleware() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
c.Header("Access-Control-Allow-Origin", "*")
|
||||
c.Header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
|
||||
c.Header("Access-Control-Allow-Headers", "Origin, Content-Type, Authorization, Upgrade, Connection, Sec-WebSocket-Key, Sec-WebSocket-Version, Sec-WebSocket-Protocol")
|
||||
c.Header("Access-Control-Allow-Credentials", "true")
|
||||
|
||||
if c.Request.Method == "OPTIONS" {
|
||||
c.AbortWithStatus(http.StatusNoContent)
|
||||
return
|
||||
}
|
||||
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,290 @@
|
||||
// Package wshandlers provides WebSocket message handlers for the agent manager.
|
||||
package wshandlers
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/kandev/kandev/internal/agent/lifecycle"
|
||||
"github.com/kandev/kandev/internal/agent/registry"
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// Handlers contains WebSocket handlers for the agent API
|
||||
type Handlers struct {
|
||||
lifecycle *lifecycle.Manager
|
||||
registry *registry.Registry
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewHandlers creates a new WebSocket handlers instance
|
||||
func NewHandlers(lm *lifecycle.Manager, reg *registry.Registry, log *logger.Logger) *Handlers {
|
||||
return &Handlers{
|
||||
lifecycle: lm,
|
||||
registry: reg,
|
||||
logger: log.WithFields(zap.String("component", "agent-ws-handlers")),
|
||||
}
|
||||
}
|
||||
|
||||
// RegisterHandlers registers all agent handlers with the dispatcher
|
||||
func (h *Handlers) RegisterHandlers(d *ws.Dispatcher) {
|
||||
d.RegisterFunc(ws.ActionAgentList, h.ListAgents)
|
||||
d.RegisterFunc(ws.ActionAgentLaunch, h.LaunchAgent)
|
||||
d.RegisterFunc(ws.ActionAgentStatus, h.GetAgentStatus)
|
||||
d.RegisterFunc(ws.ActionAgentLogs, h.GetAgentLogs)
|
||||
d.RegisterFunc(ws.ActionAgentStop, h.StopAgent)
|
||||
d.RegisterFunc(ws.ActionAgentTypes, h.ListAgentTypes)
|
||||
}
|
||||
|
||||
// AgentResponse represents an agent instance
|
||||
type AgentResponse struct {
|
||||
ID string `json:"id"`
|
||||
TaskID string `json:"task_id"`
|
||||
AgentType string `json:"agent_type"`
|
||||
ContainerID string `json:"container_id,omitempty"`
|
||||
Status string `json:"status"`
|
||||
Progress int `json:"progress"`
|
||||
StartedAt string `json:"started_at"`
|
||||
FinishedAt string `json:"finished_at,omitempty"`
|
||||
ExitCode *int `json:"exit_code,omitempty"`
|
||||
Error string `json:"error,omitempty"`
|
||||
Metadata map[string]string `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// ListAgentsResponse is the response for agent.list
|
||||
type ListAgentsResponse struct {
|
||||
Agents []AgentResponse `json:"agents"`
|
||||
Total int `json:"total"`
|
||||
}
|
||||
|
||||
// ListAgents handles agent.list action
|
||||
func (h *Handlers) ListAgents(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
if h.lifecycle == nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Agent manager not available", nil)
|
||||
}
|
||||
|
||||
agents := h.lifecycle.ListInstances()
|
||||
resp := ListAgentsResponse{
|
||||
Agents: make([]AgentResponse, 0, len(agents)),
|
||||
Total: len(agents),
|
||||
}
|
||||
|
||||
for _, a := range agents {
|
||||
agent := AgentResponse{
|
||||
ID: a.ID,
|
||||
TaskID: a.TaskID,
|
||||
AgentType: a.AgentType,
|
||||
ContainerID: a.ContainerID,
|
||||
Status: string(a.Status),
|
||||
Progress: a.Progress,
|
||||
StartedAt: a.StartedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
if a.FinishedAt != nil && !a.FinishedAt.IsZero() {
|
||||
agent.FinishedAt = a.FinishedAt.Format("2006-01-02T15:04:05Z")
|
||||
}
|
||||
if a.ExitCode != nil {
|
||||
agent.ExitCode = a.ExitCode
|
||||
}
|
||||
if a.ErrorMessage != "" {
|
||||
agent.Error = a.ErrorMessage
|
||||
}
|
||||
resp.Agents = append(resp.Agents, agent)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// LaunchAgentRequest is the payload for agent.launch
|
||||
type LaunchAgentRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
AgentType string `json:"agent_type"`
|
||||
WorkspacePath string `json:"workspace_path"`
|
||||
Env map[string]string `json:"env,omitempty"`
|
||||
}
|
||||
|
||||
// LaunchAgent handles agent.launch action
|
||||
func (h *Handlers) LaunchAgent(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req LaunchAgentRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
}
|
||||
if req.AgentType == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "agent_type is required", nil)
|
||||
}
|
||||
if req.WorkspacePath == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "workspace_path is required", nil)
|
||||
}
|
||||
|
||||
if h.lifecycle == nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Agent manager not available", nil)
|
||||
}
|
||||
|
||||
launchReq := &lifecycle.LaunchRequest{
|
||||
TaskID: req.TaskID,
|
||||
AgentType: req.AgentType,
|
||||
WorkspacePath: req.WorkspacePath,
|
||||
Env: req.Env,
|
||||
}
|
||||
|
||||
instance, err := h.lifecycle.Launch(ctx, launchReq)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to launch agent",
|
||||
zap.String("task_id", req.TaskID),
|
||||
zap.String("agent_type", req.AgentType),
|
||||
zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to launch agent: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"success": true,
|
||||
"agent_id": instance.ID,
|
||||
"task_id": req.TaskID,
|
||||
})
|
||||
}
|
||||
|
||||
// AgentIDRequest is a common request with just agent_id
|
||||
type AgentIDRequest struct {
|
||||
AgentID string `json:"agent_id"`
|
||||
}
|
||||
|
||||
// GetAgentStatus handles agent.status action
|
||||
func (h *Handlers) GetAgentStatus(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req AgentIDRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.AgentID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "agent_id is required", nil)
|
||||
}
|
||||
|
||||
if h.lifecycle == nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Agent manager not available", nil)
|
||||
}
|
||||
|
||||
agent, found := h.lifecycle.GetInstance(req.AgentID)
|
||||
if !found {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeNotFound, "Agent not found", nil)
|
||||
}
|
||||
|
||||
resp := AgentResponse{
|
||||
ID: agent.ID,
|
||||
TaskID: agent.TaskID,
|
||||
AgentType: agent.AgentType,
|
||||
ContainerID: agent.ContainerID,
|
||||
Status: string(agent.Status),
|
||||
Progress: agent.Progress,
|
||||
StartedAt: agent.StartedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
if agent.FinishedAt != nil && !agent.FinishedAt.IsZero() {
|
||||
resp.FinishedAt = agent.FinishedAt.Format("2006-01-02T15:04:05Z")
|
||||
}
|
||||
if agent.ExitCode != nil {
|
||||
resp.ExitCode = agent.ExitCode
|
||||
}
|
||||
if agent.ErrorMessage != "" {
|
||||
resp.Error = agent.ErrorMessage
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// GetAgentLogs handles agent.logs action
|
||||
func (h *Handlers) GetAgentLogs(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req AgentIDRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.AgentID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "agent_id is required", nil)
|
||||
}
|
||||
|
||||
if h.lifecycle == nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Agent manager not available", nil)
|
||||
}
|
||||
|
||||
_, found := h.lifecycle.GetInstance(req.AgentID)
|
||||
if !found {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeNotFound, "Agent not found", nil)
|
||||
}
|
||||
|
||||
// Note: Log retrieval requires Docker client access which is not available in wshandlers
|
||||
// This handler returns a stub response; full log retrieval should use the HTTP API
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"agent_id": req.AgentID,
|
||||
"logs": []string{},
|
||||
"message": "Use HTTP API for full log retrieval",
|
||||
})
|
||||
}
|
||||
|
||||
// StopAgent handles agent.stop action
|
||||
func (h *Handlers) StopAgent(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req AgentIDRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.AgentID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "agent_id is required", nil)
|
||||
}
|
||||
|
||||
if h.lifecycle == nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Agent manager not available", nil)
|
||||
}
|
||||
|
||||
if err := h.lifecycle.StopAgent(ctx, req.AgentID, false); err != nil {
|
||||
h.logger.Error("failed to stop agent", zap.String("agent_id", req.AgentID), zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to stop agent: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]bool{"success": true})
|
||||
}
|
||||
|
||||
// AgentTypeResponse represents an agent type
|
||||
type AgentTypeResponse struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Image string `json:"image"`
|
||||
Capabilities []string `json:"capabilities,omitempty"`
|
||||
Enabled bool `json:"enabled"`
|
||||
}
|
||||
|
||||
// ListAgentTypesResponse is the response for agent.types
|
||||
type ListAgentTypesResponse struct {
|
||||
Types []AgentTypeResponse `json:"types"`
|
||||
Total int `json:"total"`
|
||||
}
|
||||
|
||||
// ListAgentTypes handles agent.types action
|
||||
func (h *Handlers) ListAgentTypes(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
if h.registry == nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Registry not available", nil)
|
||||
}
|
||||
|
||||
types := h.registry.List()
|
||||
resp := ListAgentTypesResponse{
|
||||
Types: make([]AgentTypeResponse, 0, len(types)),
|
||||
Total: len(types),
|
||||
}
|
||||
|
||||
for _, t := range types {
|
||||
resp.Types = append(resp.Types, AgentTypeResponse{
|
||||
ID: t.ID,
|
||||
Name: t.Name,
|
||||
Description: t.Description,
|
||||
Image: t.Image,
|
||||
Capabilities: t.Capabilities,
|
||||
Enabled: t.Enabled,
|
||||
})
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
@@ -0,0 +1,235 @@
|
||||
package websocket
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/gorilla/websocket"
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
const (
|
||||
// Time allowed to write a message to the peer
|
||||
writeWait = 10 * time.Second
|
||||
|
||||
// Time allowed to read the next pong message from the peer
|
||||
pongWait = 60 * time.Second
|
||||
|
||||
// Send pings to peer with this period (must be less than pongWait)
|
||||
pingPeriod = (pongWait * 9) / 10
|
||||
|
||||
// Maximum message size allowed from peer
|
||||
maxMessageSize = 512 * 1024 // 512KB
|
||||
)
|
||||
|
||||
// Client represents a single WebSocket connection
|
||||
type Client struct {
|
||||
ID string
|
||||
conn *websocket.Conn
|
||||
hub *Hub
|
||||
send chan []byte
|
||||
subscriptions map[string]bool // Task IDs this client is subscribed to
|
||||
mu sync.RWMutex
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewClient creates a new WebSocket client
|
||||
func NewClient(id string, conn *websocket.Conn, hub *Hub, log *logger.Logger) *Client {
|
||||
return &Client{
|
||||
ID: id,
|
||||
conn: conn,
|
||||
hub: hub,
|
||||
send: make(chan []byte, 256),
|
||||
subscriptions: make(map[string]bool),
|
||||
logger: log.WithFields(zap.String("client_id", id)),
|
||||
}
|
||||
}
|
||||
|
||||
// ReadPump pumps messages from the WebSocket connection to the hub
|
||||
func (c *Client) ReadPump(ctx context.Context) {
|
||||
defer func() {
|
||||
c.hub.Unregister(c)
|
||||
c.conn.Close()
|
||||
}()
|
||||
|
||||
c.conn.SetReadLimit(maxMessageSize)
|
||||
c.conn.SetReadDeadline(time.Now().Add(pongWait))
|
||||
c.conn.SetPongHandler(func(string) error {
|
||||
c.conn.SetReadDeadline(time.Now().Add(pongWait))
|
||||
return nil
|
||||
})
|
||||
|
||||
for {
|
||||
_, message, err := c.conn.ReadMessage()
|
||||
if err != nil {
|
||||
if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
|
||||
c.logger.Error("WebSocket read error", zap.Error(err))
|
||||
}
|
||||
break
|
||||
}
|
||||
|
||||
// Parse the message
|
||||
var msg ws.Message
|
||||
if err := json.Unmarshal(message, &msg); err != nil {
|
||||
c.logger.Error("Failed to parse message", zap.Error(err))
|
||||
c.sendError("", "", ws.ErrorCodeBadRequest, "Invalid message format", nil)
|
||||
continue
|
||||
}
|
||||
|
||||
// Process the message
|
||||
c.handleMessage(ctx, &msg)
|
||||
}
|
||||
}
|
||||
|
||||
// handleMessage processes an incoming message
|
||||
func (c *Client) handleMessage(ctx context.Context, msg *ws.Message) {
|
||||
c.logger.Debug("Received message",
|
||||
zap.String("action", msg.Action),
|
||||
zap.String("id", msg.ID))
|
||||
|
||||
// Handle subscription actions specially (they need access to the client)
|
||||
switch msg.Action {
|
||||
case ws.ActionTaskSubscribe:
|
||||
c.handleSubscribe(msg)
|
||||
return
|
||||
case ws.ActionTaskUnsubscribe:
|
||||
c.handleUnsubscribe(msg)
|
||||
return
|
||||
}
|
||||
|
||||
// Dispatch to handler
|
||||
response, err := c.hub.dispatcher.Dispatch(ctx, msg)
|
||||
if err != nil {
|
||||
c.logger.Error("Handler error",
|
||||
zap.String("action", msg.Action),
|
||||
zap.Error(err))
|
||||
c.sendError(msg.ID, msg.Action, ws.ErrorCodeInternalError, err.Error(), nil)
|
||||
return
|
||||
}
|
||||
|
||||
if response != nil {
|
||||
c.sendMessage(response)
|
||||
}
|
||||
}
|
||||
|
||||
// SubscribeRequest is the payload for task.subscribe
|
||||
type SubscribeRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
}
|
||||
|
||||
// handleSubscribe handles task.subscribe action
|
||||
func (c *Client) handleSubscribe(msg *ws.Message) {
|
||||
var req SubscribeRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
c.sendError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
return
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
c.sendError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
return
|
||||
}
|
||||
|
||||
c.hub.SubscribeToTask(c, req.TaskID)
|
||||
|
||||
resp, _ := ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"success": true,
|
||||
"task_id": req.TaskID,
|
||||
})
|
||||
c.sendMessage(resp)
|
||||
}
|
||||
|
||||
// handleUnsubscribe handles task.unsubscribe action
|
||||
func (c *Client) handleUnsubscribe(msg *ws.Message) {
|
||||
var req SubscribeRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
c.sendError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
return
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
c.sendError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
return
|
||||
}
|
||||
|
||||
c.hub.UnsubscribeFromTask(c, req.TaskID)
|
||||
|
||||
resp, _ := ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"success": true,
|
||||
"task_id": req.TaskID,
|
||||
})
|
||||
c.sendMessage(resp)
|
||||
}
|
||||
|
||||
// sendMessage sends a message to the client
|
||||
func (c *Client) sendMessage(msg *ws.Message) {
|
||||
data, err := json.Marshal(msg)
|
||||
if err != nil {
|
||||
c.logger.Error("Failed to marshal message", zap.Error(err))
|
||||
return
|
||||
}
|
||||
|
||||
select {
|
||||
case c.send <- data:
|
||||
default:
|
||||
c.logger.Warn("Client send buffer full")
|
||||
}
|
||||
}
|
||||
|
||||
// sendError sends an error message to the client
|
||||
func (c *Client) sendError(id, action, code, message string, details map[string]interface{}) {
|
||||
msg, err := ws.NewError(id, action, code, message, details)
|
||||
if err != nil {
|
||||
c.logger.Error("Failed to create error message", zap.Error(err))
|
||||
return
|
||||
}
|
||||
c.sendMessage(msg)
|
||||
}
|
||||
|
||||
// WritePump pumps messages from the hub to the WebSocket connection
|
||||
func (c *Client) WritePump() {
|
||||
ticker := time.NewTicker(pingPeriod)
|
||||
defer func() {
|
||||
ticker.Stop()
|
||||
c.conn.Close()
|
||||
}()
|
||||
|
||||
for {
|
||||
select {
|
||||
case message, ok := <-c.send:
|
||||
c.conn.SetWriteDeadline(time.Now().Add(writeWait))
|
||||
if !ok {
|
||||
// Hub closed the channel
|
||||
c.conn.WriteMessage(websocket.CloseMessage, []byte{})
|
||||
return
|
||||
}
|
||||
|
||||
w, err := c.conn.NextWriter(websocket.TextMessage)
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
w.Write(message)
|
||||
|
||||
// Batch additional queued messages
|
||||
n := len(c.send)
|
||||
for i := 0; i < n; i++ {
|
||||
w.Write([]byte{'\n'})
|
||||
w.Write(<-c.send)
|
||||
}
|
||||
|
||||
if err := w.Close(); err != nil {
|
||||
return
|
||||
}
|
||||
|
||||
case <-ticker.C:
|
||||
c.conn.SetWriteDeadline(time.Now().Add(writeWait))
|
||||
if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
|
||||
return
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
package websocket
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/http"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/google/uuid"
|
||||
gorillaws "github.com/gorilla/websocket"
|
||||
"go.uber.org/zap"
|
||||
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
)
|
||||
|
||||
var upgrader = gorillaws.Upgrader{
|
||||
ReadBufferSize: 1024,
|
||||
WriteBufferSize: 1024,
|
||||
CheckOrigin: func(r *http.Request) bool {
|
||||
// TODO: In production, validate origin
|
||||
return true
|
||||
},
|
||||
}
|
||||
|
||||
// Handler handles WebSocket connections
|
||||
type Handler struct {
|
||||
hub *Hub
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewHandler creates a new WebSocket handler
|
||||
func NewHandler(hub *Hub, log *logger.Logger) *Handler {
|
||||
return &Handler{
|
||||
hub: hub,
|
||||
logger: log.WithFields(zap.String("component", "ws_handler")),
|
||||
}
|
||||
}
|
||||
|
||||
// HandleConnection upgrades HTTP to WebSocket and handles messages
|
||||
func (h *Handler) HandleConnection(c *gin.Context) {
|
||||
// Validate token (optional for now)
|
||||
token := c.Query("token")
|
||||
if token == "" {
|
||||
token = c.GetHeader("Authorization")
|
||||
}
|
||||
// TODO: Implement proper JWT validation
|
||||
_ = token
|
||||
|
||||
// Upgrade connection to WebSocket
|
||||
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
|
||||
if err != nil {
|
||||
h.logger.Error("Failed to upgrade connection", zap.Error(err))
|
||||
return
|
||||
}
|
||||
|
||||
// Create a unique client ID
|
||||
clientID := uuid.New().String()
|
||||
|
||||
h.logger.Info("WebSocket connection established",
|
||||
zap.String("client_id", clientID),
|
||||
zap.String("remote_addr", c.Request.RemoteAddr),
|
||||
)
|
||||
|
||||
// Create client and register with hub
|
||||
client := NewClient(clientID, conn, h.hub, h.logger)
|
||||
|
||||
// Register client with hub
|
||||
h.hub.Register(client)
|
||||
|
||||
// Start read and write pumps
|
||||
go client.WritePump()
|
||||
client.ReadPump(c.Request.Context())
|
||||
}
|
||||
|
||||
// SetupRoutes adds the WebSocket route to the router
|
||||
func SetupRoutes(router *gin.Engine, hub *Hub, log *logger.Logger) {
|
||||
handler := NewHandler(hub, log)
|
||||
|
||||
// Main WebSocket endpoint
|
||||
router.GET("/ws", handler.HandleConnection)
|
||||
}
|
||||
|
||||
// RegisterHealthHandler registers the health check handler
|
||||
func RegisterHealthHandler(d *ws.Dispatcher) {
|
||||
d.RegisterFunc(ws.ActionHealthCheck, func(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"status": "ok",
|
||||
"service": "kandev",
|
||||
"mode": "unified",
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
// Package websocket provides a unified WebSocket gateway for all API operations.
|
||||
package websocket
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"sync"
|
||||
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// Hub manages all WebSocket client connections
|
||||
type Hub struct {
|
||||
// All registered clients
|
||||
clients map[*Client]bool
|
||||
|
||||
// Clients subscribed to specific tasks (for ACP notifications)
|
||||
taskSubscribers map[string]map[*Client]bool
|
||||
|
||||
// Channels for client management
|
||||
register chan *Client
|
||||
unregister chan *Client
|
||||
|
||||
// Channel for broadcasting notifications
|
||||
broadcast chan *ws.Message
|
||||
|
||||
// Message dispatcher
|
||||
dispatcher *ws.Dispatcher
|
||||
|
||||
mu sync.RWMutex
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewHub creates a new WebSocket hub
|
||||
func NewHub(dispatcher *ws.Dispatcher, log *logger.Logger) *Hub {
|
||||
return &Hub{
|
||||
clients: make(map[*Client]bool),
|
||||
taskSubscribers: make(map[string]map[*Client]bool),
|
||||
register: make(chan *Client),
|
||||
unregister: make(chan *Client),
|
||||
broadcast: make(chan *ws.Message, 256),
|
||||
dispatcher: dispatcher,
|
||||
logger: log.WithFields(zap.String("component", "ws_hub")),
|
||||
}
|
||||
}
|
||||
|
||||
// Run starts the hub's main processing loop
|
||||
func (h *Hub) Run(ctx context.Context) {
|
||||
h.logger.Info("WebSocket hub started")
|
||||
defer h.logger.Info("WebSocket hub stopped")
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
h.closeAllClients()
|
||||
return
|
||||
|
||||
case client := <-h.register:
|
||||
h.mu.Lock()
|
||||
h.clients[client] = true
|
||||
h.mu.Unlock()
|
||||
h.logger.Debug("Client registered", zap.String("client_id", client.ID))
|
||||
|
||||
case client := <-h.unregister:
|
||||
h.removeClient(client)
|
||||
|
||||
case msg := <-h.broadcast:
|
||||
h.broadcastMessage(msg)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// closeAllClients closes all client connections
|
||||
func (h *Hub) closeAllClients() {
|
||||
h.mu.Lock()
|
||||
defer h.mu.Unlock()
|
||||
|
||||
for client := range h.clients {
|
||||
close(client.send)
|
||||
delete(h.clients, client)
|
||||
}
|
||||
h.taskSubscribers = make(map[string]map[*Client]bool)
|
||||
}
|
||||
|
||||
// removeClient removes a client from the hub
|
||||
func (h *Hub) removeClient(client *Client) {
|
||||
h.mu.Lock()
|
||||
defer h.mu.Unlock()
|
||||
|
||||
if _, ok := h.clients[client]; ok {
|
||||
delete(h.clients, client)
|
||||
close(client.send)
|
||||
|
||||
// Remove from all task subscriptions
|
||||
for taskID := range client.subscriptions {
|
||||
if clients, ok := h.taskSubscribers[taskID]; ok {
|
||||
delete(clients, client)
|
||||
if len(clients) == 0 {
|
||||
delete(h.taskSubscribers, taskID)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
h.logger.Debug("Client unregistered", zap.String("client_id", client.ID))
|
||||
}
|
||||
|
||||
// broadcastMessage sends a message to relevant clients
|
||||
func (h *Hub) broadcastMessage(msg *ws.Message) {
|
||||
data, err := json.Marshal(msg)
|
||||
if err != nil {
|
||||
h.logger.Error("Failed to marshal broadcast message", zap.Error(err))
|
||||
return
|
||||
}
|
||||
|
||||
h.mu.RLock()
|
||||
defer h.mu.RUnlock()
|
||||
|
||||
// For now, broadcast to all clients
|
||||
// TODO: Add topic-based routing for task-specific notifications
|
||||
for client := range h.clients {
|
||||
select {
|
||||
case client.send <- data:
|
||||
default:
|
||||
// Client buffer full, will be cleaned up by write pump
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Register adds a client to the hub
|
||||
func (h *Hub) Register(client *Client) {
|
||||
h.register <- client
|
||||
}
|
||||
|
||||
// Unregister removes a client from the hub
|
||||
func (h *Hub) Unregister(client *Client) {
|
||||
h.unregister <- client
|
||||
}
|
||||
|
||||
// Broadcast sends a notification to all connected clients
|
||||
func (h *Hub) Broadcast(msg *ws.Message) {
|
||||
h.broadcast <- msg
|
||||
}
|
||||
|
||||
// BroadcastToTask sends a notification to clients subscribed to a specific task
|
||||
func (h *Hub) BroadcastToTask(taskID string, msg *ws.Message) {
|
||||
data, err := json.Marshal(msg)
|
||||
if err != nil {
|
||||
h.logger.Error("Failed to marshal message", zap.Error(err))
|
||||
return
|
||||
}
|
||||
|
||||
h.mu.RLock()
|
||||
clients := h.taskSubscribers[taskID]
|
||||
h.mu.RUnlock()
|
||||
|
||||
for client := range clients {
|
||||
select {
|
||||
case client.send <- data:
|
||||
default:
|
||||
// Buffer full
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// SubscribeToTask subscribes a client to task notifications
|
||||
func (h *Hub) SubscribeToTask(client *Client, taskID string) {
|
||||
h.mu.Lock()
|
||||
defer h.mu.Unlock()
|
||||
|
||||
if _, ok := h.taskSubscribers[taskID]; !ok {
|
||||
h.taskSubscribers[taskID] = make(map[*Client]bool)
|
||||
}
|
||||
h.taskSubscribers[taskID][client] = true
|
||||
client.subscriptions[taskID] = true
|
||||
|
||||
h.logger.Debug("Client subscribed to task",
|
||||
zap.String("client_id", client.ID),
|
||||
zap.String("task_id", taskID))
|
||||
}
|
||||
|
||||
// UnsubscribeFromTask unsubscribes a client from task notifications
|
||||
func (h *Hub) UnsubscribeFromTask(client *Client, taskID string) {
|
||||
h.mu.Lock()
|
||||
defer h.mu.Unlock()
|
||||
|
||||
delete(client.subscriptions, taskID)
|
||||
if clients, ok := h.taskSubscribers[taskID]; ok {
|
||||
delete(clients, client)
|
||||
if len(clients) == 0 {
|
||||
delete(h.taskSubscribers, taskID)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// GetClientCount returns the number of connected clients
|
||||
func (h *Hub) GetClientCount() int {
|
||||
h.mu.RLock()
|
||||
defer h.mu.RUnlock()
|
||||
return len(h.clients)
|
||||
}
|
||||
|
||||
// GetDispatcher returns the message dispatcher
|
||||
func (h *Hub) GetDispatcher() *ws.Dispatcher {
|
||||
return h.dispatcher
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
package websocket
|
||||
|
||||
import (
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
)
|
||||
|
||||
// Gateway represents the unified WebSocket gateway
|
||||
type Gateway struct {
|
||||
Hub *Hub
|
||||
Dispatcher *ws.Dispatcher
|
||||
Handler *Handler
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewGateway creates a new WebSocket gateway with all components initialized
|
||||
func NewGateway(log *logger.Logger) *Gateway {
|
||||
dispatcher := ws.NewDispatcher()
|
||||
hub := NewHub(dispatcher, log)
|
||||
handler := NewHandler(hub, log)
|
||||
|
||||
// Register health check handler
|
||||
RegisterHealthHandler(dispatcher)
|
||||
|
||||
return &Gateway{
|
||||
Hub: hub,
|
||||
Dispatcher: dispatcher,
|
||||
Handler: handler,
|
||||
logger: log,
|
||||
}
|
||||
}
|
||||
|
||||
// SetupRoutes adds the WebSocket routes to the Gin engine
|
||||
func (g *Gateway) SetupRoutes(router *gin.Engine) {
|
||||
router.GET("/ws", g.Handler.HandleConnection)
|
||||
}
|
||||
|
||||
@@ -0,0 +1,218 @@
|
||||
// Package wshandlers provides WebSocket message handlers for the orchestrator.
|
||||
package wshandlers
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
"github.com/kandev/kandev/internal/orchestrator"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// Handlers contains WebSocket handlers for the orchestrator API
|
||||
type Handlers struct {
|
||||
service *orchestrator.Service
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewHandlers creates a new WebSocket handlers instance
|
||||
func NewHandlers(svc *orchestrator.Service, log *logger.Logger) *Handlers {
|
||||
return &Handlers{
|
||||
service: svc,
|
||||
logger: log.WithFields(zap.String("component", "orchestrator-ws-handlers")),
|
||||
}
|
||||
}
|
||||
|
||||
// RegisterHandlers registers all orchestrator handlers with the dispatcher
|
||||
func (h *Handlers) RegisterHandlers(d *ws.Dispatcher) {
|
||||
d.RegisterFunc(ws.ActionOrchestratorStatus, h.GetStatus)
|
||||
d.RegisterFunc(ws.ActionOrchestratorQueue, h.GetQueue)
|
||||
d.RegisterFunc(ws.ActionOrchestratorTrigger, h.TriggerTask)
|
||||
d.RegisterFunc(ws.ActionOrchestratorStart, h.StartTask)
|
||||
d.RegisterFunc(ws.ActionOrchestratorStop, h.StopTask)
|
||||
d.RegisterFunc(ws.ActionOrchestratorPrompt, h.PromptTask)
|
||||
d.RegisterFunc(ws.ActionOrchestratorComplete, h.CompleteTask)
|
||||
}
|
||||
|
||||
// GetStatus handles orchestrator.status action
|
||||
func (h *Handlers) GetStatus(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
status := h.service.GetStatus()
|
||||
return ws.NewResponse(msg.ID, msg.Action, status)
|
||||
}
|
||||
|
||||
// QueuedTaskResponse represents a task in the queue
|
||||
type QueuedTaskResponse struct {
|
||||
TaskID string `json:"task_id"`
|
||||
Priority int `json:"priority"`
|
||||
QueuedAt string `json:"queued_at"`
|
||||
}
|
||||
|
||||
// QueueResponse is the response for orchestrator.queue
|
||||
type QueueResponse struct {
|
||||
Tasks []QueuedTaskResponse `json:"tasks"`
|
||||
Total int `json:"total"`
|
||||
}
|
||||
|
||||
// GetQueue handles orchestrator.queue action
|
||||
func (h *Handlers) GetQueue(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
queuedTasks := h.service.GetQueuedTasks()
|
||||
|
||||
tasks := make([]QueuedTaskResponse, 0, len(queuedTasks))
|
||||
for _, qt := range queuedTasks {
|
||||
tasks = append(tasks, QueuedTaskResponse{
|
||||
TaskID: qt.TaskID,
|
||||
Priority: qt.Priority,
|
||||
QueuedAt: qt.QueuedAt.Format("2006-01-02T15:04:05Z"),
|
||||
})
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, QueueResponse{
|
||||
Tasks: tasks,
|
||||
Total: len(tasks),
|
||||
})
|
||||
}
|
||||
|
||||
// TriggerTaskRequest is the payload for orchestrator.trigger
|
||||
type TriggerTaskRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
}
|
||||
|
||||
// TriggerTask handles orchestrator.trigger action
|
||||
func (h *Handlers) TriggerTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req TriggerTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
}
|
||||
|
||||
// For now just log - the service would need task details
|
||||
h.logger.Info("Triggering task", zap.String("task_id", req.TaskID))
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"success": true,
|
||||
"message": "Task triggered",
|
||||
"task_id": req.TaskID,
|
||||
})
|
||||
}
|
||||
|
||||
// StartTaskRequest is the payload for orchestrator.start
|
||||
type StartTaskRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
AgentType string `json:"agent_type,omitempty"`
|
||||
Priority int `json:"priority,omitempty"`
|
||||
}
|
||||
|
||||
// StartTask handles orchestrator.start action
|
||||
func (h *Handlers) StartTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req StartTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
}
|
||||
|
||||
execution, err := h.service.StartTask(ctx, req.TaskID, req.AgentType, req.Priority)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to start task", zap.String("task_id", req.TaskID), zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to start task: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"success": true,
|
||||
"task_id": execution.TaskID,
|
||||
"agent_instance_id": execution.AgentInstanceID,
|
||||
"status": execution.Status,
|
||||
})
|
||||
}
|
||||
|
||||
// TaskIDRequest is a common request with just task_id
|
||||
type TaskIDRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
}
|
||||
|
||||
// StopTaskRequest is the payload for orchestrator.stop
|
||||
type StopTaskRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
Reason string `json:"reason,omitempty"`
|
||||
Force bool `json:"force,omitempty"`
|
||||
}
|
||||
|
||||
// StopTask handles orchestrator.stop action
|
||||
func (h *Handlers) StopTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req StopTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
}
|
||||
|
||||
reason := req.Reason
|
||||
if reason == "" {
|
||||
reason = "stopped via WebSocket API"
|
||||
}
|
||||
|
||||
if err := h.service.StopTask(ctx, req.TaskID, reason, req.Force); err != nil {
|
||||
h.logger.Error("failed to stop task", zap.String("task_id", req.TaskID), zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to stop task: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]bool{"success": true})
|
||||
}
|
||||
|
||||
// PromptTaskRequest is the payload for orchestrator.prompt
|
||||
type PromptTaskRequest struct {
|
||||
TaskID string `json:"task_id"`
|
||||
Prompt string `json:"prompt"`
|
||||
}
|
||||
|
||||
// PromptTask handles orchestrator.prompt action
|
||||
func (h *Handlers) PromptTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req PromptTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
}
|
||||
if req.Prompt == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "prompt is required", nil)
|
||||
}
|
||||
|
||||
if err := h.service.PromptTask(ctx, req.TaskID, req.Prompt); err != nil {
|
||||
h.logger.Error("failed to send prompt", zap.String("task_id", req.TaskID), zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to send prompt: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]bool{"success": true})
|
||||
}
|
||||
|
||||
// CompleteTask handles orchestrator.complete action
|
||||
func (h *Handlers) CompleteTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req TaskIDRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.TaskID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "task_id is required", nil)
|
||||
}
|
||||
|
||||
if err := h.service.CompleteTask(ctx, req.TaskID); err != nil {
|
||||
h.logger.Error("failed to complete task", zap.String("task_id", req.TaskID), zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to complete task: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{
|
||||
"success": true,
|
||||
"message": "task completed",
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,184 @@
|
||||
package wshandlers
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/kandev/kandev/internal/task/service"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// CreateBoardRequest is the payload for board.create
|
||||
type CreateBoardRequest struct {
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description,omitempty"`
|
||||
}
|
||||
|
||||
// BoardResponse is the response for board operations
|
||||
type BoardResponse struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description,omitempty"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
}
|
||||
|
||||
// ListBoardsResponse is the response for board.list
|
||||
type ListBoardsResponse struct {
|
||||
Boards []BoardResponse `json:"boards"`
|
||||
Total int `json:"total"`
|
||||
}
|
||||
|
||||
// CreateBoard handles board.create action
|
||||
func (h *Handlers) CreateBoard(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req CreateBoardRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.Name == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "name is required", nil)
|
||||
}
|
||||
|
||||
svcReq := &service.CreateBoardRequest{
|
||||
Name: req.Name,
|
||||
Description: req.Description,
|
||||
}
|
||||
|
||||
board, err := h.service.CreateBoard(ctx, svcReq)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to create board", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to create board", nil)
|
||||
}
|
||||
|
||||
resp := BoardResponse{
|
||||
ID: board.ID,
|
||||
Name: board.Name,
|
||||
Description: board.Description,
|
||||
CreatedAt: board.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
UpdatedAt: board.UpdatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// ListBoards handles board.list action
|
||||
func (h *Handlers) ListBoards(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
boards, err := h.service.ListBoards(ctx)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to list boards", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to list boards", nil)
|
||||
}
|
||||
|
||||
resp := ListBoardsResponse{
|
||||
Boards: make([]BoardResponse, len(boards)),
|
||||
Total: len(boards),
|
||||
}
|
||||
for i, b := range boards {
|
||||
resp.Boards[i] = BoardResponse{
|
||||
ID: b.ID,
|
||||
Name: b.Name,
|
||||
Description: b.Description,
|
||||
CreatedAt: b.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
UpdatedAt: b.UpdatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// GetBoardRequest is the payload for board.get
|
||||
type GetBoardRequest struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
|
||||
// GetBoard handles board.get action
|
||||
func (h *Handlers) GetBoard(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req GetBoardRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
board, err := h.service.GetBoard(ctx, req.ID)
|
||||
if err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeNotFound, "Board not found", nil)
|
||||
}
|
||||
|
||||
resp := BoardResponse{
|
||||
ID: board.ID,
|
||||
Name: board.Name,
|
||||
Description: board.Description,
|
||||
CreatedAt: board.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
UpdatedAt: board.UpdatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// UpdateBoardRequest is the payload for board.update
|
||||
type UpdateBoardRequest struct {
|
||||
ID string `json:"id"`
|
||||
Name *string `json:"name,omitempty"`
|
||||
Description *string `json:"description,omitempty"`
|
||||
}
|
||||
|
||||
// UpdateBoard handles board.update action
|
||||
func (h *Handlers) UpdateBoard(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req UpdateBoardRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
svcReq := &service.UpdateBoardRequest{
|
||||
Name: req.Name,
|
||||
Description: req.Description,
|
||||
}
|
||||
|
||||
board, err := h.service.UpdateBoard(ctx, req.ID, svcReq)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to update board", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to update board", nil)
|
||||
}
|
||||
|
||||
resp := BoardResponse{
|
||||
ID: board.ID,
|
||||
Name: board.Name,
|
||||
Description: board.Description,
|
||||
CreatedAt: board.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
UpdatedAt: board.UpdatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// DeleteBoardRequest is the payload for board.delete
|
||||
type DeleteBoardRequest struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
|
||||
// DeleteBoard handles board.delete action
|
||||
func (h *Handlers) DeleteBoard(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req DeleteBoardRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
if err := h.service.DeleteBoard(ctx, req.ID); err != nil {
|
||||
h.logger.Error("failed to delete board", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to delete board", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]bool{"success": true})
|
||||
}
|
||||
@@ -0,0 +1,153 @@
|
||||
package wshandlers
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/kandev/kandev/internal/task/service"
|
||||
v1 "github.com/kandev/kandev/pkg/api/v1"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// CreateColumnRequest is the payload for column.create
|
||||
type CreateColumnRequest struct {
|
||||
BoardID string `json:"board_id"`
|
||||
Name string `json:"name"`
|
||||
Position int `json:"position"`
|
||||
State string `json:"state,omitempty"`
|
||||
}
|
||||
|
||||
// ColumnResponse is the response for column operations
|
||||
type ColumnResponse struct {
|
||||
ID string `json:"id"`
|
||||
BoardID string `json:"board_id"`
|
||||
Name string `json:"name"`
|
||||
Position int `json:"position"`
|
||||
State string `json:"state"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
}
|
||||
|
||||
// ListColumnsResponse is the response for column.list
|
||||
type ListColumnsResponse struct {
|
||||
Columns []ColumnResponse `json:"columns"`
|
||||
Total int `json:"total"`
|
||||
}
|
||||
|
||||
// ListColumnsRequest is the payload for column.list
|
||||
type ListColumnsRequest struct {
|
||||
BoardID string `json:"board_id"`
|
||||
}
|
||||
|
||||
// ListColumns handles column.list action
|
||||
func (h *Handlers) ListColumns(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req ListColumnsRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.BoardID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "board_id is required", nil)
|
||||
}
|
||||
|
||||
columns, err := h.service.ListColumns(ctx, req.BoardID)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to list columns", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to list columns", nil)
|
||||
}
|
||||
|
||||
resp := ListColumnsResponse{
|
||||
Columns: make([]ColumnResponse, len(columns)),
|
||||
Total: len(columns),
|
||||
}
|
||||
for i, c := range columns {
|
||||
resp.Columns[i] = ColumnResponse{
|
||||
ID: c.ID,
|
||||
BoardID: c.BoardID,
|
||||
Name: c.Name,
|
||||
Position: c.Position,
|
||||
State: string(c.State),
|
||||
CreatedAt: c.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// CreateColumn handles column.create action
|
||||
func (h *Handlers) CreateColumn(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req CreateColumnRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.BoardID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "board_id is required", nil)
|
||||
}
|
||||
if req.Name == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "name is required", nil)
|
||||
}
|
||||
|
||||
// Default state to TODO if not specified
|
||||
state := v1.TaskState(req.State)
|
||||
if state == "" {
|
||||
state = v1.TaskStateTODO
|
||||
}
|
||||
|
||||
svcReq := &service.CreateColumnRequest{
|
||||
BoardID: req.BoardID,
|
||||
Name: req.Name,
|
||||
Position: req.Position,
|
||||
State: state,
|
||||
}
|
||||
|
||||
column, err := h.service.CreateColumn(ctx, svcReq)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to create column", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to create column", nil)
|
||||
}
|
||||
|
||||
resp := ColumnResponse{
|
||||
ID: column.ID,
|
||||
BoardID: column.BoardID,
|
||||
Name: column.Name,
|
||||
Position: column.Position,
|
||||
State: string(column.State),
|
||||
CreatedAt: column.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// GetColumnRequest is the payload for column.get
|
||||
type GetColumnRequest struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
|
||||
// GetColumn handles column.get action
|
||||
func (h *Handlers) GetColumn(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req GetColumnRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
column, err := h.service.GetColumn(ctx, req.ID)
|
||||
if err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeNotFound, "Column not found", nil)
|
||||
}
|
||||
|
||||
resp := ColumnResponse{
|
||||
ID: column.ID,
|
||||
BoardID: column.BoardID,
|
||||
Name: column.Name,
|
||||
Position: column.Position,
|
||||
State: string(column.State),
|
||||
CreatedAt: column.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
// Package wshandlers provides WebSocket message handlers for the task service.
|
||||
package wshandlers
|
||||
|
||||
import (
|
||||
"github.com/kandev/kandev/internal/common/logger"
|
||||
"github.com/kandev/kandev/internal/task/service"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// Handlers contains WebSocket handlers for the task API
|
||||
type Handlers struct {
|
||||
service *service.Service
|
||||
logger *logger.Logger
|
||||
}
|
||||
|
||||
// NewHandlers creates a new WebSocket handlers instance
|
||||
func NewHandlers(svc *service.Service, log *logger.Logger) *Handlers {
|
||||
return &Handlers{
|
||||
service: svc,
|
||||
logger: log.WithFields(zap.String("component", "task-ws-handlers")),
|
||||
}
|
||||
}
|
||||
|
||||
// RegisterHandlers registers all task handlers with the dispatcher
|
||||
func (h *Handlers) RegisterHandlers(d *ws.Dispatcher) {
|
||||
// Board handlers
|
||||
d.RegisterFunc(ws.ActionBoardList, h.ListBoards)
|
||||
d.RegisterFunc(ws.ActionBoardCreate, h.CreateBoard)
|
||||
d.RegisterFunc(ws.ActionBoardGet, h.GetBoard)
|
||||
d.RegisterFunc(ws.ActionBoardUpdate, h.UpdateBoard)
|
||||
d.RegisterFunc(ws.ActionBoardDelete, h.DeleteBoard)
|
||||
|
||||
// Column handlers
|
||||
d.RegisterFunc(ws.ActionColumnList, h.ListColumns)
|
||||
d.RegisterFunc(ws.ActionColumnCreate, h.CreateColumn)
|
||||
d.RegisterFunc(ws.ActionColumnGet, h.GetColumn)
|
||||
|
||||
// Task handlers
|
||||
d.RegisterFunc(ws.ActionTaskList, h.ListTasks)
|
||||
d.RegisterFunc(ws.ActionTaskCreate, h.CreateTask)
|
||||
d.RegisterFunc(ws.ActionTaskGet, h.GetTask)
|
||||
d.RegisterFunc(ws.ActionTaskUpdate, h.UpdateTask)
|
||||
d.RegisterFunc(ws.ActionTaskDelete, h.DeleteTask)
|
||||
d.RegisterFunc(ws.ActionTaskMove, h.MoveTask)
|
||||
d.RegisterFunc(ws.ActionTaskState, h.UpdateTaskState)
|
||||
}
|
||||
|
||||
@@ -0,0 +1,283 @@
|
||||
package wshandlers
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/kandev/kandev/internal/task/models"
|
||||
"github.com/kandev/kandev/internal/task/service"
|
||||
v1 "github.com/kandev/kandev/pkg/api/v1"
|
||||
ws "github.com/kandev/kandev/pkg/websocket"
|
||||
"go.uber.org/zap"
|
||||
)
|
||||
|
||||
// CreateTaskRequest is the payload for task.create
|
||||
type CreateTaskRequest struct {
|
||||
BoardID string `json:"board_id"`
|
||||
ColumnID string `json:"column_id"`
|
||||
Title string `json:"title"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Priority int `json:"priority,omitempty"`
|
||||
AgentType string `json:"agent_type,omitempty"`
|
||||
RepositoryURL string `json:"repository_url,omitempty"`
|
||||
Branch string `json:"branch,omitempty"`
|
||||
Metadata map[string]interface{} `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// TaskResponse is the response for task operations
|
||||
type TaskResponse struct {
|
||||
ID string `json:"id"`
|
||||
BoardID string `json:"board_id"`
|
||||
ColumnID string `json:"column_id"`
|
||||
Title string `json:"title"`
|
||||
Description string `json:"description,omitempty"`
|
||||
State string `json:"state"`
|
||||
Priority int `json:"priority"`
|
||||
AgentType string `json:"agent_type,omitempty"`
|
||||
RepositoryURL string `json:"repository_url,omitempty"`
|
||||
Branch string `json:"branch,omitempty"`
|
||||
Position int `json:"position"`
|
||||
CreatedAt string `json:"created_at"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
Metadata map[string]interface{} `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// ListTasksRequest is the payload for task.list
|
||||
type ListTasksRequest struct {
|
||||
BoardID string `json:"board_id"`
|
||||
}
|
||||
|
||||
// ListTasksResponse is the response for task.list
|
||||
type ListTasksResponse struct {
|
||||
Tasks []TaskResponse `json:"tasks"`
|
||||
Total int `json:"total"`
|
||||
}
|
||||
|
||||
// CreateTask handles task.create action
|
||||
func (h *Handlers) CreateTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req CreateTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.BoardID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "board_id is required", nil)
|
||||
}
|
||||
if req.ColumnID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "column_id is required", nil)
|
||||
}
|
||||
if req.Title == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "title is required", nil)
|
||||
}
|
||||
|
||||
svcReq := &service.CreateTaskRequest{
|
||||
BoardID: req.BoardID,
|
||||
ColumnID: req.ColumnID,
|
||||
Title: req.Title,
|
||||
Description: req.Description,
|
||||
Priority: req.Priority,
|
||||
AgentType: req.AgentType,
|
||||
RepositoryURL: req.RepositoryURL,
|
||||
Branch: req.Branch,
|
||||
Metadata: req.Metadata,
|
||||
}
|
||||
|
||||
task, err := h.service.CreateTask(ctx, svcReq)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to create task", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to create task", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, taskToResponse(task))
|
||||
}
|
||||
|
||||
// ListTasks handles task.list action
|
||||
func (h *Handlers) ListTasks(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req ListTasksRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.BoardID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "board_id is required", nil)
|
||||
}
|
||||
|
||||
tasks, err := h.service.ListTasks(ctx, req.BoardID)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to list tasks", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to list tasks", nil)
|
||||
}
|
||||
|
||||
resp := ListTasksResponse{
|
||||
Tasks: make([]TaskResponse, len(tasks)),
|
||||
Total: len(tasks),
|
||||
}
|
||||
for i, t := range tasks {
|
||||
resp.Tasks[i] = taskToResponse(t)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, resp)
|
||||
}
|
||||
|
||||
// GetTaskRequest is the payload for task.get
|
||||
type GetTaskRequest struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
|
||||
// GetTask handles task.get action
|
||||
func (h *Handlers) GetTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req GetTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
task, err := h.service.GetTask(ctx, req.ID)
|
||||
if err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeNotFound, "Task not found", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, taskToResponse(task))
|
||||
}
|
||||
|
||||
// UpdateTaskRequest is the payload for task.update
|
||||
type UpdateTaskRequest struct {
|
||||
ID string `json:"id"`
|
||||
Title *string `json:"title,omitempty"`
|
||||
Description *string `json:"description,omitempty"`
|
||||
Priority *int `json:"priority,omitempty"`
|
||||
Metadata map[string]interface{} `json:"metadata,omitempty"`
|
||||
}
|
||||
|
||||
// UpdateTask handles task.update action
|
||||
func (h *Handlers) UpdateTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req UpdateTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
svcReq := &service.UpdateTaskRequest{
|
||||
Title: req.Title,
|
||||
Description: req.Description,
|
||||
Priority: req.Priority,
|
||||
Metadata: req.Metadata,
|
||||
}
|
||||
|
||||
task, err := h.service.UpdateTask(ctx, req.ID, svcReq)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to update task", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to update task", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, taskToResponse(task))
|
||||
}
|
||||
|
||||
// DeleteTaskRequest is the payload for task.delete
|
||||
type DeleteTaskRequest struct {
|
||||
ID string `json:"id"`
|
||||
}
|
||||
|
||||
// DeleteTask handles task.delete action
|
||||
func (h *Handlers) DeleteTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req DeleteTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
|
||||
if err := h.service.DeleteTask(ctx, req.ID); err != nil {
|
||||
h.logger.Error("failed to delete task", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to delete task", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, map[string]bool{"success": true})
|
||||
}
|
||||
|
||||
// MoveTaskRequest is the payload for task.move
|
||||
type MoveTaskRequest struct {
|
||||
ID string `json:"id"`
|
||||
ColumnID string `json:"column_id"`
|
||||
Position int `json:"position"`
|
||||
}
|
||||
|
||||
// MoveTask handles task.move action
|
||||
func (h *Handlers) MoveTask(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req MoveTaskRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
if req.ColumnID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "column_id is required", nil)
|
||||
}
|
||||
|
||||
task, err := h.service.MoveTask(ctx, req.ID, req.ColumnID, req.Position)
|
||||
if err != nil {
|
||||
h.logger.Error("failed to move task", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to move task", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, taskToResponse(task))
|
||||
}
|
||||
|
||||
// UpdateTaskStateRequest is the payload for task.state
|
||||
type UpdateTaskStateRequest struct {
|
||||
ID string `json:"id"`
|
||||
State string `json:"state"`
|
||||
}
|
||||
|
||||
// UpdateTaskState handles task.state action
|
||||
func (h *Handlers) UpdateTaskState(ctx context.Context, msg *ws.Message) (*ws.Message, error) {
|
||||
var req UpdateTaskStateRequest
|
||||
if err := msg.ParsePayload(&req); err != nil {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeBadRequest, "Invalid payload: "+err.Error(), nil)
|
||||
}
|
||||
|
||||
if req.ID == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "id is required", nil)
|
||||
}
|
||||
if req.State == "" {
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "state is required", nil)
|
||||
}
|
||||
|
||||
task, err := h.service.UpdateTaskState(ctx, req.ID, v1.TaskState(req.State))
|
||||
if err != nil {
|
||||
h.logger.Error("failed to update task state", zap.Error(err))
|
||||
return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeInternalError, "Failed to update task state", nil)
|
||||
}
|
||||
|
||||
return ws.NewResponse(msg.ID, msg.Action, taskToResponse(task))
|
||||
}
|
||||
|
||||
// taskToResponse converts a task model to response
|
||||
func taskToResponse(t *models.Task) TaskResponse {
|
||||
return TaskResponse{
|
||||
ID: t.ID,
|
||||
BoardID: t.BoardID,
|
||||
ColumnID: t.ColumnID,
|
||||
Title: t.Title,
|
||||
Description: t.Description,
|
||||
State: string(t.State),
|
||||
Priority: t.Priority,
|
||||
AgentType: t.AgentType,
|
||||
RepositoryURL: t.RepositoryURL,
|
||||
Branch: t.Branch,
|
||||
Position: t.Position,
|
||||
CreatedAt: t.CreatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
UpdatedAt: t.UpdatedAt.Format("2006-01-02T15:04:05Z"),
|
||||
Metadata: t.Metadata,
|
||||
}
|
||||
}
|
||||
|
||||
Binary file not shown.
@@ -0,0 +1,76 @@
|
||||
package websocket
|
||||
|
||||
// Action constants for WebSocket messages
|
||||
const (
|
||||
// Health
|
||||
ActionHealthCheck = "health.check"
|
||||
|
||||
// Board actions
|
||||
ActionBoardList = "board.list"
|
||||
ActionBoardCreate = "board.create"
|
||||
ActionBoardGet = "board.get"
|
||||
ActionBoardUpdate = "board.update"
|
||||
ActionBoardDelete = "board.delete"
|
||||
|
||||
// Column actions
|
||||
ActionColumnList = "column.list"
|
||||
ActionColumnCreate = "column.create"
|
||||
ActionColumnGet = "column.get"
|
||||
|
||||
// Task actions
|
||||
ActionTaskList = "task.list"
|
||||
ActionTaskCreate = "task.create"
|
||||
ActionTaskGet = "task.get"
|
||||
ActionTaskUpdate = "task.update"
|
||||
ActionTaskDelete = "task.delete"
|
||||
ActionTaskMove = "task.move"
|
||||
ActionTaskState = "task.state"
|
||||
|
||||
// Agent actions
|
||||
ActionAgentList = "agent.list"
|
||||
ActionAgentLaunch = "agent.launch"
|
||||
ActionAgentStatus = "agent.status"
|
||||
ActionAgentLogs = "agent.logs"
|
||||
ActionAgentStop = "agent.stop"
|
||||
ActionAgentPrompt = "agent.prompt"
|
||||
ActionAgentCancel = "agent.cancel"
|
||||
ActionAgentSession = "agent.session"
|
||||
ActionAgentTypes = "agent.types"
|
||||
|
||||
// Orchestrator actions
|
||||
ActionOrchestratorStatus = "orchestrator.status"
|
||||
ActionOrchestratorQueue = "orchestrator.queue"
|
||||
ActionOrchestratorTrigger = "orchestrator.trigger"
|
||||
ActionOrchestratorStart = "orchestrator.start"
|
||||
ActionOrchestratorStop = "orchestrator.stop"
|
||||
ActionOrchestratorPause = "orchestrator.pause"
|
||||
ActionOrchestratorResume = "orchestrator.resume"
|
||||
ActionOrchestratorPrompt = "orchestrator.prompt"
|
||||
ActionOrchestratorComplete = "orchestrator.complete"
|
||||
|
||||
// Subscription actions
|
||||
ActionTaskSubscribe = "task.subscribe"
|
||||
ActionTaskUnsubscribe = "task.unsubscribe"
|
||||
|
||||
// Notification actions (server -> client)
|
||||
ActionACPProgress = "acp.progress"
|
||||
ActionACPLog = "acp.log"
|
||||
ActionACPResult = "acp.result"
|
||||
ActionACPError = "acp.error"
|
||||
ActionACPStatus = "acp.status"
|
||||
ActionACPHeartbeat = "acp.heartbeat"
|
||||
ActionTaskUpdated = "task.updated"
|
||||
ActionAgentUpdated = "agent.updated"
|
||||
)
|
||||
|
||||
// Error codes
|
||||
const (
|
||||
ErrorCodeBadRequest = "BAD_REQUEST"
|
||||
ErrorCodeNotFound = "NOT_FOUND"
|
||||
ErrorCodeInternalError = "INTERNAL_ERROR"
|
||||
ErrorCodeUnauthorized = "UNAUTHORIZED"
|
||||
ErrorCodeForbidden = "FORBIDDEN"
|
||||
ErrorCodeValidation = "VALIDATION_ERROR"
|
||||
ErrorCodeUnknownAction = "UNKNOWN_ACTION"
|
||||
)
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
package websocket
|
||||
|
||||
import "context"
|
||||
|
||||
// Handler is the interface for WebSocket message handlers
|
||||
type Handler interface {
|
||||
// Handle processes a WebSocket message and returns a response
|
||||
Handle(ctx context.Context, msg *Message) (*Message, error)
|
||||
}
|
||||
|
||||
// HandlerFunc is a function type that implements Handler
|
||||
type HandlerFunc func(ctx context.Context, msg *Message) (*Message, error)
|
||||
|
||||
// Handle implements the Handler interface
|
||||
func (f HandlerFunc) Handle(ctx context.Context, msg *Message) (*Message, error) {
|
||||
return f(ctx, msg)
|
||||
}
|
||||
|
||||
// Dispatcher routes messages to appropriate handlers based on action
|
||||
type Dispatcher struct {
|
||||
handlers map[string]Handler
|
||||
}
|
||||
|
||||
// NewDispatcher creates a new message dispatcher
|
||||
func NewDispatcher() *Dispatcher {
|
||||
return &Dispatcher{
|
||||
handlers: make(map[string]Handler),
|
||||
}
|
||||
}
|
||||
|
||||
// Register registers a handler for an action
|
||||
func (d *Dispatcher) Register(action string, handler Handler) {
|
||||
d.handlers[action] = handler
|
||||
}
|
||||
|
||||
// RegisterFunc registers a handler function for an action
|
||||
func (d *Dispatcher) RegisterFunc(action string, handler HandlerFunc) {
|
||||
d.handlers[action] = handler
|
||||
}
|
||||
|
||||
// Dispatch routes a message to the appropriate handler
|
||||
func (d *Dispatcher) Dispatch(ctx context.Context, msg *Message) (*Message, error) {
|
||||
handler, ok := d.handlers[msg.Action]
|
||||
if !ok {
|
||||
return NewError(msg.ID, msg.Action, ErrorCodeUnknownAction,
|
||||
"Unknown action: "+msg.Action, nil)
|
||||
}
|
||||
return handler.Handle(ctx, msg)
|
||||
}
|
||||
|
||||
// HasHandler returns true if a handler is registered for the action
|
||||
func (d *Dispatcher) HasHandler(action string) bool {
|
||||
_, ok := d.handlers[action]
|
||||
return ok
|
||||
}
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
// Package websocket provides WebSocket message types and protocol definitions.
|
||||
package websocket
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"time"
|
||||
)
|
||||
|
||||
// MessageType represents the type of WebSocket message
|
||||
type MessageType string
|
||||
|
||||
const (
|
||||
MessageTypeRequest MessageType = "request"
|
||||
MessageTypeResponse MessageType = "response"
|
||||
MessageTypeNotification MessageType = "notification"
|
||||
MessageTypeError MessageType = "error"
|
||||
)
|
||||
|
||||
// Message is the base envelope for all WebSocket messages
|
||||
type Message struct {
|
||||
ID string `json:"id,omitempty"`
|
||||
Type MessageType `json:"type"`
|
||||
Action string `json:"action"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
Timestamp time.Time `json:"timestamp"`
|
||||
}
|
||||
|
||||
// Request represents a client request message
|
||||
type Request struct {
|
||||
ID string `json:"id"`
|
||||
Type MessageType `json:"type"`
|
||||
Action string `json:"action"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
}
|
||||
|
||||
// Response represents a server response message
|
||||
type Response struct {
|
||||
ID string `json:"id"`
|
||||
Type MessageType `json:"type"`
|
||||
Action string `json:"action"`
|
||||
Payload json.RawMessage `json:"payload,omitempty"`
|
||||
Timestamp time.Time `json:"timestamp"`
|
||||
}
|
||||
|
||||
// Notification represents a server push notification
|
||||
type Notification struct {
|
||||
Type MessageType `json:"type"`
|
||||
Action string `json:"action"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
Timestamp time.Time `json:"timestamp"`
|
||||
}
|
||||
|
||||
// ErrorPayload represents an error response payload
|
||||
type ErrorPayload struct {
|
||||
Code string `json:"code"`
|
||||
Message string `json:"message"`
|
||||
Details map[string]interface{} `json:"details,omitempty"`
|
||||
}
|
||||
|
||||
// NewRequest creates a new request message
|
||||
func NewRequest(id, action string, payload interface{}) (*Message, error) {
|
||||
data, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &Message{
|
||||
ID: id,
|
||||
Type: MessageTypeRequest,
|
||||
Action: action,
|
||||
Payload: data,
|
||||
Timestamp: time.Now().UTC(),
|
||||
}, nil
|
||||
}
|
||||
|
||||
// NewResponse creates a new response message
|
||||
func NewResponse(id, action string, payload interface{}) (*Message, error) {
|
||||
data, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &Message{
|
||||
ID: id,
|
||||
Type: MessageTypeResponse,
|
||||
Action: action,
|
||||
Payload: data,
|
||||
Timestamp: time.Now().UTC(),
|
||||
}, nil
|
||||
}
|
||||
|
||||
// NewNotification creates a new notification message
|
||||
func NewNotification(action string, payload interface{}) (*Message, error) {
|
||||
data, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &Message{
|
||||
Type: MessageTypeNotification,
|
||||
Action: action,
|
||||
Payload: data,
|
||||
Timestamp: time.Now().UTC(),
|
||||
}, nil
|
||||
}
|
||||
|
||||
// NewError creates a new error response message
|
||||
func NewError(id, action, code, message string, details map[string]interface{}) (*Message, error) {
|
||||
payload := ErrorPayload{
|
||||
Code: code,
|
||||
Message: message,
|
||||
Details: details,
|
||||
}
|
||||
data, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &Message{
|
||||
ID: id,
|
||||
Type: MessageTypeError,
|
||||
Action: action,
|
||||
Payload: data,
|
||||
Timestamp: time.Now().UTC(),
|
||||
}, nil
|
||||
}
|
||||
|
||||
// ParsePayload parses the payload into the given struct
|
||||
func (m *Message) ParsePayload(v interface{}) error {
|
||||
if m.Payload == nil {
|
||||
return nil
|
||||
}
|
||||
return json.Unmarshal(m.Payload, v)
|
||||
}
|
||||
|
||||
+33
-22
@@ -14,7 +14,7 @@ The current implementation uses a **unified binary architecture** instead of sep
|
||||
- ✅ **Native ACP (Agent Communication Protocol)** - JSON-RPC 2.0 over stdin/stdout
|
||||
- ✅ **Permission request handling** - Auto-approval of workspace indexing and tool permissions
|
||||
- ✅ **Session resumption** for multi-turn agent conversations
|
||||
- 📋 WebSocket support for real-time frontend streaming
|
||||
- ✅ WebSocket-first API for all operations (replacing REST)
|
||||
- 📋 JWT authentication
|
||||
- 📋 NATS event bus for distributed deployment
|
||||
|
||||
@@ -60,23 +60,23 @@ Kandev uses an event-driven architecture with **Agent Communication Protocol (AC
|
||||
|
||||
## Planned Architecture (Microservices) 📋
|
||||
|
||||
### 1. API Gateway
|
||||
### 1. API Gateway (WebSocket-First)
|
||||
**Port:** 8080
|
||||
**Purpose:** Single entry point for all client requests with WebSocket support
|
||||
**Purpose:** Single entry point for all client requests via WebSocket
|
||||
|
||||
**Responsibilities:**
|
||||
- Route requests to appropriate services
|
||||
- Route WebSocket messages to appropriate services
|
||||
- JWT authentication and authorization
|
||||
- **WebSocket connection management for real-time ACP streaming**
|
||||
- **Proxy ACP streams from Orchestrator to frontend**
|
||||
- **WebSocket connection management for all API operations**
|
||||
- **WebSocket message routing for real-time ACP streaming**
|
||||
- Rate limiting and request validation
|
||||
- CORS handling
|
||||
- API versioning
|
||||
- CORS handling for WebSocket upgrade requests
|
||||
- API versioning via message schema
|
||||
|
||||
**Dependencies:**
|
||||
- Task Service (internal)
|
||||
- Agent Manager (internal)
|
||||
- Orchestrator (internal - WebSocket proxy)
|
||||
- Orchestrator (internal - WebSocket message routing)
|
||||
- PostgreSQL (for user auth)
|
||||
|
||||
---
|
||||
@@ -129,11 +129,12 @@ Kandev uses an event-driven architecture with **Agent Communication Protocol (AC
|
||||
- `agent.failed`
|
||||
- **`acp.message.*` - All ACP messages from agents**
|
||||
|
||||
**Key Endpoints:**
|
||||
- `WS /api/v1/orchestrator/tasks/{taskId}/stream` - Real-time ACP streaming
|
||||
- `POST /api/v1/orchestrator/tasks/{taskId}/start` - Start agent execution
|
||||
- `POST /api/v1/orchestrator/tasks/{taskId}/stop` - Stop agent execution
|
||||
- `GET /api/v1/orchestrator/tasks/{taskId}/status` - Get execution status
|
||||
**WebSocket Actions:**
|
||||
- `orchestrator.subscribe` - Subscribe to real-time ACP streaming for a task
|
||||
- `orchestrator.unsubscribe` - Unsubscribe from ACP streaming
|
||||
- `orchestrator.start` - Start agent execution for a task
|
||||
- `orchestrator.stop` - Stop agent execution for a task
|
||||
- `orchestrator.status` - Get execution status for a task
|
||||
|
||||
**Orchestration Logic:**
|
||||
```
|
||||
@@ -241,13 +242,17 @@ Workspace Mount (Read-Write):
|
||||
### Example 1: User Creates a Task with AI Agent (with Real-time ACP Streaming)
|
||||
|
||||
```
|
||||
1. User → API Gateway: POST /api/v1/boards/{id}/tasks
|
||||
1. User → API Gateway: WebSocket message: task.create
|
||||
{
|
||||
"title": "Fix login bug",
|
||||
"description": "Users can't login with email",
|
||||
"agent_type": "auggie-cli",
|
||||
"repository_url": "https://github.com/user/repo",
|
||||
"branch": "main"
|
||||
"action": "task.create",
|
||||
"payload": {
|
||||
"boardId": "{id}",
|
||||
"title": "Fix login bug",
|
||||
"description": "Users can't login with email",
|
||||
"agent_type": "auggie-cli",
|
||||
"repository_url": "https://github.com/user/repo",
|
||||
"branch": "main"
|
||||
}
|
||||
}
|
||||
|
||||
2. API Gateway → Task Service: Forward request
|
||||
@@ -333,8 +338,14 @@ Workspace Mount (Read-Write):
|
||||
### Example 2: Manual Task State Change
|
||||
|
||||
```
|
||||
1. User → API Gateway: PATCH /api/v1/tasks/{id}/state
|
||||
{ "state": "IN_PROGRESS" }
|
||||
1. User → API Gateway: WebSocket message: task.state
|
||||
{
|
||||
"action": "task.state",
|
||||
"payload": {
|
||||
"taskId": "{id}",
|
||||
"state": "IN_PROGRESS"
|
||||
}
|
||||
}
|
||||
|
||||
2. API Gateway → Task Service: Forward request
|
||||
|
||||
|
||||
+194
-40
@@ -66,72 +66,225 @@ The server starts on port 8080 by default.
|
||||
|
||||
### Step 3: Verify It's Running
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:8080/health
|
||||
The backend uses a WebSocket-first architecture. Connect to `ws://localhost:8080/ws` to interact with the API.
|
||||
|
||||
# Should return: {"status":"ok"}
|
||||
#### Using websocat (Command Line)
|
||||
|
||||
```bash
|
||||
# Install websocat
|
||||
# macOS: brew install websocat
|
||||
# Linux: cargo install websocat
|
||||
|
||||
# Health check
|
||||
echo '{"id":"1","type":"request","action":"health.check","payload":{}}' | websocat ws://localhost:8080/ws
|
||||
|
||||
# Should return a response with status "ok"
|
||||
```
|
||||
|
||||
#### Using JavaScript
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8080/ws');
|
||||
|
||||
ws.onopen = () => {
|
||||
ws.send(JSON.stringify({
|
||||
id: '1',
|
||||
type: 'request',
|
||||
action: 'health.check',
|
||||
payload: {}
|
||||
}));
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const msg = JSON.parse(event.data);
|
||||
console.log('Health:', msg); // { id: '1', type: 'response', action: 'health.check', payload: { status: 'ok' }, ... }
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebSocket Message Protocol
|
||||
|
||||
### Connection
|
||||
|
||||
Connect to: `ws://localhost:8080/ws`
|
||||
|
||||
### Message Envelope
|
||||
|
||||
All messages use this envelope format:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "correlation-uuid",
|
||||
"type": "request|response|notification|error",
|
||||
"action": "action.name",
|
||||
"payload": {},
|
||||
"timestamp": "2026-01-10T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Message Types
|
||||
|
||||
- `request` - Client request to the server
|
||||
- `response` - Server response to a request
|
||||
- `notification` - Server push notification (e.g., agent status updates)
|
||||
- `error` - Error response
|
||||
|
||||
---
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Create a Board
|
||||
|
||||
#### websocat
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/boards \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "My Project", "description": "Project tasks"}'
|
||||
echo '{"id":"1","type":"request","action":"board.create","payload":{"name":"My Project","description":"Project tasks"}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '1',
|
||||
type: 'request',
|
||||
action: 'board.create',
|
||||
payload: { name: 'My Project', description: 'Project tasks' }
|
||||
}));
|
||||
```
|
||||
|
||||
### List Boards
|
||||
|
||||
#### websocat
|
||||
|
||||
```bash
|
||||
echo '{"id":"2","type":"request","action":"board.list","payload":{}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '2',
|
||||
type: 'request',
|
||||
action: 'board.list',
|
||||
payload: {}
|
||||
}));
|
||||
```
|
||||
|
||||
### Create a Column
|
||||
|
||||
#### websocat
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/boards/{board_id}/columns \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "To Do"}'
|
||||
echo '{"id":"3","type":"request","action":"column.create","payload":{"board_id":"<board_id>","name":"To Do"}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '3',
|
||||
type: 'request',
|
||||
action: 'column.create',
|
||||
payload: { board_id: '<board_id>', name: 'To Do' }
|
||||
}));
|
||||
```
|
||||
|
||||
### Create a Task
|
||||
|
||||
#### websocat
|
||||
|
||||
```bash
|
||||
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"}'
|
||||
echo '{"id":"4","type":"request","action":"task.create","payload":{"board_id":"<board_id>","column_id":"<column_id>","title":"Fix login bug","description":"Users cannot login"}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
### Create a Task with Agent
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '4',
|
||||
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 for a Task
|
||||
|
||||
#### websocat
|
||||
|
||||
```bash
|
||||
# Create a task that will be executed by an AI agent
|
||||
curl -X POST http://localhost:8080/api/v1/tasks \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Analyze codebase",
|
||||
"description": "Provide an overview of the project structure",
|
||||
"board_id": "{board_id}",
|
||||
"column_id": "{column_id}",
|
||||
"agent_type": "augment-agent",
|
||||
"repository_url": "/path/to/your/project"
|
||||
}'
|
||||
echo '{"id":"5","type":"request","action":"agent.launch","payload":{"task_id":"<task_id>","agent_type":"augment-agent","repository_url":"/path/to/your/project"}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '5',
|
||||
type: 'request',
|
||||
action: 'agent.launch',
|
||||
payload: {
|
||||
task_id: '<task_id>',
|
||||
agent_type: 'augment-agent',
|
||||
repository_url: '/path/to/your/project'
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
### Start Task via Orchestrator
|
||||
|
||||
#### websocat
|
||||
|
||||
```bash
|
||||
# Start the task - this launches the agent container
|
||||
curl -X POST http://localhost:8080/api/v1/orchestrator/tasks/{task_id}/start \
|
||||
-H "Content-Type: application/json"
|
||||
echo '{"id":"6","type":"request","action":"orchestrator.start","payload":{"task_id":"<task_id>"}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '6',
|
||||
type: 'request',
|
||||
action: 'orchestrator.start',
|
||||
payload: { task_id: '<task_id>' }
|
||||
}));
|
||||
```
|
||||
|
||||
### Check Agent Status
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/api/v1/agents/{agent_id}/status
|
||||
#### websocat
|
||||
|
||||
# List all agents
|
||||
curl http://localhost:8080/api/v1/agents
|
||||
```bash
|
||||
echo '{"id":"7","type":"request","action":"agent.status","payload":{"agent_id":"<agent_id>"}}' | websocat ws://localhost:8080/ws
|
||||
```
|
||||
|
||||
#### JavaScript
|
||||
|
||||
```javascript
|
||||
ws.send(JSON.stringify({
|
||||
id: '7',
|
||||
type: 'request',
|
||||
action: 'agent.status',
|
||||
payload: { agent_id: '<agent_id>' }
|
||||
}));
|
||||
```
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
For interactive testing, connect in interactive mode:
|
||||
|
||||
```bash
|
||||
websocat ws://localhost:8080/ws
|
||||
# Then type messages manually, one per line:
|
||||
{"id":"1","type":"request","action":"health.check","payload":{}}
|
||||
{"id":"2","type":"request","action":"board.list","payload":{}}
|
||||
```
|
||||
|
||||
---
|
||||
@@ -150,14 +303,15 @@ cd /path/to/kandev
|
||||
./scripts/e2e-test.sh
|
||||
```
|
||||
|
||||
The E2E test:
|
||||
1. Starts the server with a fresh database
|
||||
2. Creates a board, column, and task
|
||||
3. Starts the task via the orchestrator
|
||||
4. Verifies the agent container starts
|
||||
5. Checks that ACP session is created
|
||||
6. Verifies permission requests are handled
|
||||
7. Waits for agent to complete
|
||||
The E2E test uses WebSocket connections to:
|
||||
1. Start the server with a fresh database
|
||||
2. Connect via WebSocket to `ws://localhost:8080/ws`
|
||||
3. Create a board, column, and task using WebSocket messages
|
||||
4. Start the task via the orchestrator (`orchestrator.start`)
|
||||
5. Verify the agent container starts
|
||||
6. Check that ACP session is created
|
||||
7. Receive real-time agent status notifications
|
||||
8. Wait for agent to complete
|
||||
|
||||
---
|
||||
|
||||
|
||||
+355
-308
@@ -2,6 +2,7 @@
|
||||
|
||||
> **Note:** This is the original planning document for the microservices architecture.
|
||||
> The current implementation uses a simplified unified binary approach with SQLite.
|
||||
> The current implementation uses a WebSocket-only API (no REST endpoints).
|
||||
> See [GETTING_STARTED.md](GETTING_STARTED.md) for the current implementation details.
|
||||
> This document is preserved for reference and future scaling considerations.
|
||||
|
||||
@@ -12,25 +13,26 @@
|
||||
### High-Level Architecture
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Frontend UI │ (Out of scope - connects via WebSocket/REST)
|
||||
│ Frontend UI │ (Out of scope - connects via WebSocket)
|
||||
└────────┬────────┘
|
||||
│ REST API + WebSocket (ACP Streaming)
|
||||
│ Single WebSocket Connection
|
||||
│ ws://localhost:8080/ws
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ API Gateway Service │
|
||||
│ - Authentication & Authorization │
|
||||
│ - Request routing │
|
||||
│ - WebSocket connection management │
|
||||
│ - Message routing & dispatching │
|
||||
│ - Authentication & Authorization │
|
||||
│ - Rate limiting │
|
||||
└────────┬────────────────────────────────┘
|
||||
│
|
||||
│ WebSocket Messages
|
||||
┌────┴────┬──────────────┬─────────────┐
|
||||
▼ ▼ ▼ ▼
|
||||
┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐
|
||||
│ Task │ │Orchestr- │ │ Agent │ │ Event │
|
||||
│Service │ │ator │ │ Manager │ │ Bus │
|
||||
│ │ │ Service │ │ Service │ │ (NATS) │
|
||||
│ │ │+ ACP API │ │+ ACP │ │ │
|
||||
│ │ │+ ACP │ │+ ACP │ │ │
|
||||
└───┬────┘ └────┬─────┘ └────┬────┘ └────┬─────┘
|
||||
│ │ │ │
|
||||
└───────────┴────────────┴───────────┘
|
||||
@@ -94,27 +96,25 @@
|
||||
**Package:** `cmd/api-gateway`
|
||||
|
||||
**Responsibilities:**
|
||||
- HTTP request handling and routing
|
||||
- WebSocket connection management for ACP streaming
|
||||
- JWT-based authentication
|
||||
- Request validation
|
||||
- CORS handling
|
||||
- API versioning
|
||||
- Metrics collection
|
||||
- Real-time ACP stream proxying to frontend
|
||||
- WebSocket connection management and message routing
|
||||
- WebSocket message dispatching to appropriate services
|
||||
- JWT-based authentication via connection handshake
|
||||
- Message validation and rate limiting
|
||||
- Real-time notification broadcasting
|
||||
- ACP stream proxying to connected clients
|
||||
|
||||
**Key Components:**
|
||||
- `internal/gateway/router` - HTTP routing
|
||||
- `internal/gateway/websocket` - WebSocket connection and message handling
|
||||
- `internal/gateway/dispatcher` - Message routing to services
|
||||
- `internal/gateway/middleware` - Auth, logging, rate limiting
|
||||
- `internal/gateway/handlers` - HTTP handlers
|
||||
- `internal/gateway/websocket` - WebSocket connection management
|
||||
- `internal/gateway/broadcast` - Notification broadcasting to clients
|
||||
- `internal/gateway/streaming` - ACP stream multiplexing
|
||||
|
||||
### 2.2 Task Service
|
||||
**Package:** `cmd/task-service`
|
||||
|
||||
**Responsibilities:**
|
||||
- CRUD operations for tasks
|
||||
- CRUD operations for tasks via WebSocket messages
|
||||
- Task state management (TODO, IN_PROGRESS, BLOCKED, COMPLETED, FAILED)
|
||||
- Task assignment to agents
|
||||
- Task priority and scheduling
|
||||
@@ -123,6 +123,7 @@
|
||||
**Key Components:**
|
||||
- `internal/task/repository` - Database operations
|
||||
- `internal/task/service` - Business logic
|
||||
- `internal/task/handlers` - WebSocket message handlers
|
||||
- `internal/task/models` - Data structures
|
||||
|
||||
### 2.3 Orchestrator Service
|
||||
@@ -137,7 +138,7 @@
|
||||
- Health monitoring of running agents
|
||||
- **ACP stream aggregation and distribution**
|
||||
- **Real-time agent status tracking**
|
||||
- **WebSocket endpoint for frontend streaming**
|
||||
- **WebSocket notification publishing**
|
||||
|
||||
**Key Components:**
|
||||
- `internal/orchestrator/watcher` - Event monitoring
|
||||
@@ -145,7 +146,7 @@
|
||||
- `internal/orchestrator/executor` - Agent execution coordination
|
||||
- `internal/orchestrator/acp` - ACP protocol handler
|
||||
- `internal/orchestrator/streaming` - Real-time stream management
|
||||
- `internal/orchestrator/api` - REST API for orchestrator control
|
||||
- `internal/orchestrator/handlers` - WebSocket message handlers
|
||||
|
||||
### 2.4 Agent Manager Service
|
||||
**Package:** `cmd/agent-manager`
|
||||
@@ -167,7 +168,7 @@
|
||||
- `internal/agent/monitor` - Health and metrics
|
||||
- `internal/agent/acp` - ACP protocol implementation
|
||||
- `internal/agent/credentials` - Host credential management
|
||||
- `internal/agent/streaming` - Real-time stream handling
|
||||
- `internal/agent/handlers` - WebSocket message handlers
|
||||
|
||||
## 3. Database Schema
|
||||
|
||||
@@ -450,300 +451,293 @@ docker build -t kandev/gemini-agent:latest .
|
||||
- **Development**: Local Docker registry or Docker Hub
|
||||
- **Production**: Private container registry (AWS ECR, Google GCR, or Azure ACR)
|
||||
|
||||
## 5. API Endpoints
|
||||
## 5. WebSocket API
|
||||
|
||||
### 4.1 Task Management API
|
||||
The backend exposes a single WebSocket endpoint for all client communication. All operations use a unified message envelope format.
|
||||
|
||||
#### Tasks
|
||||
- `POST /api/v1/boards/{boardId}/tasks` - Create a new task
|
||||
- `GET /api/v1/boards/{boardId}/tasks` - List tasks (with filtering)
|
||||
- `GET /api/v1/tasks/{taskId}` - Get task details
|
||||
- `PUT /api/v1/tasks/{taskId}` - Update task
|
||||
- `DELETE /api/v1/tasks/{taskId}` - Delete task
|
||||
- `PATCH /api/v1/tasks/{taskId}/state` - Update task state
|
||||
- `GET /api/v1/tasks/{taskId}/events` - Get task history
|
||||
### 5.1 Connection
|
||||
|
||||
#### Boards
|
||||
- `POST /api/v1/boards` - Create a new board
|
||||
- `GET /api/v1/boards` - List user's boards
|
||||
- `GET /api/v1/boards/{boardId}` - Get board details
|
||||
- `PUT /api/v1/boards/{boardId}` - Update board
|
||||
- `DELETE /api/v1/boards/{boardId}` - Delete board
|
||||
**Endpoint:** `ws://localhost:8080/ws`
|
||||
|
||||
### 4.2 Agent Management API
|
||||
**Authentication:** JWT token passed in the initial connection handshake via query parameter or header.
|
||||
|
||||
#### Agent Instances
|
||||
- `GET /api/v1/agents` - List all agent instances
|
||||
- `GET /api/v1/agents/{agentId}` - Get agent instance details
|
||||
- `GET /api/v1/agents/{agentId}/logs` - Get agent logs
|
||||
- `POST /api/v1/agents/{agentId}/stop` - Stop a running agent
|
||||
- `GET /api/v1/tasks/{taskId}/agents` - Get agents for a task
|
||||
|
||||
#### Agent Types
|
||||
- `GET /api/v1/agent-types` - List available agent types
|
||||
- `GET /api/v1/agent-types/{typeId}` - Get agent type details
|
||||
- `POST /api/v1/agent-types` - Register new agent type (admin)
|
||||
- `PUT /api/v1/agent-types/{typeId}` - Update agent type (admin)
|
||||
|
||||
### 4.3 Orchestrator API (Real-time & Control)
|
||||
|
||||
The Orchestrator service exposes both REST and WebSocket endpoints for real-time agent monitoring and control.
|
||||
|
||||
#### Orchestration Control (REST)
|
||||
|
||||
**`POST /api/v1/orchestrator/trigger`**
|
||||
- Manually trigger orchestration for a specific task
|
||||
- **Request Body:**
|
||||
```json
|
||||
{
|
||||
"task_id": "uuid",
|
||||
"force": false
|
||||
}
|
||||
```
|
||||
- **Response:** `202 Accepted`
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
**`GET /api/v1/orchestrator/status`**
|
||||
- Get overall orchestrator status and metrics
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"active_agents": 5,
|
||||
"queued_tasks": 12,
|
||||
"uptime_seconds": 86400,
|
||||
"last_heartbeat": "2026-01-09T10:30:00Z"
|
||||
}
|
||||
```
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
**`GET /api/v1/orchestrator/queue`**
|
||||
- View current task queue with priorities
|
||||
- **Query Params:** `?limit=50&offset=0`
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{
|
||||
"task_id": "uuid",
|
||||
"priority": 5,
|
||||
"queued_at": "2026-01-09T10:25:00Z",
|
||||
"estimated_start": "2026-01-09T10:35:00Z"
|
||||
}
|
||||
],
|
||||
"total": 12
|
||||
}
|
||||
```
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
#### Agent Execution Control (REST)
|
||||
|
||||
**`POST /api/v1/orchestrator/tasks/{taskId}/start`**
|
||||
- Start agent execution for a task
|
||||
- **Request Body:**
|
||||
```json
|
||||
{
|
||||
"agent_type": "auggie-cli",
|
||||
"priority": 5
|
||||
}
|
||||
```
|
||||
- **Response:** `202 Accepted` with agent instance ID
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
**`POST /api/v1/orchestrator/tasks/{taskId}/stop`**
|
||||
- Stop running agent for a task
|
||||
- **Request Body:**
|
||||
```json
|
||||
{
|
||||
"reason": "User requested stop",
|
||||
"force": false
|
||||
}
|
||||
```
|
||||
- **Response:** `200 OK`
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
**`POST /api/v1/orchestrator/tasks/{taskId}/pause`**
|
||||
- Pause agent execution (if supported by agent)
|
||||
- **Response:** `200 OK` or `501 Not Implemented`
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
**`POST /api/v1/orchestrator/tasks/{taskId}/resume`**
|
||||
- Resume paused agent execution
|
||||
- **Response:** `200 OK`
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
**`GET /api/v1/orchestrator/tasks/{taskId}/status`**
|
||||
- Get detailed execution status for a task
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"task_id": "uuid",
|
||||
"state": "IN_PROGRESS",
|
||||
"agent_instance_id": "uuid",
|
||||
"agent_type": "auggie-cli",
|
||||
"started_at": "2026-01-09T10:30:00Z",
|
||||
"progress": 45,
|
||||
"current_operation": "Analyzing code structure...",
|
||||
"estimated_completion": "2026-01-09T10:45:00Z"
|
||||
}
|
||||
```
|
||||
- **Auth:** Required (JWT)
|
||||
|
||||
#### Real-time ACP Streaming (WebSocket)
|
||||
|
||||
**`WS /api/v1/orchestrator/tasks/{taskId}/stream`**
|
||||
- WebSocket endpoint for real-time ACP message streaming
|
||||
- **Connection:** Upgrade from HTTP to WebSocket
|
||||
- **Auth:** JWT token in query param or header
|
||||
- **Protocol:** ACP over WebSocket
|
||||
|
||||
**Connection Flow:**
|
||||
```javascript
|
||||
// Client connects
|
||||
const ws = new WebSocket('ws://localhost:8082/api/v1/orchestrator/tasks/{taskId}/stream?token=JWT_TOKEN');
|
||||
|
||||
// Receive ACP messages
|
||||
ws.onmessage = (event) => {
|
||||
const acpMessage = JSON.parse(event.data);
|
||||
// Handle: progress, log, result, error, status
|
||||
};
|
||||
|
||||
// Send control messages (optional)
|
||||
ws.send(JSON.stringify({
|
||||
type: 'control',
|
||||
action: 'pause'
|
||||
}));
|
||||
const ws = new WebSocket('ws://localhost:8080/ws?token=JWT_TOKEN');
|
||||
```
|
||||
|
||||
**ACP Message Types Streamed:**
|
||||
- `progress` - Agent progress updates (0-100%)
|
||||
- `log` - Real-time log messages from agent
|
||||
- `result` - Intermediate or final results
|
||||
- `error` - Error messages and stack traces
|
||||
- `status` - Agent status changes
|
||||
- `heartbeat` - Keep-alive messages
|
||||
### 5.2 Message Envelope
|
||||
|
||||
**Example ACP Messages:**
|
||||
All messages follow a standard envelope format:
|
||||
|
||||
*Progress Update:*
|
||||
```json
|
||||
{
|
||||
"type": "progress",
|
||||
"timestamp": "2026-01-09T10:30:15Z",
|
||||
"agent_id": "uuid",
|
||||
"task_id": "uuid",
|
||||
"data": {
|
||||
"id": "correlation-uuid",
|
||||
"type": "request|response|notification|error",
|
||||
"action": "action.name",
|
||||
"payload": {},
|
||||
"timestamp": "2026-01-10T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `id` | Correlation UUID to match requests with responses |
|
||||
| `type` | Message type: `request`, `response`, `notification`, or `error` |
|
||||
| `action` | The action being performed (see action tables below) |
|
||||
| `payload` | Action-specific data |
|
||||
| `timestamp` | ISO 8601 timestamp |
|
||||
|
||||
### 5.3 Request/Response Actions (Client → Server → Client)
|
||||
|
||||
#### Health Check
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `health.check` | Health check |
|
||||
|
||||
#### Board Management
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `board.list` | List boards |
|
||||
| `board.create` | Create board |
|
||||
| `board.get` | Get board by ID |
|
||||
| `board.update` | Update board |
|
||||
| `board.delete` | Delete board |
|
||||
| `column.list` | List columns for a board |
|
||||
| `column.create` | Create column |
|
||||
|
||||
#### Task Management
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `task.list` | List tasks (with filtering) |
|
||||
| `task.create` | Create task |
|
||||
| `task.get` | Get task details |
|
||||
| `task.update` | Update task |
|
||||
| `task.delete` | Delete task |
|
||||
| `task.move` | Move task to different column/position |
|
||||
| `task.state` | Update task state |
|
||||
|
||||
#### Agent Management
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `agent.list` | List all agent instances |
|
||||
| `agent.launch` | Launch agent for a task |
|
||||
| `agent.status` | Get agent status |
|
||||
| `agent.logs` | Get agent logs |
|
||||
| `agent.stop` | Stop a running agent |
|
||||
| `agent.prompt` | Send prompt to agent |
|
||||
| `agent.cancel` | Cancel agent execution |
|
||||
| `agent.session` | Get agent session info |
|
||||
| `agent.types` | List available agent types |
|
||||
|
||||
#### Orchestrator Control
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `orchestrator.status` | Get orchestrator status and metrics |
|
||||
| `orchestrator.queue` | View current task queue |
|
||||
| `orchestrator.trigger` | Manually trigger orchestration for a task |
|
||||
| `orchestrator.start` | Start agent execution for a task |
|
||||
| `orchestrator.stop` | Stop agent execution for a task |
|
||||
| `orchestrator.prompt` | Send prompt to orchestrator |
|
||||
| `orchestrator.complete` | Mark task as complete |
|
||||
|
||||
### 5.4 Notification Types (Server → Client)
|
||||
|
||||
Notifications are pushed from the server without a prior request. They use `type: "notification"`.
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| `acp.progress` | Agent progress update (0-100%) |
|
||||
| `acp.log` | Agent log message |
|
||||
| `acp.result` | Agent result (intermediate or final) |
|
||||
| `acp.error` | Agent error |
|
||||
| `acp.status` | Agent status change |
|
||||
| `acp.heartbeat` | Keep-alive heartbeat |
|
||||
| `task.updated` | Task was updated |
|
||||
| `agent.updated` | Agent status changed |
|
||||
|
||||
### 5.5 Example Messages
|
||||
|
||||
**Request: Create Task**
|
||||
```json
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"type": "request",
|
||||
"action": "task.create",
|
||||
"payload": {
|
||||
"board_id": "board-uuid",
|
||||
"title": "Implement user authentication",
|
||||
"description": "Add JWT-based authentication",
|
||||
"priority": 5,
|
||||
"agent_type": "auggie-cli"
|
||||
},
|
||||
"timestamp": "2026-01-10T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Response: Task Created**
|
||||
```json
|
||||
{
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"type": "response",
|
||||
"action": "task.create",
|
||||
"payload": {
|
||||
"task": {
|
||||
"id": "task-uuid",
|
||||
"board_id": "board-uuid",
|
||||
"title": "Implement user authentication",
|
||||
"description": "Add JWT-based authentication",
|
||||
"state": "TODO",
|
||||
"priority": 5,
|
||||
"agent_type": "auggie-cli",
|
||||
"created_at": "2026-01-10T10:30:00Z"
|
||||
}
|
||||
},
|
||||
"timestamp": "2026-01-10T10:30:01Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Request: Launch Agent**
|
||||
```json
|
||||
{
|
||||
"id": "660e8400-e29b-41d4-a716-446655440001",
|
||||
"type": "request",
|
||||
"action": "agent.launch",
|
||||
"payload": {
|
||||
"task_id": "task-uuid",
|
||||
"agent_type": "auggie-cli"
|
||||
},
|
||||
"timestamp": "2026-01-10T10:31:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Notification: ACP Progress**
|
||||
```json
|
||||
{
|
||||
"id": "770e8400-e29b-41d4-a716-446655440002",
|
||||
"type": "notification",
|
||||
"action": "acp.progress",
|
||||
"payload": {
|
||||
"agent_id": "agent-uuid",
|
||||
"task_id": "task-uuid",
|
||||
"progress": 45,
|
||||
"message": "Analyzing file: src/main.go",
|
||||
"current_file": "src/main.go",
|
||||
"files_processed": 23,
|
||||
"total_files": 51
|
||||
}
|
||||
},
|
||||
"timestamp": "2026-01-10T10:32:15Z"
|
||||
}
|
||||
```
|
||||
|
||||
*Log Message:*
|
||||
**Notification: ACP Log**
|
||||
```json
|
||||
{
|
||||
"type": "log",
|
||||
"timestamp": "2026-01-09T10:30:16Z",
|
||||
"agent_id": "uuid",
|
||||
"task_id": "uuid",
|
||||
"data": {
|
||||
"id": "880e8400-e29b-41d4-a716-446655440003",
|
||||
"type": "notification",
|
||||
"action": "acp.log",
|
||||
"payload": {
|
||||
"agent_id": "agent-uuid",
|
||||
"task_id": "task-uuid",
|
||||
"level": "info",
|
||||
"message": "Found 3 potential issues in authentication module",
|
||||
"metadata": {
|
||||
"module": "auth",
|
||||
"issues": 3
|
||||
}
|
||||
}
|
||||
},
|
||||
"timestamp": "2026-01-10T10:32:16Z"
|
||||
}
|
||||
```
|
||||
|
||||
*Result Message:*
|
||||
**Notification: ACP Result**
|
||||
```json
|
||||
{
|
||||
"type": "result",
|
||||
"timestamp": "2026-01-09T10:35:00Z",
|
||||
"agent_id": "uuid",
|
||||
"task_id": "uuid",
|
||||
"data": {
|
||||
"id": "990e8400-e29b-41d4-a716-446655440004",
|
||||
"type": "notification",
|
||||
"action": "acp.result",
|
||||
"payload": {
|
||||
"agent_id": "agent-uuid",
|
||||
"task_id": "task-uuid",
|
||||
"status": "completed",
|
||||
"summary": "Analysis complete. Found 12 issues, suggested 8 improvements.",
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "report",
|
||||
"path": "/workspace/analysis_report.md",
|
||||
"url": "/api/v1/tasks/{taskId}/artifacts/report.md"
|
||||
"path": "/workspace/analysis_report.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"timestamp": "2026-01-10T10:35:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**`WS /api/v1/orchestrator/stream`**
|
||||
- Global WebSocket endpoint for all task updates
|
||||
- Streams ACP messages from all tasks user has access to
|
||||
- **Auth:** Required (JWT)
|
||||
- **Filtering:** Client can subscribe to specific tasks
|
||||
|
||||
**Subscription Message:**
|
||||
**Error Response**
|
||||
```json
|
||||
{
|
||||
"action": "subscribe",
|
||||
"task_ids": ["uuid1", "uuid2"]
|
||||
"id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"type": "error",
|
||||
"action": "task.create",
|
||||
"payload": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Title is required",
|
||||
"details": {
|
||||
"field": "title"
|
||||
}
|
||||
},
|
||||
"timestamp": "2026-01-10T10:30:01Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### Agent Execution Logs (REST)
|
||||
### 5.6 Connection Flow
|
||||
|
||||
**`GET /api/v1/orchestrator/tasks/{taskId}/logs`**
|
||||
- Get historical logs for a task's agent execution
|
||||
- **Query Params:**
|
||||
- `?level=info,warn,error` - Filter by log level
|
||||
- `?since=2026-01-09T10:00:00Z` - Logs since timestamp
|
||||
- `?limit=100&offset=0` - Pagination
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"logs": [
|
||||
{
|
||||
"timestamp": "2026-01-09T10:30:00Z",
|
||||
"level": "info",
|
||||
"message": "Starting code analysis...",
|
||||
"metadata": {}
|
||||
}
|
||||
],
|
||||
"total": 245
|
||||
```javascript
|
||||
// 1. Connect to WebSocket
|
||||
const ws = new WebSocket('ws://localhost:8080/ws?token=JWT_TOKEN');
|
||||
|
||||
// 2. Handle connection open
|
||||
ws.onopen = () => {
|
||||
console.log('Connected to Kandev WebSocket');
|
||||
};
|
||||
|
||||
// 3. Send requests
|
||||
function sendRequest(action, payload) {
|
||||
const id = crypto.randomUUID();
|
||||
ws.send(JSON.stringify({
|
||||
id,
|
||||
type: 'request',
|
||||
action,
|
||||
payload,
|
||||
timestamp: new Date().toISOString()
|
||||
}));
|
||||
return id;
|
||||
}
|
||||
|
||||
// 4. Handle incoming messages
|
||||
ws.onmessage = (event) => {
|
||||
const message = JSON.parse(event.data);
|
||||
|
||||
switch (message.type) {
|
||||
case 'response':
|
||||
handleResponse(message);
|
||||
break;
|
||||
case 'notification':
|
||||
handleNotification(message);
|
||||
break;
|
||||
case 'error':
|
||||
handleError(message);
|
||||
break;
|
||||
}
|
||||
```
|
||||
- **Auth:** Required (JWT)
|
||||
};
|
||||
|
||||
**`GET /api/v1/orchestrator/tasks/{taskId}/artifacts`**
|
||||
- List artifacts generated by agent
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"artifacts": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "analysis_report.md",
|
||||
"type": "report",
|
||||
"size": 12458,
|
||||
"created_at": "2026-01-09T10:35:00Z",
|
||||
"download_url": "/api/v1/tasks/{taskId}/artifacts/{artifactId}/download"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
- **Auth:** Required (JWT)
|
||||
// 5. Example: List boards
|
||||
sendRequest('board.list', {});
|
||||
|
||||
**`GET /api/v1/orchestrator/tasks/{taskId}/artifacts/{artifactId}/download`**
|
||||
- Download artifact file
|
||||
- **Response:** File download
|
||||
- **Auth:** Required (JWT)
|
||||
// 6. Example: Launch agent and receive streaming updates
|
||||
sendRequest('agent.launch', { task_id: 'task-uuid', agent_type: 'auggie-cli' });
|
||||
// Notifications (acp.progress, acp.log, acp.result) will stream automatically
|
||||
```
|
||||
|
||||
## 5. Go Package Structure
|
||||
## 6. Go Package Structure
|
||||
|
||||
```
|
||||
kandev/
|
||||
@@ -765,15 +759,16 @@ kandev/
|
||||
│ │ ├── errors/ # Error types and handling
|
||||
│ │ └── acp/ # ACP protocol implementation
|
||||
│ ├── gateway/
|
||||
│ │ ├── router/
|
||||
│ │ ├── middleware/
|
||||
│ │ ├── handlers/
|
||||
│ │ ├── websocket/ # WebSocket connection management
|
||||
│ │ ├── websocket/ # WebSocket connection & message handling
|
||||
│ │ ├── dispatcher/ # Message routing to services
|
||||
│ │ ├── middleware/ # Auth, logging, rate limiting
|
||||
│ │ ├── broadcast/ # Notification broadcasting
|
||||
│ │ └── streaming/ # ACP stream multiplexing
|
||||
│ ├── task/
|
||||
│ │ ├── models/
|
||||
│ │ ├── repository/
|
||||
│ │ ├── service/
|
||||
│ │ ├── handlers/ # WebSocket message handlers
|
||||
│ │ └── events/
|
||||
│ ├── orchestrator/
|
||||
│ │ ├── watcher/
|
||||
@@ -782,7 +777,7 @@ kandev/
|
||||
│ │ ├── queue/
|
||||
│ │ ├── acp/ # ACP protocol handler
|
||||
│ │ ├── streaming/ # Real-time stream management
|
||||
│ │ └── api/ # REST API handlers
|
||||
│ │ └── handlers/ # WebSocket message handlers
|
||||
│ ├── agent/
|
||||
│ │ ├── models/
|
||||
│ │ ├── docker/
|
||||
@@ -791,7 +786,7 @@ kandev/
|
||||
│ │ ├── monitor/
|
||||
│ │ ├── acp/ # ACP stream handling
|
||||
│ │ ├── credentials/ # Host credential management
|
||||
│ │ └── streaming/ # Container stream handling
|
||||
│ │ └── handlers/ # WebSocket message handlers
|
||||
│ └── events/
|
||||
│ ├── bus/ # Event bus abstraction
|
||||
│ ├── publisher/
|
||||
@@ -799,6 +794,10 @@ kandev/
|
||||
├── pkg/
|
||||
│ ├── api/
|
||||
│ │ └── v1/ # API models (shared)
|
||||
│ ├── websocket/
|
||||
│ │ ├── message/ # WebSocket message envelope types
|
||||
│ │ ├── handler/ # Handler interface definitions
|
||||
│ │ └── router/ # Action routing utilities
|
||||
│ └── acp/
|
||||
│ ├── protocol/ # ACP protocol definitions
|
||||
│ ├── client/ # ACP client library
|
||||
@@ -816,7 +815,7 @@ kandev/
|
||||
└── go.sum
|
||||
```
|
||||
|
||||
## 6. Core Data Structures
|
||||
## 7. Core Data Structures
|
||||
|
||||
### 6.1 Task Models
|
||||
|
||||
@@ -947,7 +946,7 @@ type AgentLog struct {
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Docker Integration Strategy
|
||||
## 8. Docker Integration Strategy
|
||||
|
||||
### 7.1 Docker SDK Usage
|
||||
|
||||
@@ -1206,7 +1205,7 @@ func CheckoutRepository(taskID, repoURL, branch string) (string, error) {
|
||||
6. **No Credential Storage**: Never store credentials in database
|
||||
7. **Container Network Isolation**: Limit network access from containers
|
||||
|
||||
## 8. Inter-Service Communication
|
||||
## 9. Inter-Service Communication
|
||||
|
||||
### 8.1 Event Bus (NATS)
|
||||
|
||||
@@ -1234,16 +1233,53 @@ type Event struct {
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 Agent Communication Protocol (ACP) Flow
|
||||
### 8.2 WebSocket Message Flow
|
||||
|
||||
**ACP Message Flow Through System:**
|
||||
**Client Request Flow:**
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Frontend UI │
|
||||
└──────┬───────┘
|
||||
│ WebSocket Message (request)
|
||||
│ ws://localhost:8080/ws
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ API Gateway │ ← Maintains WebSocket connections
|
||||
│ (Dispatcher) │ Routes messages by action prefix
|
||||
└──────┬───────┘
|
||||
│ Internal routing
|
||||
├──────────────┬──────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌────────────┐ ┌────────────┐
|
||||
│ Task │ │Orchestrator│ │Agent │
|
||||
│ Handlers │ │ Handlers │ │Handlers │
|
||||
└──────────┘ └────────────┘ └────────────┘
|
||||
│ │ │
|
||||
└──────────────┴──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ API Gateway │ ← Sends response back
|
||||
│ (WebSocket) │
|
||||
└──────┬───────┘
|
||||
│ WebSocket Message (response)
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Frontend UI │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### 8.3 ACP Notification Flow (Agent → Client)
|
||||
|
||||
**Real-time Agent Updates:**
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ AI Agent │
|
||||
│ Container │
|
||||
└──────┬───────┘
|
||||
│ ACP Messages (stdout/HTTP)
|
||||
│ ACP Messages (stdout)
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Agent │
|
||||
@@ -1260,12 +1296,13 @@ type Event struct {
|
||||
┌──────────────┐
|
||||
│ Orchestrator │ ← Aggregates ACP messages
|
||||
└──────┬───────┘
|
||||
│ WebSocket broadcast
|
||||
│ Publishes notification event
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ API Gateway │ ← Proxies WebSocket to frontend
|
||||
│ API Gateway │ ← Broadcasts to connected WebSocket clients
|
||||
│ (Broadcast) │
|
||||
└──────┬───────┘
|
||||
│ WebSocket
|
||||
│ WebSocket Notification (acp.progress, acp.log, etc.)
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Frontend UI │ ← Displays real-time updates
|
||||
@@ -1282,21 +1319,32 @@ func PublishACPMessage(nc *nats.Conn, taskID string, msg ACPMessage) error {
|
||||
}
|
||||
```
|
||||
|
||||
**ACP Message Subscription:**
|
||||
**WebSocket Notification Broadcasting:**
|
||||
```go
|
||||
// internal/orchestrator/acp/subscriber.go
|
||||
func SubscribeToTaskACP(nc *nats.Conn, taskID string, handler func(ACPMessage)) error {
|
||||
subject := fmt.Sprintf("acp.message.%s", taskID)
|
||||
_, err := nc.Subscribe(subject, func(m *nats.Msg) {
|
||||
var msg ACPMessage
|
||||
json.Unmarshal(m.Data, &msg)
|
||||
handler(msg)
|
||||
})
|
||||
return err
|
||||
// internal/gateway/broadcast/broadcaster.go
|
||||
func BroadcastNotification(action string, payload interface{}) {
|
||||
msg := WebSocketMessage{
|
||||
ID: uuid.New().String(),
|
||||
Type: "notification",
|
||||
Action: action,
|
||||
Payload: payload,
|
||||
Timestamp: time.Now().UTC(),
|
||||
}
|
||||
// Send to all connected clients subscribed to this task
|
||||
hub.BroadcastToSubscribers(msg)
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 Communication Patterns
|
||||
### 8.4 Communication Patterns
|
||||
|
||||
**Frontend → API Gateway (WebSocket):**
|
||||
- Single persistent WebSocket connection per client
|
||||
- Request/response pattern with correlation IDs
|
||||
- Real-time notifications pushed to client
|
||||
|
||||
**API Gateway → Services:**
|
||||
- Routes messages based on action prefix (`task.*`, `agent.*`, `orchestrator.*`)
|
||||
- Maintains connection state and authentication context
|
||||
|
||||
**Task Service → Event Bus:**
|
||||
- Publishes task lifecycle events
|
||||
@@ -1316,13 +1364,12 @@ func SubscribeToTaskACP(nc *nats.Conn, taskID string, handler func(ACPMessage))
|
||||
- Direct gRPC calls for agent operations
|
||||
- Request agent launch/stop/status
|
||||
|
||||
**Orchestrator → Frontend (via API Gateway):**
|
||||
- WebSocket connections for real-time ACP streaming
|
||||
- REST API for status queries and control
|
||||
**Orchestrator → API Gateway:**
|
||||
- Publishes notification events for WebSocket broadcast
|
||||
- Uses NATS for inter-service notification delivery
|
||||
|
||||
**Agent Container → Agent Manager:**
|
||||
- ACP messages via stdout (captured by Docker logs API)
|
||||
- Alternative: HTTP endpoint for structured ACP messages
|
||||
|
||||
### 8.4 ACP Protocol Implementation
|
||||
|
||||
@@ -1393,7 +1440,7 @@ func CaptureContainerACP(ctx context.Context, containerID string, taskID string)
|
||||
}
|
||||
```
|
||||
|
||||
## 9. Key Go Dependencies
|
||||
## 10. Key Go Dependencies
|
||||
|
||||
```go
|
||||
// go.mod
|
||||
@@ -1432,7 +1479,7 @@ require (
|
||||
)
|
||||
```
|
||||
|
||||
## 10. Implementation Phases
|
||||
## 11. Implementation Phases
|
||||
|
||||
### Phase 1: Foundation (Week 1-2)
|
||||
**Goal:** Set up project structure and core infrastructure
|
||||
@@ -1461,7 +1508,7 @@ require (
|
||||
1. Implement task repository layer
|
||||
2. Implement task service layer with business logic
|
||||
3. Create task event publishers
|
||||
4. Build REST API handlers for tasks
|
||||
4. Build WebSocket handlers for tasks
|
||||
5. Add validation and error handling
|
||||
6. Write unit tests for task service
|
||||
|
||||
@@ -1504,7 +1551,7 @@ require (
|
||||
3. Create executor that coordinates with Agent Manager
|
||||
4. **Implement ACP message aggregation from NATS**
|
||||
5. **Build WebSocket endpoint for real-time streaming**
|
||||
6. **Create comprehensive Orchestrator REST API**
|
||||
6. **Create comprehensive Orchestrator WebSocket API**
|
||||
7. Implement retry logic
|
||||
8. Add workload balancing
|
||||
9. Write end-to-end tests
|
||||
@@ -1514,7 +1561,7 @@ require (
|
||||
- Task queue management
|
||||
- **Real-time ACP streaming to clients**
|
||||
- **WebSocket API for frontend integration**
|
||||
- **Complete Orchestrator REST API**
|
||||
- **Complete Orchestrator WebSocket API**
|
||||
- Retry and error handling
|
||||
- Orchestration monitoring
|
||||
|
||||
@@ -1522,7 +1569,7 @@ require (
|
||||
**Goal:** Unified API entry point with WebSocket support
|
||||
|
||||
**Tasks:**
|
||||
1. Implement HTTP router and middleware
|
||||
1. Implement WebSocket router and middleware
|
||||
2. Add JWT authentication
|
||||
3. **Implement WebSocket connection management**
|
||||
4. **Create ACP stream proxying to frontend**
|
||||
@@ -1557,7 +1604,7 @@ require (
|
||||
- Deployment documentation
|
||||
- Monitoring dashboards
|
||||
|
||||
## 11. Configuration Management
|
||||
## 12. Configuration Management
|
||||
|
||||
### 11.1 Configuration Structure
|
||||
|
||||
@@ -1655,7 +1702,7 @@ LOG_FORMAT=json
|
||||
LOG_OUTPUT_PATH=stdout
|
||||
```
|
||||
|
||||
## 12. Security Considerations
|
||||
## 13. Security Considerations
|
||||
|
||||
### 12.1 Authentication & Authorization
|
||||
- JWT-based authentication for API requests
|
||||
@@ -1680,7 +1727,7 @@ LOG_OUTPUT_PATH=stdout
|
||||
- SQL injection prevention (parameterized queries)
|
||||
- Rate limiting on API endpoints
|
||||
|
||||
## 13. Monitoring & Observability
|
||||
## 14. Monitoring & Observability
|
||||
|
||||
### 13.1 Metrics (Prometheus)
|
||||
- Task creation/completion rates
|
||||
@@ -1705,7 +1752,7 @@ LOG_OUTPUT_PATH=stdout
|
||||
- Request flow visualization
|
||||
- Performance bottleneck identification
|
||||
|
||||
## 14. Next Steps
|
||||
## 15. Next Steps
|
||||
|
||||
### Immediate Actions:
|
||||
1. **Review and approve this implementation plan**
|
||||
@@ -1728,7 +1775,7 @@ LOG_OUTPUT_PATH=stdout
|
||||
- **ACP protocol library**
|
||||
- **Initial agent Docker images**
|
||||
|
||||
## 15. Deployment Architecture
|
||||
## 16. Deployment Architecture
|
||||
|
||||
### 15.1 Primary Deployment Target: Client Machines
|
||||
|
||||
@@ -1905,14 +1952,14 @@ echo "Access the API at http://localhost:8080"
|
||||
### Questions Answered:
|
||||
|
||||
1. **Agent Types:** ✅ **Auggie CLI and Gemini agents** (documented in Section 3.2 and 4)
|
||||
2. **Repository Access:** ✅ **Host credential mounting** (documented in Section 7.4)
|
||||
2. **Repository Access:** ✅ **Host credential mounting** (documented in Section 8.4)
|
||||
3. **Scaling:** ✅ **Single-user local deployment initially, cloud scaling in roadmap**
|
||||
4. **Deployment:** ✅ **Client machines (local workstations)** (documented in Section 15)
|
||||
5. **Frontend Integration:** ✅ **JWT authentication + WebSocket for real-time streaming** (documented in Section 4.3)
|
||||
4. **Deployment:** ✅ **Client machines (local workstations)** (documented in Section 16)
|
||||
5. **Frontend Integration:** ✅ **JWT authentication + WebSocket API for real-time streaming** (documented in Section 5)
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Last Updated:** 2026-01-09
|
||||
**Document Version:** 1.1
|
||||
**Last Updated:** 2026-01-10
|
||||
**Author:** Kandev Backend Team
|
||||
|
||||
|
||||
@@ -0,0 +1,408 @@
|
||||
asyncapi: 2.6.0
|
||||
info:
|
||||
title: Kandev WebSocket API
|
||||
description: |
|
||||
Kandev is a Kanban board system with AI agent orchestration capabilities.
|
||||
|
||||
## Overview
|
||||
- **Task Service**: Manages tasks, boards, and columns
|
||||
- **Agent Manager**: Manages Docker container lifecycle for AI agents
|
||||
- **Orchestrator**: Coordinates agent execution
|
||||
|
||||
## WebSocket Protocol
|
||||
All communication happens over a single WebSocket connection.
|
||||
Messages use a JSON envelope format with request/response correlation.
|
||||
|
||||
## Agent Communication Protocol (ACP)
|
||||
Agents communicate via JSON messages on stdout. Real-time updates are
|
||||
pushed to clients via WebSocket notifications.
|
||||
|
||||
⚠️ **This documentation must be updated when API changes.**
|
||||
version: 2.0.0
|
||||
contact:
|
||||
name: Kandev Team
|
||||
license:
|
||||
name: MIT
|
||||
|
||||
servers:
|
||||
development:
|
||||
url: ws://localhost:8080/ws
|
||||
protocol: ws
|
||||
description: Local development WebSocket server
|
||||
|
||||
defaultContentType: application/json
|
||||
|
||||
channels:
|
||||
/:
|
||||
publish:
|
||||
summary: Send messages to the server
|
||||
operationId: sendMessage
|
||||
message:
|
||||
oneOf:
|
||||
- $ref: '#/components/messages/Request'
|
||||
subscribe:
|
||||
summary: Receive messages from the server
|
||||
operationId: receiveMessage
|
||||
message:
|
||||
oneOf:
|
||||
- $ref: '#/components/messages/Response'
|
||||
- $ref: '#/components/messages/Notification'
|
||||
- $ref: '#/components/messages/Error'
|
||||
|
||||
components:
|
||||
messages:
|
||||
Request:
|
||||
name: Request
|
||||
title: Client Request
|
||||
summary: Request message from client to server
|
||||
contentType: application/json
|
||||
payload:
|
||||
$ref: '#/components/schemas/RequestEnvelope'
|
||||
|
||||
Response:
|
||||
name: Response
|
||||
title: Server Response
|
||||
summary: Response message from server to client
|
||||
contentType: application/json
|
||||
payload:
|
||||
$ref: '#/components/schemas/ResponseEnvelope'
|
||||
|
||||
Notification:
|
||||
name: Notification
|
||||
title: Server Notification
|
||||
summary: Push notification from server to client
|
||||
contentType: application/json
|
||||
payload:
|
||||
$ref: '#/components/schemas/NotificationEnvelope'
|
||||
|
||||
Error:
|
||||
name: Error
|
||||
title: Error Response
|
||||
summary: Error response from server
|
||||
contentType: application/json
|
||||
payload:
|
||||
$ref: '#/components/schemas/ErrorEnvelope'
|
||||
|
||||
schemas:
|
||||
# Message Envelopes
|
||||
RequestEnvelope:
|
||||
type: object
|
||||
required: [id, type, action, payload]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Correlation ID for request/response matching
|
||||
type:
|
||||
type: string
|
||||
enum: [request]
|
||||
action:
|
||||
type: string
|
||||
description: Action to perform
|
||||
enum:
|
||||
- health.check
|
||||
- board.list
|
||||
- board.create
|
||||
- board.get
|
||||
- board.update
|
||||
- board.delete
|
||||
- column.list
|
||||
- column.create
|
||||
- column.get
|
||||
- task.list
|
||||
- task.create
|
||||
- task.get
|
||||
- task.update
|
||||
- task.delete
|
||||
- task.move
|
||||
- task.state
|
||||
- task.subscribe
|
||||
- task.unsubscribe
|
||||
- agent.list
|
||||
- agent.launch
|
||||
- agent.status
|
||||
- agent.logs
|
||||
- agent.stop
|
||||
- agent.prompt
|
||||
- agent.cancel
|
||||
- agent.session
|
||||
- agent.types
|
||||
- orchestrator.status
|
||||
- orchestrator.queue
|
||||
- orchestrator.trigger
|
||||
- orchestrator.start
|
||||
- orchestrator.stop
|
||||
- orchestrator.prompt
|
||||
- orchestrator.complete
|
||||
payload:
|
||||
type: object
|
||||
description: Action-specific payload
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
ResponseEnvelope:
|
||||
type: object
|
||||
required: [id, type, action, payload]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Correlation ID matching the request
|
||||
type:
|
||||
type: string
|
||||
enum: [response]
|
||||
action:
|
||||
type: string
|
||||
description: Action that was performed
|
||||
payload:
|
||||
type: object
|
||||
description: Response data
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
NotificationEnvelope:
|
||||
type: object
|
||||
required: [type, action, payload]
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum: [notification]
|
||||
action:
|
||||
type: string
|
||||
description: Notification type
|
||||
enum:
|
||||
- acp.progress
|
||||
- acp.log
|
||||
- acp.result
|
||||
- acp.error
|
||||
- acp.status
|
||||
- acp.heartbeat
|
||||
- task.updated
|
||||
- agent.updated
|
||||
payload:
|
||||
type: object
|
||||
description: Notification data
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
ErrorEnvelope:
|
||||
type: object
|
||||
required: [id, type, action, payload]
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Correlation ID matching the request
|
||||
type:
|
||||
type: string
|
||||
enum: [error]
|
||||
action:
|
||||
type: string
|
||||
description: Action that failed
|
||||
payload:
|
||||
$ref: '#/components/schemas/ErrorPayload'
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
ErrorPayload:
|
||||
type: object
|
||||
required: [code, message]
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: Error code
|
||||
message:
|
||||
type: string
|
||||
description: Human readable message
|
||||
details:
|
||||
type: object
|
||||
description: Additional error details
|
||||
|
||||
# Domain Models (keep from openapi.yaml)
|
||||
Board:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
required: [id, name, created_at, updated_at]
|
||||
|
||||
Column:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
board_id:
|
||||
type: string
|
||||
format: uuid
|
||||
name:
|
||||
type: string
|
||||
position:
|
||||
type: integer
|
||||
state:
|
||||
type: string
|
||||
enum: [TODO, IN_PROGRESS, DONE]
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
required: [id, board_id, name, position, created_at]
|
||||
|
||||
Task:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
board_id:
|
||||
type: string
|
||||
format: uuid
|
||||
column_id:
|
||||
type: string
|
||||
format: uuid
|
||||
title:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
state:
|
||||
type: string
|
||||
enum: [TODO, IN_PROGRESS, BLOCKED, COMPLETED, FAILED, CANCELLED]
|
||||
priority:
|
||||
type: integer
|
||||
agent_type:
|
||||
type: string
|
||||
position:
|
||||
type: integer
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
metadata:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
required: [id, board_id, column_id, title, state, created_at, updated_at]
|
||||
|
||||
AgentInstance:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
task_id:
|
||||
type: string
|
||||
format: uuid
|
||||
agent_type:
|
||||
type: string
|
||||
container_id:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
enum: [starting, running, completed, failed, stopped, READY]
|
||||
progress:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 100
|
||||
started_at:
|
||||
type: string
|
||||
format: date-time
|
||||
finished_at:
|
||||
type: string
|
||||
format: date-time
|
||||
exit_code:
|
||||
type: integer
|
||||
error_message:
|
||||
type: string
|
||||
metadata:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
required: [id, task_id, agent_type, status, progress, started_at]
|
||||
|
||||
AgentType:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
image:
|
||||
type: string
|
||||
capabilities:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
enabled:
|
||||
type: boolean
|
||||
required: [id, name, image, enabled]
|
||||
|
||||
# ACP Notification Payloads
|
||||
ACPProgress:
|
||||
type: object
|
||||
properties:
|
||||
agent_id:
|
||||
type: string
|
||||
task_id:
|
||||
type: string
|
||||
progress:
|
||||
type: integer
|
||||
message:
|
||||
type: string
|
||||
current_file:
|
||||
type: string
|
||||
files_processed:
|
||||
type: integer
|
||||
total_files:
|
||||
type: integer
|
||||
|
||||
ACPLog:
|
||||
type: object
|
||||
properties:
|
||||
agent_id:
|
||||
type: string
|
||||
task_id:
|
||||
type: string
|
||||
level:
|
||||
type: string
|
||||
enum: [debug, info, warn, error]
|
||||
message:
|
||||
type: string
|
||||
metadata:
|
||||
type: object
|
||||
|
||||
ACPResult:
|
||||
type: object
|
||||
properties:
|
||||
agent_id:
|
||||
type: string
|
||||
task_id:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
summary:
|
||||
type: string
|
||||
artifacts:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
path:
|
||||
type: string
|
||||
-1293
File diff suppressed because it is too large
Load Diff
+75
-47
@@ -2,11 +2,13 @@
|
||||
#
|
||||
# End-to-End Test for Kandev
|
||||
# This script tests the complete flow from task creation to agent execution
|
||||
# using WebSocket-based communication with the backend.
|
||||
#
|
||||
# Prerequisites:
|
||||
# - Docker running with kandev/augment-agent:latest image built
|
||||
# - Augment session credentials in ~/.augment/session.json
|
||||
# - Port 8080 available
|
||||
# - websocat installed (cargo install websocat or brew install websocat)
|
||||
#
|
||||
# Usage: ./scripts/e2e-test.sh [--build]
|
||||
# --build Build the Docker image before running tests
|
||||
@@ -26,7 +28,7 @@ NC='\033[0m' # No Color
|
||||
|
||||
# Configuration
|
||||
SERVER_PORT=8080
|
||||
BASE_URL="http://localhost:${SERVER_PORT}"
|
||||
WS_URL="ws://localhost:${SERVER_PORT}/ws"
|
||||
AGENTCTL_PORT=9999
|
||||
WAIT_FOR_AGENT_SECONDS=120
|
||||
SERVER_PID=""
|
||||
@@ -78,10 +80,26 @@ log_info() {
|
||||
echo -e "${YELLOW}→ $1${NC}"
|
||||
}
|
||||
|
||||
# WebSocket helper function
|
||||
# Sends a request via WebSocket and returns the response
|
||||
ws_request() {
|
||||
local action=$1
|
||||
local payload=$2
|
||||
local id=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo "req-$$-$RANDOM")
|
||||
|
||||
# Compact the payload to single line (remove newlines and extra spaces)
|
||||
local compact_payload=$(echo "$payload" | jq -c '.')
|
||||
local message="{\"id\":\"${id}\",\"type\":\"request\",\"action\":\"${action}\",\"payload\":${compact_payload}}"
|
||||
|
||||
# Send request and get response (with timeout)
|
||||
echo "$message" | timeout 10 websocat -n1 "${WS_URL}" 2>/dev/null
|
||||
}
|
||||
|
||||
wait_for_server() {
|
||||
log_info "Waiting for server to be ready..."
|
||||
for i in {1..30}; do
|
||||
if curl -s "${BASE_URL}/health" > /dev/null 2>&1; then
|
||||
HEALTH=$(ws_request "health.check" '{}' 2>/dev/null)
|
||||
if echo "$HEALTH" | jq -e '.payload.status == "ok"' > /dev/null 2>&1; then
|
||||
log_success "Server is ready"
|
||||
return 0
|
||||
fi
|
||||
@@ -108,6 +126,14 @@ wait_for_agentctl() {
|
||||
# Check prerequisites
|
||||
log_step "Checking Prerequisites"
|
||||
|
||||
if ! command -v websocat &> /dev/null; then
|
||||
log_error "websocat is not installed"
|
||||
log_info "Install with: cargo install websocat"
|
||||
log_info "Or on macOS: brew install websocat"
|
||||
exit 1
|
||||
fi
|
||||
log_success "websocat is available"
|
||||
|
||||
if ! command -v docker &> /dev/null; then
|
||||
log_error "Docker is not installed"
|
||||
exit 1
|
||||
@@ -168,25 +194,21 @@ wait_for_server
|
||||
|
||||
# Run the E2E test
|
||||
log_step "Step 1: Create Board"
|
||||
BOARD=$(curl -s -X POST "${BASE_URL}/api/v1/boards" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "E2E Test Board", "description": "Automated end-to-end test"}')
|
||||
BOARD_ID=$(echo "$BOARD" | jq -r '.id')
|
||||
BOARD_RESPONSE=$(ws_request "board.create" '{"name": "E2E Test Board", "description": "Automated end-to-end test"}')
|
||||
BOARD_ID=$(echo "$BOARD_RESPONSE" | jq -r '.payload.id')
|
||||
if [ "$BOARD_ID" == "null" ] || [ -z "$BOARD_ID" ]; then
|
||||
log_error "Failed to create board"
|
||||
echo "$BOARD"
|
||||
echo "$BOARD_RESPONSE"
|
||||
exit 1
|
||||
fi
|
||||
log_success "Created board: $BOARD_ID"
|
||||
|
||||
log_step "Step 2: Create Column"
|
||||
COLUMN=$(curl -s -X POST "${BASE_URL}/api/v1/boards/${BOARD_ID}/columns" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "To Do", "position": 0}')
|
||||
COLUMN_ID=$(echo "$COLUMN" | jq -r '.id')
|
||||
COLUMN_RESPONSE=$(ws_request "column.create" "{\"board_id\": \"${BOARD_ID}\", \"name\": \"To Do\", \"position\": 0}")
|
||||
COLUMN_ID=$(echo "$COLUMN_RESPONSE" | jq -r '.payload.id')
|
||||
if [ "$COLUMN_ID" == "null" ] || [ -z "$COLUMN_ID" ]; then
|
||||
log_error "Failed to create column"
|
||||
echo "$COLUMN"
|
||||
echo "$COLUMN_RESPONSE"
|
||||
exit 1
|
||||
fi
|
||||
log_success "Created column: $COLUMN_ID"
|
||||
@@ -197,31 +219,32 @@ TEST_WORKSPACE=$(mktemp -d)
|
||||
log_info "Test workspace: $TEST_WORKSPACE"
|
||||
|
||||
# Create a simple task that creates a file
|
||||
TASK=$(curl -s -X POST "${BASE_URL}/api/v1/tasks" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"title\": \"E2E Test Task\",
|
||||
\"description\": \"Create a file named 'agent-result.txt' in the workspace root with the content 'Hello from Agent'. Do nothing else.\",
|
||||
\"board_id\": \"${BOARD_ID}\",
|
||||
\"column_id\": \"${COLUMN_ID}\",
|
||||
\"repository_url\": \"${TEST_WORKSPACE}\",
|
||||
\"agent_type\": \"augment-agent\"
|
||||
}")
|
||||
TASK_ID=$(echo "$TASK" | jq -r '.id')
|
||||
TASK_PAYLOAD=$(cat <<EOF
|
||||
{
|
||||
"title": "E2E Test Task",
|
||||
"description": "Create a file named 'agent-result.txt' in the workspace root with the content 'Hello from Agent'. Do nothing else.",
|
||||
"board_id": "${BOARD_ID}",
|
||||
"column_id": "${COLUMN_ID}",
|
||||
"repository_url": "${TEST_WORKSPACE}",
|
||||
"agent_type": "augment-agent"
|
||||
}
|
||||
EOF
|
||||
)
|
||||
TASK_RESPONSE=$(ws_request "task.create" "$TASK_PAYLOAD")
|
||||
TASK_ID=$(echo "$TASK_RESPONSE" | jq -r '.payload.id')
|
||||
if [ "$TASK_ID" == "null" ] || [ -z "$TASK_ID" ]; then
|
||||
log_error "Failed to create task"
|
||||
echo "$TASK"
|
||||
echo "$TASK_RESPONSE"
|
||||
exit 1
|
||||
fi
|
||||
log_success "Created task: $TASK_ID"
|
||||
|
||||
log_step "Step 4: Start Task via Orchestrator"
|
||||
START_RESULT=$(curl -s -X POST "${BASE_URL}/api/v1/orchestrator/tasks/${TASK_ID}/start" \
|
||||
-H "Content-Type: application/json")
|
||||
AGENT_ID=$(echo "$START_RESULT" | jq -r '.agent_instance_id')
|
||||
START_RESPONSE=$(ws_request "orchestrator.start" "{\"task_id\": \"${TASK_ID}\"}")
|
||||
AGENT_ID=$(echo "$START_RESPONSE" | jq -r '.payload.agent_instance_id')
|
||||
if [ "$AGENT_ID" == "null" ] || [ -z "$AGENT_ID" ]; then
|
||||
log_error "Failed to start task"
|
||||
echo "$START_RESULT"
|
||||
echo "$START_RESPONSE"
|
||||
exit 1
|
||||
fi
|
||||
log_success "Task started, agent ID: $AGENT_ID"
|
||||
@@ -275,8 +298,8 @@ AGENT_OUTPUT_FILE="${TEST_WORKSPACE}/agent-result.txt"
|
||||
AGENT_READY=false
|
||||
for i in $(seq 1 $WAIT_FOR_AGENT_SECONDS); do
|
||||
# Check agent status - READY means prompt completed
|
||||
AGENT_INFO=$(curl -s "${BASE_URL}/api/v1/agents/${AGENT_ID}/status" 2>/dev/null || echo '{}')
|
||||
AGENT_STATUS=$(echo "$AGENT_INFO" | jq -r '.status // "UNKNOWN"')
|
||||
AGENT_STATUS_RESPONSE=$(ws_request "agent.status" "{\"agent_id\": \"${AGENT_ID}\"}" 2>/dev/null || echo '{}')
|
||||
AGENT_STATUS=$(echo "$AGENT_STATUS_RESPONSE" | jq -r '.payload.status // "UNKNOWN"')
|
||||
|
||||
if [ "$AGENT_STATUS" == "READY" ]; then
|
||||
log_success "Agent is READY after $i seconds (prompt completed)"
|
||||
@@ -284,7 +307,7 @@ for i in $(seq 1 $WAIT_FOR_AGENT_SECONDS); do
|
||||
break
|
||||
elif [ "$AGENT_STATUS" == "FAILED" ]; then
|
||||
log_error "Agent failed"
|
||||
echo "$AGENT_INFO" | jq .
|
||||
echo "$AGENT_STATUS_RESPONSE" | jq .
|
||||
if [ -n "$CONTAINER_ID" ]; then
|
||||
log_info "Container logs:"
|
||||
docker logs "$CONTAINER_ID" 2>&1 | tail -30
|
||||
@@ -338,11 +361,12 @@ else
|
||||
fi
|
||||
|
||||
log_step "Step 9: Check Final State"
|
||||
FINAL_AGENTS=$(curl -s "${BASE_URL}/api/v1/agents" | jq '.total')
|
||||
AGENTS_RESPONSE=$(ws_request "agent.list" '{}')
|
||||
FINAL_AGENTS=$(echo "$AGENTS_RESPONSE" | jq '.payload.total')
|
||||
log_info "Total agents: $FINAL_AGENTS"
|
||||
|
||||
FINAL_TASK=$(curl -s "${BASE_URL}/api/v1/tasks/${TASK_ID}")
|
||||
TASK_STATE=$(echo "$FINAL_TASK" | jq -r '.state')
|
||||
TASK_RESPONSE=$(ws_request "task.get" "{\"id\": \"${TASK_ID}\"}")
|
||||
TASK_STATE=$(echo "$TASK_RESPONSE" | jq -r '.payload.state')
|
||||
log_info "Task state: $TASK_STATE"
|
||||
|
||||
log_step "Step 10: Verify First Prompt Output"
|
||||
@@ -361,22 +385,27 @@ fi
|
||||
log_step "Step 11: Test Multi-Turn - Send Follow-up Prompt"
|
||||
SECOND_OUTPUT_FILE="${TEST_WORKSPACE}/second-result.txt"
|
||||
log_info "Sending follow-up prompt..."
|
||||
PROMPT_RESULT=$(curl -s -X POST "${BASE_URL}/api/v1/orchestrator/tasks/${TASK_ID}/prompt" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"prompt\": \"Create another file named 'second-result.txt' with the content 'Follow-up successful'. Do nothing else.\"}")
|
||||
PROMPT_SUCCESS=$(echo "$PROMPT_RESULT" | jq -r '.success // false')
|
||||
PROMPT_PAYLOAD=$(cat <<EOF
|
||||
{
|
||||
"task_id": "${TASK_ID}",
|
||||
"prompt": "Create another file named 'second-result.txt' with the content 'Follow-up successful'. Do nothing else."
|
||||
}
|
||||
EOF
|
||||
)
|
||||
PROMPT_RESPONSE=$(ws_request "orchestrator.prompt" "$PROMPT_PAYLOAD")
|
||||
PROMPT_SUCCESS=$(echo "$PROMPT_RESPONSE" | jq -r '.payload.success // false')
|
||||
if [ "$PROMPT_SUCCESS" == "true" ]; then
|
||||
log_success "Follow-up prompt accepted"
|
||||
else
|
||||
log_error "Follow-up prompt failed: $(echo "$PROMPT_RESULT" | jq -r '.error // "unknown"')"
|
||||
log_error "Follow-up prompt failed: $(echo "$PROMPT_RESPONSE" | jq -r '.payload.error // "unknown"')"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wait for agent to become READY again (prompt completed)
|
||||
log_info "Waiting for agent to become READY again..."
|
||||
for i in $(seq 1 120); do
|
||||
AGENT_INFO=$(curl -s "${BASE_URL}/api/v1/agents/${AGENT_ID}/status" 2>/dev/null || echo '{}')
|
||||
AGENT_STATUS=$(echo "$AGENT_INFO" | jq -r '.status // "UNKNOWN"')
|
||||
AGENT_STATUS_RESPONSE=$(ws_request "agent.status" "{\"agent_id\": \"${AGENT_ID}\"}" 2>/dev/null || echo '{}')
|
||||
AGENT_STATUS=$(echo "$AGENT_STATUS_RESPONSE" | jq -r '.payload.status // "UNKNOWN"')
|
||||
if [ "$AGENT_STATUS" == "READY" ]; then
|
||||
log_success "Agent is READY after follow-up prompt ($i seconds)"
|
||||
break
|
||||
@@ -398,18 +427,17 @@ else
|
||||
fi
|
||||
|
||||
log_step "Step 12: Complete Task"
|
||||
COMPLETE_RESULT=$(curl -s -X POST "${BASE_URL}/api/v1/orchestrator/tasks/${TASK_ID}/complete" \
|
||||
-H "Content-Type: application/json")
|
||||
COMPLETE_SUCCESS=$(echo "$COMPLETE_RESULT" | jq -r '.success // false')
|
||||
COMPLETE_RESPONSE=$(ws_request "orchestrator.complete" "{\"task_id\": \"${TASK_ID}\"}")
|
||||
COMPLETE_SUCCESS=$(echo "$COMPLETE_RESPONSE" | jq -r '.payload.success // false')
|
||||
if [ "$COMPLETE_SUCCESS" == "true" ]; then
|
||||
log_success "Task completed successfully"
|
||||
else
|
||||
log_error "Failed to complete task: $(echo "$COMPLETE_RESULT" | jq -r '.error // "unknown"')"
|
||||
log_error "Failed to complete task: $(echo "$COMPLETE_RESPONSE" | jq -r '.payload.error // "unknown"')"
|
||||
fi
|
||||
|
||||
# Verify task state is COMPLETED
|
||||
FINAL_TASK=$(curl -s "${BASE_URL}/api/v1/tasks/${TASK_ID}")
|
||||
TASK_STATE=$(echo "$FINAL_TASK" | jq -r '.state')
|
||||
FINAL_TASK_RESPONSE=$(ws_request "task.get" "{\"id\": \"${TASK_ID}\"}")
|
||||
TASK_STATE=$(echo "$FINAL_TASK_RESPONSE" | jq -r '.payload.state')
|
||||
if [ "$TASK_STATE" == "COMPLETED" ]; then
|
||||
log_success "Task state is COMPLETED"
|
||||
else
|
||||
|
||||
Reference in New Issue
Block a user