feat: add boards and tasks management endpoints

2026-02-04 02:28:51 +05:30
parent 23faa0865b
commit 1abc8f68f3
170 changed files with 6860 additions and 10706 deletions
--- a/ORCHESTRATION.md
+++ b/ORCHESTRATION.md
@@ -0,0 +1,176 @@
+# Mission Control Orchestration Guide
+
+This document explains how to orchestrate tasks in Mission Control, including how to:
+- Register sub-agents
+- Log activities
+- Track deliverables
+- Update task status
+
+## API Base URL
+
+```
+http://localhost:8000
+```
+
+Or use the `BASE_URL` environment variable.
+
+## Task Lifecycle
+
+```
+INBOX → IN_PROGRESS → REVIEW → DONE
+```
+
+**Status Descriptions:**
+- **INBOX**: New tasks awaiting processing
+- **IN_PROGRESS**: Agent actively working on the task
+- **REVIEW**: Agent finished, awaiting human approval
+- **DONE**: Task completed and approved
+
+Optional statuses may be enabled (`ASSIGNED`, `TESTING`) but are not required by default.
+
+## When You Receive a Task
+
+When a task is claimed, the response includes:
+- Task ID
+- Title, description, priority
+- Project ID
+
+## Required API Calls
+
+### 1. Register Sub-Agent (when spawning a worker)
+
+```bash
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/{TASK_ID}/subagents" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "openclaw_session_id": "unique-session-id",
+    "agent_name": "Designer"
+  }'
+```
+
+### 2. Log Activity (for each significant action)
+
+```bash
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/{TASK_ID}/activities" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "activity_type": "updated",
+    "message": "Started working on design mockups"
+  }'
+```
+
+Activity types:
+- `spawned` - When sub-agent starts
+- `updated` - Progress update
+- `completed` - Work finished
+- `file_created` - Created a deliverable
+- `status_changed` - Task moved to new status
+
+### 3. Register Deliverable (for each output)
+
+```bash
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/{TASK_ID}/deliverables" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Homepage Design",
+    "markdown_content": "## Summary\n- Implemented layout\n- Added responsive styles"
+  }'
+```
+
+### 4. Update Task Status
+
+```bash
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/{TASK_ID}/transition" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "to_status": "review" }'
+```
+
+## Complete Example Workflow
+
+```bash
+TASK_ID="abc-123"
+BASE_URL="http://localhost:8000"
+ORG_ID="org-uuid"
+WORKSPACE_ID="workspace-uuid"
+AGENT_TOKEN="agent-token"
+
+# 1) Log that you're starting
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/$TASK_ID/activities" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"activity_type": "updated", "message": "Starting work on task"}'
+
+# 2) Spawn a sub-agent
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/$TASK_ID/subagents" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"openclaw_session_id": "subagent-'$(date +%s)'", "agent_name": "Designer"}'
+
+# 3) Register the deliverable
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/$TASK_ID/deliverables" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Completed Design",
+    "markdown_content": "## Deliverable\n- Final design with all requested features"
+  }'
+
+# 4) Log completion
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/$TASK_ID/activities" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"activity_type": "completed", "message": "Design completed successfully"}'
+
+# 5) Move to review
+curl -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/tasks/$TASK_ID/transition" \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"to_status": "review"}'
+```
+
+## Endpoints Reference
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks` | GET | List tasks |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks` | POST | Create task |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}` | PATCH | Update task |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}/activities` | GET | List activities |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}/activities` | POST | Log activity |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}/deliverables` | GET | List deliverables |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}/deliverables` | POST | Add deliverable |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}/subagents` | GET | List sub-agents |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/{task_id}/subagents` | POST | Register sub-agent |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/tasks/claim-next` | POST | Claim next task (FIFO) |
+| `/api/v1/orgs/{org_id}/workspaces/{workspace_id}/events/activities` | GET | SSE activity stream |
+
+## Activity Body Schema
+
+```json
+{
+  "activity_type": "spawned|updated|completed|file_created|status_changed",
+  "message": "Human-readable description of what happened"
+}
+```
+
+## Deliverable Body Schema
+
+```json
+{
+  "title": "Display name for the deliverable",
+  "markdown_content": "Markdown content for the deliverable"
+}
+```
+
+## Sub-Agent Body Schema
+
+```json
+{
+  "openclaw_session_id": "unique-identifier-for-session",
+  "agent_name": "Designer|Developer|Researcher|Writer"
+}
+```