@desplega.ai/agent-swarm 1.74.4 → 1.76.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.74.4",
+    "version": "1.76.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -326,6 +326,17 @@
                       "claude-managed",
                       "opencode"
                     ]
+                  },
+                  "harness_provider": {
+                    "type": "string",
+                    "enum": [
+                      "claude",
+                      "codex",
+                      "pi",
+                      "devin",
+                      "claude-managed",
+                      "opencode"
+                    ]
                   }
                 },
                 "required": [
@@ -377,6 +388,66 @@
         }
       }
     },
+    "/api/agents/{id}/harness-provider": {
+      "patch": {
+        "summary": "Re-assign an agent's harness_provider (live)",
+        "description": "Updates `agents.harness_provider` and upserts `swarm_config` (scope=agent, key=HARNESS_PROVIDER) so the worker's poll-loop reconciliation picks up the new provider within ~10s. No restart required. The swarm_config row is what actually drives the worker; the column mirrors the latest set value for dashboards.",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "harness_provider": {
+                    "type": "string",
+                    "enum": [
+                      "claude",
+                      "codex",
+                      "pi",
+                      "devin",
+                      "claude-managed",
+                      "opencode"
+                    ]
+                  }
+                },
+                "required": [
+                  "harness_provider"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated agent row"
+          },
+          "400": {
+            "description": "Validation error (unknown provider)"
+          },
+          "404": {
+            "description": "Agent not found"
+          }
+        }
+      }
+    },
     "/api/agents/{id}/name": {
       "put": {
         "summary": "Update agent name",
@@ -621,6 +692,209 @@
         }
       }
     },
+    "/api/agents/{id}/credential-status": {
+      "put": {
+        "summary": "Worker self-report of credential readiness (Phase 3 boot loop)",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "ready": {
+                    "type": "boolean"
+                  },
+                  "missing": {
+                    "type": [
+                      "array",
+                      "null"
+                    ],
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "cred_status": {
+                    "type": [
+                      "object",
+                      "null"
+                    ],
+                    "properties": {
+                      "ready": {
+                        "type": "boolean"
+                      },
+                      "missing": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        },
+                        "default": []
+                      },
+                      "satisfiedBy": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "enum": [
+                          "env",
+                          "file",
+                          "side-effect-pending",
+                          null
+                        ],
+                        "default": null
+                      },
+                      "hint": {
+                        "type": [
+                          "string",
+                          "null"
+                        ],
+                        "default": null
+                      },
+                      "liveTest": {
+                        "type": [
+                          "object",
+                          "null"
+                        ],
+                        "properties": {
+                          "ok": {
+                            "type": "boolean"
+                          },
+                          "error": {
+                            "type": [
+                              "string",
+                              "null"
+                            ],
+                            "default": null
+                          },
+                          "latency_ms": {
+                            "type": "number"
+                          },
+                          "testedAt": {
+                            "type": "number"
+                          }
+                        },
+                        "default": null,
+                        "required": [
+                          "ok",
+                          "latency_ms",
+                          "testedAt"
+                        ]
+                      },
+                      "reportedAt": {
+                        "type": "number"
+                      },
+                      "reportKind": {
+                        "type": "string",
+                        "enum": [
+                          "boot",
+                          "post_task"
+                        ],
+                        "default": "boot"
+                      }
+                    },
+                    "required": [
+                      "ready",
+                      "reportedAt"
+                    ]
+                  }
+                },
+                "required": [
+                  "ready"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "State updated; returns the agent row."
+          },
+          "404": {
+            "description": "Agent not found"
+          }
+        }
+      },
+      "get": {
+        "summary": "Single-agent credential-status snapshot for the dashboard",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Credential status payload"
+          },
+          "404": {
+            "description": "Agent not found"
+          }
+        }
+      }
+    },
+    "/api/agents/credential-status": {
+      "get": {
+        "summary": "Bulk credential-status across all agents (powers the dashboard)",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "idle",
+                "busy",
+                "offline",
+                "waiting_for_credentials"
+              ]
+            },
+            "required": false,
+            "name": "status",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of {agentId, status, missing[], lastCheckedAt}"
+          }
+        }
+      }
+    },
     "/api/approval-requests": {
       "post": {
         "summary": "Create a new approval request",
@@ -2732,34 +3006,166 @@
         }
       }
     },
-    "/api/integrations/claude-managed/test": {
-      "post": {
-        "summary": "Test the claude-managed integration: resolves ANTHROPIC_API_KEY + MANAGED_AGENT_ID from swarm_config and calls beta.agents.retrieve.",
+    "/api/inbox-state": {
+      "get": {
+        "summary": "List inbox-item state rows for a user",
         "tags": [
-          "Integrations"
+          "Inbox State"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {}
-              }
-            }
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "userId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "open",
+                "snoozed",
+                "dismissed",
+                "done"
+              ]
+            },
+            "required": false,
+            "name": "status",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "approval",
+                "credential_missing",
+                "broken_task",
+                "to_read",
+                "to_start_template"
+              ]
+            },
+            "required": false,
+            "name": "itemType",
+            "in": "query"
           }
