From 4cd1e806ed3ec6ccf0c4f18458836d4132871a16 Mon Sep 17 00:00:00 2001 From: jcfs Date: Sat, 10 Jan 2026 23:09:22 +0000 Subject: [PATCH] docs: Add comprehensive WebSocket API reference Add docs/WEBSOCKET_API.md with complete documentation for all 32 WebSocket actions including: - Message envelope format and error codes - System flow diagram and typical workflow - Board, Column, Task CRUD operations - Task subscription for ACP streaming - Agent management (list, launch, status, logs, stop, types) - Orchestrator control (status, queue, start, stop, prompt, complete) - Server notifications (acp.progress, acp.log, acp.result, etc.) - Complete JavaScript usage example - Quick reference table Each action includes purpose, flow position, request/response examples, payload field tables, and side effects. --- docs/WEBSOCKET_API.md | 1558 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1558 insertions(+) create mode 100644 docs/WEBSOCKET_API.md diff --git a/docs/WEBSOCKET_API.md b/docs/WEBSOCKET_API.md new file mode 100644 index 0000000000..4196d7d2d6 --- /dev/null +++ b/docs/WEBSOCKET_API.md @@ -0,0 +1,1558 @@ +# Kandev WebSocket API Reference + +This document provides a complete reference for all WebSocket API actions, their payloads, responses, and usage patterns. + +## Overview + +Kandev uses a **single WebSocket connection** for all API operations and real-time streaming. This eliminates the need for separate REST endpoints and enables full-duplex communication. + +**Endpoint**: `ws://localhost:8080/ws` + +### Message Envelope + +All messages follow this JSON envelope format: + +```json +{ + "id": "uuid", + "type": "request|response|notification|error", + "action": "action.name", + "payload": {}, + "timestamp": "2026-01-10T12:00:00Z" +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | UUID for request/response correlation. Omit for notifications. | +| `type` | string | Message type: `request`, `response`, `notification`, or `error` | +| `action` | string | The action to perform or that was performed | +| `payload` | object | Action-specific data | +| `timestamp` | string | ISO 8601 timestamp (optional) | + +### Error Response Format + +```json +{ + "id": "correlation-uuid", + "type": "error", + "action": "original.action", + "payload": { + "code": "ERROR_CODE", + "message": "Human-readable message", + "details": {} + } +} +``` + +**Error Codes:** +- `BAD_REQUEST` - Invalid message format +- `VALIDATION_ERROR` - Missing or invalid fields +- `NOT_FOUND` - Resource not found +- `INTERNAL_ERROR` - Server error +- `UNKNOWN_ACTION` - Action not recognized + +--- + +## System Flow + +``` +┌─────────────┐ WebSocket ┌─────────────────────────────────────────────┐ +│ Client │◄──────────────────►│ Kandev Server │ +│ (Browser) │ Single Connection │ │ +└─────────────┘ │ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ + │ │ Task │ │ Agent │ │ Orchestrator │ │ + │ │ Service │ │ Manager │ │ Service │ │ + │ └─────────┘ └─────────┘ └──────────────┘ │ + │ │ │ + │ ┌──────▼──────┐ │ + │ │ Docker │ │ + │ │ Containers │ │ + │ └─────────────┘ │ + └─────────────────────────────────────────────┘ +``` + +### Typical Workflow + +1. **Connect** to `ws://localhost:8080/ws` +2. **Create Board** → `board.create` +3. **Create Column** → `column.create` +4. **Create Task** → `task.create` +5. **Subscribe to Task** → `task.subscribe` (receive real-time updates) +6. **Start Execution** → `orchestrator.start` (launches agent) +7. **Receive ACP Notifications** ← `acp.progress`, `acp.log`, etc. +8. **Send Follow-up Prompts** → `orchestrator.prompt` (multi-turn) +9. **Complete Task** → `orchestrator.complete` +10. **Unsubscribe** → `task.unsubscribe` + +--- + +## Health Check + +### `health.check` + +**Purpose:** Verify the WebSocket connection and server status. + +**Flow Position:** Can be called at any time to verify connectivity. + +**Request:** +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "type": "request", + "action": "health.check", + "payload": {} +} +``` + +**Response:** +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "type": "response", + "action": "health.check", + "payload": { + "status": "ok", + "service": "kandev", + "mode": "unified" + } +} +``` + +| Response Field | Type | Description | +|---------------|------|-------------| +| `status` | string | Server health status (`ok`) | +| `service` | string | Service name | +| `mode` | string | API mode (`unified` = WebSocket-only) | + +--- + +## Board Actions + +Boards are the top-level containers that organize columns and tasks. + +### `board.create` + +**Purpose:** Create a new Kanban board. + +**Flow Position:** First step - create a board before adding columns and tasks. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "board.create", + "payload": { + "name": "My Project", + "description": "Project description" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `name` | string | ✅ | Board name | +| `description` | string | ❌ | Optional description | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "board.create", + "payload": { + "id": "board-uuid", + "name": "My Project", + "description": "Project description", + "created_at": "2026-01-10T12:00:00Z", + "updated_at": "2026-01-10T12:00:00Z" + } +} +``` + +### `board.list` + +**Purpose:** List all boards. + +**Flow Position:** Use to display available boards to the user. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "board.list", + "payload": {} +} +``` + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "board.list", + "payload": { + "boards": [ + { + "id": "board-uuid", + "name": "My Project", + "description": "...", + "created_at": "2026-01-10T12:00:00Z", + "updated_at": "2026-01-10T12:00:00Z" + } + ], + "total": 1 + } +} +``` + +### `board.get` + +**Purpose:** Get a specific board by ID. + +**Flow Position:** Use to load board details before displaying columns and tasks. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "board.get", + "payload": { + "id": "board-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Board ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "board.get", + "payload": { + "id": "board-uuid", + "name": "My Project", + "description": "Project description", + "created_at": "2026-01-10T12:00:00Z", + "updated_at": "2026-01-10T12:00:00Z" + } +} +``` + +### `board.update` + +**Purpose:** Update an existing board's properties. + +**Flow Position:** Use when user edits board name or description. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "board.update", + "payload": { + "id": "board-uuid", + "name": "Updated Name", + "description": "Updated description" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Board ID | +| `name` | string | ❌ | New name (optional) | +| `description` | string | ❌ | New description (optional) | + +**Response:** Same as `board.get` + +### `board.delete` + +**Purpose:** Delete a board and all its columns and tasks. + +**Flow Position:** Use with caution - this is destructive. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "board.delete", + "payload": { + "id": "board-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Board ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "board.delete", + "payload": { + "success": true + } +} +``` + +--- + +## Column Actions + +Columns organize tasks within a board and represent workflow states. + +### `column.create` + +**Purpose:** Create a new column in a board. + +**Flow Position:** After creating a board, create columns for workflow stages. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "column.create", + "payload": { + "board_id": "board-uuid", + "name": "To Do", + "position": 0, + "state": "TODO" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `board_id` | string | ✅ | Parent board ID | +| `name` | string | ✅ | Column name | +| `position` | int | ❌ | Display order (0-indexed) | +| `state` | string | ❌ | Task state: `TODO`, `IN_PROGRESS`, `DONE` | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "column.create", + "payload": { + "id": "column-uuid", + "board_id": "board-uuid", + "name": "To Do", + "position": 0, + "state": "TODO", + "created_at": "2026-01-10T12:00:00Z" + } +} +``` + +### `column.list` + +**Purpose:** List all columns in a board. + +**Flow Position:** After loading a board, get its columns. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "column.list", + "payload": { + "board_id": "board-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `board_id` | string | ✅ | Board ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "column.list", + "payload": { + "columns": [ + { + "id": "column-uuid", + "board_id": "board-uuid", + "name": "To Do", + "position": 0, + "state": "TODO", + "created_at": "2026-01-10T12:00:00Z" + } + ], + "total": 1 + } +} +``` + +### `column.get` + +**Purpose:** Get a specific column by ID. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "column.get", + "payload": { + "id": "column-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Column ID | + +**Response:** Same structure as items in `column.list` + +--- + +## Task Actions + +Tasks are work items that can be executed by AI agents. + +### `task.create` + +**Purpose:** Create a new task in a column. + +**Flow Position:** Create tasks that agents will work on. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.create", + "payload": { + "board_id": "board-uuid", + "column_id": "column-uuid", + "title": "Implement feature X", + "description": "Detailed requirements...", + "priority": 1, + "agent_type": "auggie", + "repository_url": "https://github.com/org/repo", + "branch": "main", + "metadata": { + "labels": ["feature", "priority-high"] + } + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `board_id` | string | ✅ | Board ID | +| `column_id` | string | ✅ | Column ID | +| `title` | string | ✅ | Task title | +| `description` | string | ❌ | Detailed description | +| `priority` | int | ❌ | Priority level (higher = more important) | +| `agent_type` | string | ❌ | Agent to use: `auggie`, `gemini` | +| `repository_url` | string | ❌ | Git repository URL | +| `branch` | string | ❌ | Git branch | +| `metadata` | object | ❌ | Custom key-value data | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "task.create", + "payload": { + "id": "task-uuid", + "board_id": "board-uuid", + "column_id": "column-uuid", + "title": "Implement feature X", + "description": "Detailed requirements...", + "state": "TODO", + "priority": 1, + "agent_type": "auggie", + "repository_url": "https://github.com/org/repo", + "branch": "main", + "position": 0, + "created_at": "2026-01-10T12:00:00Z", + "updated_at": "2026-01-10T12:00:00Z", + "metadata": {} + } +} +``` + +| Response Field | Type | Description | +|---------------|------|-------------| +| `id` | string | Unique task ID | +| `state` | string | `TODO`, `IN_PROGRESS`, `BLOCKED`, `COMPLETED`, `FAILED`, `CANCELLED` | +| `position` | int | Position within column | + +### `task.list` + +**Purpose:** List all tasks in a board. + +**Flow Position:** Load tasks to display on the Kanban board. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.list", + "payload": { + "board_id": "board-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `board_id` | string | ✅ | Board ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "task.list", + "payload": { + "tasks": [ /* array of task objects */ ], + "total": 5 + } +} +``` + +### `task.get` + +**Purpose:** Get a specific task by ID. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.get", + "payload": { + "id": "task-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Task ID | + +**Response:** Same structure as `task.create` response + +### `task.update` + +**Purpose:** Update task properties (not state or position). + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.update", + "payload": { + "id": "task-uuid", + "title": "Updated title", + "description": "Updated description", + "priority": 2, + "metadata": { "key": "value" } + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Task ID | +| `title` | string | ❌ | New title | +| `description` | string | ❌ | New description | +| `priority` | int | ❌ | New priority | +| `metadata` | object | ❌ | Updated metadata | + +**Response:** Updated task object + +### `task.delete` + +**Purpose:** Delete a task. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.delete", + "payload": { + "id": "task-uuid" + } +} +``` + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "task.delete", + "payload": { + "success": true + } +} +``` + +### `task.move` + +**Purpose:** Move a task to a different column and/or position. + +**Flow Position:** Use for drag-and-drop on Kanban board. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.move", + "payload": { + "id": "task-uuid", + "column_id": "target-column-uuid", + "position": 0 + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Task ID | +| `column_id` | string | ✅ | Target column ID | +| `position` | int | ❌ | Position in column (0-indexed) | + +**Response:** Updated task object with new `column_id` and `position` + +### `task.state` + +**Purpose:** Update a task's state directly. + +**Flow Position:** Used by orchestrator to update task state during execution. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.state", + "payload": { + "id": "task-uuid", + "state": "IN_PROGRESS" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `id` | string | ✅ | Task ID | +| `state` | string | ✅ | New state: `TODO`, `IN_PROGRESS`, `BLOCKED`, `COMPLETED`, `FAILED`, `CANCELLED` | + +**Response:** Updated task object + + +--- + +## Task Subscription Actions + +Subscriptions enable real-time streaming of agent output (ACP) to specific clients. + +### `task.subscribe` + +**Purpose:** Subscribe to receive real-time notifications for a specific task. + +**Flow Position:** Call before `orchestrator.start` to receive agent output. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.subscribe", + "payload": { + "task_id": "task-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID to subscribe to | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "task.subscribe", + "payload": { + "success": true, + "task_id": "task-uuid" + } +} +``` + +**Effect:** After subscribing, you will receive notifications for this task: +- `acp.progress` - Progress updates +- `acp.log` - Agent log messages +- `acp.result` - Agent results +- `acp.error` - Agent errors +- `task.updated` - Task state changes + +### `task.unsubscribe` + +**Purpose:** Stop receiving notifications for a task. + +**Flow Position:** Call after task completes or when navigating away. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "task.unsubscribe", + "payload": { + "task_id": "task-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID to unsubscribe from | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "task.unsubscribe", + "payload": { + "success": true, + "task_id": "task-uuid" + } +} +``` + +--- + +## Agent Actions + +Agents are Docker containers running AI coding assistants. + +### `agent.list` + +**Purpose:** List all agent instances (running and completed). + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "agent.list", + "payload": {} +} +``` + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "agent.list", + "payload": { + "agents": [ + { + "id": "agent-uuid", + "task_id": "task-uuid", + "agent_type": "auggie", + "container_id": "docker-container-id", + "status": "running", + "progress": 45, + "started_at": "2026-01-10T12:00:00Z", + "finished_at": null, + "exit_code": null, + "error": null + } + ], + "total": 1 + } +} +``` + +| Response Field | Type | Description | +|---------------|------|-------------| +| `status` | string | `starting`, `running`, `completed`, `failed`, `stopped`, `READY` | +| `progress` | int | 0-100 percentage | +| `exit_code` | int | Container exit code (when completed) | +| `error` | string | Error message (if failed) | + +### `agent.launch` + +**Purpose:** Launch an agent container directly (low-level). + +**Flow Position:** Typically use `orchestrator.start` instead, which handles this automatically. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "agent.launch", + "payload": { + "task_id": "task-uuid", + "agent_type": "auggie", + "workspace_path": "/path/to/workspace", + "env": { + "CUSTOM_VAR": "value" + } + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID this agent is for | +| `agent_type` | string | ✅ | Agent type: `auggie`, `gemini` | +| `workspace_path` | string | ✅ | Path to mount in container | +| `env` | object | ❌ | Additional environment variables | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "agent.launch", + "payload": { + "success": true, + "agent_id": "agent-uuid", + "task_id": "task-uuid" + } +} +``` + +### `agent.status` + +**Purpose:** Get detailed status of a specific agent. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "agent.status", + "payload": { + "agent_id": "agent-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `agent_id` | string | ✅ | Agent instance ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "agent.status", + "payload": { + "id": "agent-uuid", + "task_id": "task-uuid", + "agent_type": "auggie", + "container_id": "docker-container-id", + "status": "running", + "progress": 67, + "started_at": "2026-01-10T12:00:00Z", + "finished_at": null, + "exit_code": null, + "error": null + } +} +``` + +### `agent.logs` + +**Purpose:** Get agent container logs. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "agent.logs", + "payload": { + "agent_id": "agent-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `agent_id` | string | ✅ | Agent instance ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "agent.logs", + "payload": { + "agent_id": "agent-uuid", + "logs": ["log line 1", "log line 2"], + "message": "..." + } +} +``` + +### `agent.stop` + +**Purpose:** Stop a running agent container. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "agent.stop", + "payload": { + "agent_id": "agent-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `agent_id` | string | ✅ | Agent instance ID | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "agent.stop", + "payload": { + "success": true + } +} +``` + +### `agent.types` + +**Purpose:** List available agent types. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "agent.types", + "payload": {} +} +``` + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "agent.types", + "payload": { + "types": [ + { + "id": "auggie", + "name": "Auggie CLI Agent", + "description": "Augment Code CLI-based coding agent", + "image": "ghcr.io/kandev/auggie-agent:latest", + "capabilities": ["code-generation", "refactoring", "testing"], + "enabled": true + }, + { + "id": "gemini", + "name": "Gemini Agent", + "description": "Google Gemini-based coding agent", + "image": "ghcr.io/kandev/gemini-agent:latest", + "capabilities": ["code-generation", "analysis"], + "enabled": true + } + ], + "total": 2 + } +} +``` + +--- + +## Orchestrator Actions + +The orchestrator coordinates task execution, managing the workflow between tasks and agents. + +### `orchestrator.status` + +**Purpose:** Get overall orchestrator status. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.status", + "payload": {} +} +``` + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.status", + "payload": { + "running": true, + "active_tasks": 2, + "queued_tasks": 5, + "max_concurrent": 3 + } +} +``` + +### `orchestrator.queue` + +**Purpose:** Get the current task queue. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.queue", + "payload": {} +} +``` + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.queue", + "payload": { + "tasks": [ + { + "task_id": "task-uuid", + "priority": 1, + "queued_at": "2026-01-10T12:00:00Z" + } + ], + "total": 1 + } +} +``` + +### `orchestrator.trigger` + +**Purpose:** Trigger a task for execution (adds to queue). + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.trigger", + "payload": { + "task_id": "task-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID to trigger | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.trigger", + "payload": { + "success": true, + "message": "Task triggered", + "task_id": "task-uuid" + } +} +``` + +### `orchestrator.start` + +**Purpose:** Start executing a task immediately with an agent. + +**Flow Position:** Main action to begin agent work on a task. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.start", + "payload": { + "task_id": "task-uuid", + "agent_type": "auggie", + "priority": 1 + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID to start | +| `agent_type` | string | ❌ | Override default agent type | +| `priority` | int | ❌ | Execution priority | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.start", + "payload": { + "success": true, + "task_id": "task-uuid", + "agent_instance_id": "agent-uuid", + "status": "running" + } +} +``` + +**Effect:** +1. Task state changes to `IN_PROGRESS` +2. Agent container is launched +3. ACP notifications begin streaming (if subscribed) + +### `orchestrator.stop` + +**Purpose:** Stop a running task execution. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.stop", + "payload": { + "task_id": "task-uuid", + "reason": "User cancelled", + "force": false + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID to stop | +| `reason` | string | ❌ | Reason for stopping | +| `force` | bool | ❌ | Force kill (default: false) | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.stop", + "payload": { + "success": true + } +} +``` + +### `orchestrator.prompt` + +**Purpose:** Send a follow-up prompt to a running agent (multi-turn conversation). + +**Flow Position:** Use during agent execution for clarifications or additional instructions. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.prompt", + "payload": { + "task_id": "task-uuid", + "prompt": "Also add unit tests for the new function" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID (must have running agent) | +| `prompt` | string | ✅ | Follow-up prompt text | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.prompt", + "payload": { + "success": true + } +} +``` + +**Effect:** The prompt is sent to the agent via `agentctl` HTTP sidecar. + +### `orchestrator.complete` + +**Purpose:** Mark a task as completed. + +**Flow Position:** Called when agent finishes successfully or user approves the work. + +**Request:** +```json +{ + "id": "uuid", + "type": "request", + "action": "orchestrator.complete", + "payload": { + "task_id": "task-uuid" + } +} +``` + +| Payload Field | Type | Required | Description | +|--------------|------|----------|-------------| +| `task_id` | string | ✅ | Task ID to complete | + +**Response:** +```json +{ + "id": "uuid", + "type": "response", + "action": "orchestrator.complete", + "payload": { + "success": true, + "message": "task completed" + } +} +``` + +--- + +## Server Notifications (ACP Streaming) + +These are push notifications from the server to subscribed clients. They have `type: "notification"` and no `id` field. + +### `acp.progress` + +**Purpose:** Agent progress update. + +**When:** Periodically during agent execution. + +```json +{ + "type": "notification", + "action": "acp.progress", + "payload": { + "task_id": "task-uuid", + "agent_id": "agent-uuid", + "progress": 45, + "message": "Analyzing code structure...", + "current_file": "src/main.go", + "files_processed": 12, + "total_files": 27 + }, + "timestamp": "2026-01-10T12:05:00Z" +} +``` + +### `acp.log` + +**Purpose:** Agent log message (debug, info, warn, error). + +**When:** As agent produces output. + +```json +{ + "type": "notification", + "action": "acp.log", + "payload": { + "task_id": "task-uuid", + "agent_id": "agent-uuid", + "level": "info", + "message": "Starting code generation for feature X", + "metadata": { + "component": "code-generator" + } + }, + "timestamp": "2026-01-10T12:05:30Z" +} +``` + +| Payload Field | Type | Description | +|--------------|------|-------------| +| `level` | string | `debug`, `info`, `warn`, `error` | + +### `acp.result` + +**Purpose:** Agent produced a result artifact. + +**When:** Agent completes a unit of work. + +```json +{ + "type": "notification", + "action": "acp.result", + "payload": { + "task_id": "task-uuid", + "agent_id": "agent-uuid", + "status": "success", + "summary": "Created 3 new files", + "artifacts": [ + { "type": "file", "path": "src/feature.go" }, + { "type": "file", "path": "src/feature_test.go" } + ] + }, + "timestamp": "2026-01-10T12:10:00Z" +} +``` + +### `acp.error` + +**Purpose:** Agent encountered an error. + +**When:** Error during agent execution. + +```json +{ + "type": "notification", + "action": "acp.error", + "payload": { + "task_id": "task-uuid", + "agent_id": "agent-uuid", + "code": "COMPILE_ERROR", + "message": "Failed to compile: syntax error", + "details": { + "file": "src/main.go", + "line": 42 + } + }, + "timestamp": "2026-01-10T12:06:00Z" +} +``` + +### `acp.status` + +**Purpose:** Agent status changed. + +**When:** Agent starts, completes, or fails. + +```json +{ + "type": "notification", + "action": "acp.status", + "payload": { + "task_id": "task-uuid", + "agent_id": "agent-uuid", + "status": "completed", + "previous_status": "running", + "exit_code": 0 + }, + "timestamp": "2026-01-10T12:15:00Z" +} +``` + +### `acp.heartbeat` + +**Purpose:** Keep-alive signal from agent. + +**When:** Periodically while agent is running (prevents timeout). + +```json +{ + "type": "notification", + "action": "acp.heartbeat", + "payload": { + "task_id": "task-uuid", + "agent_id": "agent-uuid" + }, + "timestamp": "2026-01-10T12:05:00Z" +} +``` + +### `task.updated` + +**Purpose:** Task properties changed. + +**When:** Task state, title, or other properties change. + +```json +{ + "type": "notification", + "action": "task.updated", + "payload": { + "id": "task-uuid", + "state": "IN_PROGRESS", + "previous_state": "TODO" + }, + "timestamp": "2026-01-10T12:00:05Z" +} +``` + +### `agent.updated` + +**Purpose:** Agent status changed. + +**When:** Agent starts, stops, or changes state. + +```json +{ + "type": "notification", + "action": "agent.updated", + "payload": { + "id": "agent-uuid", + "task_id": "task-uuid", + "status": "running", + "progress": 0 + }, + "timestamp": "2026-01-10T12:00:03Z" +} +``` + +--- + +## Complete Usage Example + +```javascript +const ws = new WebSocket('ws://localhost:8080/ws'); +const pending = new Map(); + +// Handle incoming messages +ws.onmessage = (event) => { + const msg = JSON.parse(event.data); + + if (msg.type === 'response' || msg.type === 'error') { + // Resolve pending request + const resolve = pending.get(msg.id); + if (resolve) { + pending.delete(msg.id); + resolve(msg); + } + } else if (msg.type === 'notification') { + // Handle real-time updates + console.log(`[${msg.action}]`, msg.payload); + } +}; + +// Helper to send requests +function request(action, payload) { + return new Promise((resolve) => { + const id = crypto.randomUUID(); + pending.set(id, resolve); + ws.send(JSON.stringify({ id, type: 'request', action, payload })); + }); +} + +// Full workflow example +async function runTask() { + // 1. Create board + const board = await request('board.create', { name: 'My Project' }); + + // 2. Create column + const column = await request('column.create', { + board_id: board.payload.id, + name: 'To Do', + state: 'TODO' + }); + + // 3. Create task + const task = await request('task.create', { + board_id: board.payload.id, + column_id: column.payload.id, + title: 'Implement user authentication', + agent_type: 'auggie' + }); + + // 4. Subscribe to updates + await request('task.subscribe', { task_id: task.payload.id }); + + // 5. Start execution + await request('orchestrator.start', { task_id: task.payload.id }); + + // 6. ACP notifications will now stream automatically... + + // 7. Send follow-up prompt (optional) + await request('orchestrator.prompt', { + task_id: task.payload.id, + prompt: 'Also add JWT token validation' + }); + + // 8. When done, complete the task + await request('orchestrator.complete', { task_id: task.payload.id }); + + // 9. Unsubscribe + await request('task.unsubscribe', { task_id: task.payload.id }); +} +``` + +--- + +## Quick Reference + +| Action | Purpose | +|--------|---------| +| `health.check` | Server health status | +| `board.create` | Create board | +| `board.list` | List all boards | +| `board.get` | Get board by ID | +| `board.update` | Update board | +| `board.delete` | Delete board | +| `column.create` | Create column | +| `column.list` | List columns in board | +| `column.get` | Get column by ID | +| `task.create` | Create task | +| `task.list` | List tasks in board | +| `task.get` | Get task by ID | +| `task.update` | Update task properties | +| `task.delete` | Delete task | +| `task.move` | Move task to column/position | +| `task.state` | Change task state | +| `task.subscribe` | Subscribe to task notifications | +| `task.unsubscribe` | Unsubscribe from task | +| `agent.list` | List agent instances | +| `agent.launch` | Launch agent (low-level) | +| `agent.status` | Get agent status | +| `agent.logs` | Get agent logs | +| `agent.stop` | Stop agent | +| `agent.types` | List available agent types | +| `orchestrator.status` | Get orchestrator status | +| `orchestrator.queue` | Get task queue | +| `orchestrator.trigger` | Queue task for execution | +| `orchestrator.start` | Start task execution | +| `orchestrator.stop` | Stop task execution | +| `orchestrator.prompt` | Send follow-up prompt | +| `orchestrator.complete` | Complete task | +