kandev/docs/WEBSOCKET_API.md

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:

{
  "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

{
  "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:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "request",
  "action": "health.check",
  "payload": {}
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "board.list",
  "payload": {}
}

Response:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "board.get",
  "payload": {
    "id": "board-uuid"
  }
}

Payload Field	Type	Required	Description
id	string	✅	Board ID

Response:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "board.delete",
  "payload": {
    "id": "board-uuid"
  }
}

Payload Field	Type	Required	Description
id	string	✅	Board ID

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "column.list",
  "payload": {
    "board_id": "board-uuid"
  }
}

Payload Field	Type	Required	Description
board_id	string	✅	Board ID

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "task.list",
  "payload": {
    "board_id": "board-uuid"
  }
}

Payload Field	Type	Required	Description
board_id	string	✅	Board ID

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "task.delete",
  "payload": {
    "id": "task-uuid"
  }
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "agent.list",
  "payload": {}
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "agent.status",
  "payload": {
    "agent_id": "agent-uuid"
  }
}

Payload Field	Type	Required	Description
agent_id	string	✅	Agent instance ID

Response:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "agent.logs",
  "payload": {
    "agent_id": "agent-uuid"
  }
}

Payload Field	Type	Required	Description
agent_id	string	✅	Agent instance ID

Response:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "agent.stop",
  "payload": {
    "agent_id": "agent-uuid"
  }
}

Payload Field	Type	Required	Description
agent_id	string	✅	Agent instance ID

Response:

{
  "id": "uuid",
  "type": "response",
  "action": "agent.stop",
  "payload": {
    "success": true
  }
}

agent.types

Purpose: List available agent types.

Request:

{
  "id": "uuid",
  "type": "request",
  "action": "agent.types",
  "payload": {}
}

Response:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "orchestrator.status",
  "payload": {}
}

Response:

{
  "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:

{
  "id": "uuid",
  "type": "request",
  "action": "orchestrator.queue",
  "payload": {}
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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).

{
  "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.

{
  "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.

{
  "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

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