-        },
+        ],
         "responses": {
           "200": {
-            "description": "Connection result — `{ ok: true, agentName, model }` on success or `{ ok: false, error }` on any failure (missing config, Anthropic API error). Always 200 OK."
-          }
-        }
-      }
-    },
+            "description": "Inbox state rows"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "patch": {
+        "summary": "Upsert per-user dismiss/snooze/done state for an inbox item",
+        "tags": [
+          "Inbox State"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "userId": {
+                    "type": "string"
+                  },
+                  "itemType": {
+                    "type": "string",
+                    "enum": [
+                      "approval",
+                      "credential_missing",
+                      "broken_task",
+                      "to_read",
+                      "to_start_template"
+                    ]
+                  },
+                  "itemId": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "open",
+                      "snoozed",
+                      "dismissed",
+                      "done"
+                    ]
+                  },
+                  "snoozeUntil": {
+                    "type": "string",
+                    "format": "date-time"
+                  }
+                },
+                "required": [
+                  "userId",
+                  "itemType",
+                  "itemId",
+                  "status"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Upserted inbox state row"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/integrations/claude-managed/test": {
+      "post": {
+        "summary": "Test the claude-managed integration: resolves ANTHROPIC_API_KEY + MANAGED_AGENT_ID from swarm_config and calls beta.agents.retrieve.",
+        "tags": [
+          "Integrations"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Connection result — `{ ok: true, agentName, model }` on success or `{ ok: false, error }` on any failure (missing config, Anthropic API error). Always 200 OK."
+          }
+        }
+      }
+    },
     "/api/memory/index": {
       "post": {
         "summary": "Ingest content into memory system (async embedding)",
@@ -3031,6 +3437,167 @@
         }
       }
     },
+    "/api/memory/rate": {
+      "post": {
+        "summary": "Submit RatingEvents to update memory usefulness posteriors",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "events": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "memoryId": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "signal": {
+                          "type": "number",
+                          "minimum": -1,
+                          "maximum": 1
+                        },
+                        "weight": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        },
+                        "source": {
+                          "type": "string",
+                          "enum": [
+                            "llm",
+                            "explicit-self"
+                          ]
+                        },
+                        "reasoning": {
+                          "type": "string",
+                          "maxLength": 500
+                        },
+                        "taskId": {
+                          "type": "string",
+                          "format": "uuid"
+                        },
+                        "referencesSource": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 512,
+                          "description": "Optional external source ID this memory references. Free-form string, convention \"<source>:<identifier>\" (e.g. \"github:owner/repo#N\", \"linear:KEY-N\", \"customer:<slug>\", \"slack:<channel>:<ts>\", \"agentmail:<thread-id>\"). Pick any prefix that fits — no closed enum. When present, an edge from this memory to the external source is created/updated."
+                        }
+                      },
+                      "required": [
+                        "memoryId",
+                        "signal",
+                        "weight",
+                        "source"
+                      ]
+                    },
+                    "minItems": 1,
+                    "maxItems": 50
+                  }
+                },
+                "required": [
+                  "events"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Ratings applied; per-event rejections returned in body"
+          },
+          "400": {
+            "description": "Validation error or explicit-self R6 spam-guard rejection"
+          },
+          "409": {
+            "description": "Duplicate explicit-self rating for (taskId, memoryId)"
+          }
+        }
+      }
+    },
+    "/api/memory/retrievals": {
+      "get": {
+        "summary": "List memories retrieved for a task or session (rater input)",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": false,
+            "name": "taskId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "sessionId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Retrieval rows joined with agent_memory"
+          },
+          "400": {
+            "description": "Missing taskId/sessionId or X-Agent-ID"
+          }
+        }
+      }
+    },
+    "/api/memory/edges": {
+      "get": {
+        "summary": "List references-source edges for a memory",
+        "tags": [
+          "Memory"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": true,
+            "name": "memoryId",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Edges with computed usefulness scores"
+          },
+          "400": {
+            "description": "Missing memoryId or X-Agent-ID"
+          }
+        }
+      }
+    },
     "/api/prompt-templates/resolved": {
       "get": {
         "summary": "Resolve a prompt template for a given event type and scope chain",
@@ -5303,11 +5870,11 @@
         }
       }
     },
-    "/api/skills": {
+    "/api/sessions": {
       "get": {
-        "summary": "List skills with optional filters",
+        "summary": "List recent task sessions (root tasks + chain summary)",
         "tags": [
-          "Skills"
+          "Sessions"
         ],
         "security": [
           {
@@ -5317,26 +5884,24 @@
         "parameters": [
           {
             "schema": {
-              "type": "string"
-            },
-            "required": false,
-            "name": "type",
-            "in": "query"
-          },
-          {
-            "schema": {
-              "type": "string"
+              "type": [
+                "integer",
+                "null"
+              ]
             },
             "required": false,
-            "name": "scope",
+            "name": "limit",
             "in": "query"
           },
           {
             "schema": {
-              "type": "string"
+              "type": [
+                "integer",
+                "null"
+              ]
             },
             "required": false,
-            "name": "agentId",
+            "name": "offset",
             "in": "query"
           },
           {
@@ -5344,7 +5909,7 @@
               "type": "string"
             },
             "required": false,
-            "name": "enabled",
+            "name": "source",
             "in": "query"
           },
           {
@@ -5352,30 +5917,127 @@
               "type": "string"
             },
             "required": false,
-            "name": "search",
+            "name": "q",
             "in": "query"
           }
         ],
         "responses": {
           "200": {
-            "description": "Skill list"
+            "description": "Recent sessions ordered by chain-wide last activity"
+          },
+          "401": {
+            "description": "Unauthorized"
           }
         }
-      },
-      "post": {
-        "summary": "Create a new skill",
+      }
+    },
+    "/api/sessions/{rootTaskId}": {
+      "get": {
+        "summary": "Get a session — root task + the entire descendant chain",
         "tags": [
-          "Skills"
+          "Sessions"
         ],
         "security": [
           {
             "bearerAuth": []
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "rootTaskId",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Root task + chain (ordered by createdAt)"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "Root task not found"
+          }
+        }
+      }
+    },
+    "/api/skills": {
+      "get": {
+        "summary": "List skills with optional filters",
+        "tags": [
+          "Skills"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "type",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "scope",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "agentId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "enabled",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "search",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Skill list"
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a new skill",
+        "tags": [
+          "Skills"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
                 "type": "object",
                 "properties": {
                   "content": {
@@ -6657,6 +7319,294 @@
         }
       }
     },
+    "/status": {
+      "get": {
+        "summary": "Identity + setup readiness + live activity for the swarm dashboard",
+        "description": "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; the 7 setup milestones each emit `unverified | configured | verified`; activity counts agents alive in the last 5 min and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set.",
+        "tags": [
+          "Status"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Status payload",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "identity": {
+                      "type": "object",
+                      "properties": {
+                        "name": {
+                          "type": "string"
+                        },
+                        "logo_url": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "brand_color": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "is_cloud": {
+                          "type": "boolean"
+                        },
+                        "marketing_url": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "hide_cloud_promo": {
+                          "type": "boolean"
+                        }
+                      },
+                      "required": [
+                        "name",
+                        "logo_url",
+                        "brand_color",
+                        "is_cloud",
+                        "marketing_url",
+                        "hide_cloud_promo"
+                      ]
+                    },
+                    "setup": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "enum": [
+                              "harness",
+                              "slack",
+                              "github",
+                              "linear",
+                              "jira",
+                              "workers",
+                              "first_task"
+                            ]
+                          },
+                          "label": {
+                            "type": "string"
+                          },
+                          "state": {
+                            "type": "string",
+                            "enum": [
+                              "unverified",
+                              "configured",
+                              "verified"
+                            ]
+                          },
+                          "hint": {
+                            "type": "string"
+                          },
+                          "action_url": {
+                            "type": "string"
+                          },
+                          "provider": {
+                            "type": "string",
+                            "enum": [
+                              "claude",
+                              "codex",
+                              "pi",
+                              "devin",
+                              "claude-managed",
+                              "opencode"
+                            ]
+                          },
+                          "providers": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "provider": {
+                                  "type": "string",
+                                  "enum": [
+                                    "claude",
+                                    "codex",
+                                    "pi",
+                                    "devin",
+                                    "claude-managed",
+                                    "opencode"
+                                  ]
+                                },
+                                "state": {
+                                  "type": "string",
+                                  "enum": [
+                                    "unverified",
+                                    "configured",
+                                    "verified"
+                                  ]
+                                },
+                                "workers": {
+                                  "type": "integer",
+                                  "minimum": 0
+                                }
+                              },
+                              "required": [
+                                "provider",
+                                "state",
+                                "workers"
+                              ]
+                            }
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "label",
+                          "state"
+                        ]
+                      }
+                    },
+                    "activity": {
+                      "type": "object",
+                      "properties": {
+                        "agents_online": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "leads_online": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "recent_tasks_count": {
+                          "type": "integer",
+                          "minimum": 0
+                        }
+                      },
+                      "required": [
+                        "agents_online",
+                        "leads_online",
+                        "recent_tasks_count"
+                      ]
+                    },
+                    "agent_fs": {
+                      "type": "object",
+                      "properties": {
+                        "configured": {
+                          "type": "boolean"
+                        },
+                        "base_url": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "configured",
+                        "base_url"
+                      ]
+                    },
+                    "health": {
+                      "type": "string",
+                      "enum": [
+                        "ok",
+                        "degraded",
+                        "broken"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "identity",
+                    "setup",
+                    "activity",
+                    "agent_fs",
+                    "health"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/status/test-connection": {
+      "post": {
+        "summary": "Live-test the harness provider's credentials",
+        "description": "Issues a real upstream call (Anthropic /v1/models, OpenAI /v1/models, etc.) for the given provider. Updates an in-memory cache so the next GET /status reports `harness.state = 'verified'` for SWARM_VERIFY_TTL_MS (default 1h).",
+        "tags": [
+          "Status"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "enum": [
+                      "claude",
+                      "codex",
+                      "pi",
+                      "devin",
+                      "claude-managed",
+                      "opencode"
+                    ]
+                  }
+                },
+                "required": [
+                  "provider"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Live-test result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "error": {
+                      "type": "string"
+                    },
+                    "latency_ms": {
+                      "type": "integer",
+                      "minimum": 0
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "latency_ms"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/tasks": {
       "get": {
         "summary": "List tasks with filters",
@@ -6713,6 +7663,23 @@
             "name": "includeHeartbeat",
             "in": "query"
           },
+          {
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "required": false,
+            "name": "createdAfter",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "source",
+            "in": "query"
+          },
           {
             "schema": {
               "type": [
@@ -6739,6 +7706,9 @@
         "responses": {
           "200": {
             "description": "Paginated task list"
+          },
+          "400": {
+            "description": "Validation error (e.g. unknown status token)"
           }
         }
       },
@@ -6793,7 +7763,21 @@
                     "type": "string"
                   },
                   "source": {
-                    "type": "string"
+                    "type": "string",
+                    "enum": [
+                      "mcp",
+                      "slack",
+                      "api",
+                      "ui",
+                      "github",
+                      "gitlab",
+                      "agentmail",
+                      "system",
+                      "schedule",
+                      "workflow",
+                      "linear",
+                      "jira"
+                    ]
                   },
                   "outputSchema": {
                     "type": "object",
@@ -6801,6 +7785,9 @@
                   },
                   "contextKey": {
                     "type": "string"
+                  },
+                  "requestedByUserId": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -7266,6 +8253,58 @@
         }
       }
     },
+    "/api/task-templates": {
+      "get": {
+        "summary": "List task templates ('To start' bucket)",
+        "tags": [
+          "Task Templates"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "category",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "task",
+                "workflow",
+                "schedule"
+              ]
+            },
+            "required": false,
+            "name": "kind",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "query",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Task template list"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/trackers/jira/authorize": {
       "get": {
         "summary": "Redirect to Atlassian OAuth consent screen",
@@ -7641,6 +8680,185 @@
         }
       }
     },
+    "/api/users": {
+      "get": {
+        "summary": "List all users",
+        "tags": [
+          "Users"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of users"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a new user",
+        "tags": [
+          "Users"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "email": {
+                    "type": "string"
+                  },
+                  "role": {
+                    "type": "string"
+                  },
+                  "notes": {
+                    "type": "string"
+                  },
+                  "slackUserId": {
+                    "type": "string"
+                  },
+                  "linearUserId": {
+                    "type": "string"
+                  },
+                  "githubUsername": {
+                    "type": "string"
+                  },
+                  "gitlabUsername": {
+                    "type": "string"
+                  },
+                  "emailAliases": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "preferredChannel": {
+                    "type": "string"
+                  },
+                  "timezone": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "User created"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/users/{id}": {
+      "put": {
+        "summary": "Update an existing user (partial — at least one field required)",
+        "tags": [
+          "Users"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "email": {
+                    "type": "string"
+                  },
+                  "role": {
+                    "type": "string"
+                  },
+                  "notes": {
+                    "type": "string"
+                  },
+                  "slackUserId": {
+                    "type": "string"
+                  },
+                  "linearUserId": {
+                    "type": "string"
+                  },
+                  "githubUsername": {
+                    "type": "string"
+                  },
+                  "gitlabUsername": {
+                    "type": "string"
+                  },
+                  "emailAliases": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "preferredChannel": {
+                    "type": "string"
+                  },
+                  "timezone": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "User updated"
+          },
+          "400": {
+            "description": "Validation error or empty body"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "User not found"
+          }
+        }
+      }
+    },
     "/api/github/webhook": {
       "post": {
         "summary": "Handle GitHub webhook events",