@desplega.ai/agent-swarm 2.5.3 → 2.6.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "2.5.3",
+    "version": "2.6.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": [
@@ -648,6 +648,15 @@
           },
           "testedAt": {
             "type": "number"
+          },
+          "warning": {
+            "type": "string"
+          },
+          "keys": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AgentCredStatusKeyResult"
+            }
           }
         },
         "default": null,
@@ -657,6 +666,39 @@
           "testedAt"
         ]
       },
+      "AgentCredStatusKeyResult": {
+        "type": "object",
+        "properties": {
+          "keyType": {
+            "type": "string"
+          },
+          "index": {
+            "type": "number"
+          },
+          "suffix": {
+            "type": "string"
+          },
+          "ok": {
+            "type": "boolean"
+          },
+          "error": {
+            "type": "string"
+          },
+          "httpStatus": {
+            "type": "number"
+          },
+          "latency_ms": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "keyType",
+          "index",
+          "suffix",
+          "ok",
+          "latency_ms"
+        ]
+      },
       "AgentLatestModel": {
         "type": [
           "object",
@@ -5521,6 +5563,77 @@
           "nodeId"
         ]
       },
+      "WorkflowRunStepSlim": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "runId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "nodeId": {
+            "type": "string"
+          },
+          "nodeType": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "running",
+              "waiting",
+              "completed",
+              "failed",
+              "skipped",
+              "cancelled"
+            ]
+          },
+          "output": {},
+          "error": {
+            "type": "string"
+          },
+          "startedAt": {
+            "type": "string"
+          },
+          "finishedAt": {
+            "type": "string"
+          },
+          "retryCount": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0
+          },
+          "maxRetries": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 3
+          },
+          "nextRetryAt": {
+            "type": "string"
+          },
+          "idempotencyKey": {
+            "type": "string"
+          },
+          "diagnostics": {
+            "type": "string"
+          },
+          "nextPort": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "runId",
+          "nodeId",
+          "nodeType",
+          "status",
+          "startedAt"
+        ]
+      },
       "WorkflowVersion": {
         "type": "object",
         "properties": {
@@ -12366,6 +12479,9 @@
                       "eng_lead",
                       "founder",
                       "product",
+                      "marketing",
+                      "sales",
+                      "research",
                       "ops",
                       "other"
                     ]
@@ -17266,6 +17382,217 @@
         }
       }
     },
+    "/api/codex-oauth/accounts": {
+      "get": {
+        "summary": "List stored Codex ChatGPT accounts",
+        "tags": [
+          "Codex OAuth"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stored account metadata",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "accounts": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "slot": {
+                            "type": "integer",
+                            "minimum": 0
+                          },
+                          "configKey": {
+                            "type": "string"
+                          },
+                          "legacy": {
+                            "type": "boolean"
+                          },
+                          "suffix": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "plan": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "email": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "needs_login",
+                              "unchecked"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "slot",
+                          "configKey",
+                          "legacy",
+                          "suffix",
+                          "plan",
+                          "email",
+                          "status"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "accounts"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Caller cannot read all secrets",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/codex-oauth/accounts/{slot}": {
+      "delete": {
+        "summary": "Remove a stored Codex ChatGPT account",
+        "tags": [
+          "Codex OAuth"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0,
+              "maximum": 100
+            },
+            "required": false,
+            "name": "slot",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Remaining accounts",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "accounts": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "slot": {
+                            "type": "integer",
+                            "minimum": 0
+                          },
+                          "configKey": {
+                            "type": "string"
+                          },
+                          "legacy": {
+                            "type": "boolean"
+                          },
+                          "suffix": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "plan": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "email": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "needs_login",
+                              "unchecked"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "slot",
+                          "configKey",
+                          "legacy",
+                          "suffix",
+                          "plan",
+                          "email",
+                          "status"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "accounts"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Config administration and permission to read all secrets required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Account slot does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/oauth/keep-warm/codex": {
       "post": {
         "summary": "Locked keep-warm refresh sweep across all Codex OAuth pool slots",
@@ -17417,7 +17744,7 @@
     "/api/comb/review-batches": {
       "post": {
         "summary": "Send agent-fs comments to the swarm as one lead task",
-        "description": "Comb's 'Send to swarm'. The server reads each comment again from agent-fs with its bootstrap key, skips replies, resolved comments, and comments already sent, and creates ONE task for the lead. Each sent comment gets a `[comb:sent task=<id>]` reply from the swarm service account. A comment is sent at most once. When an earlier send lost its reply, the batch posts that reply again (`repaired`). Answers 404 while COMB_ENABLED is off.",
+        "description": "Comb's 'Send to swarm'. The server reads each comment again from agent-fs with its bootstrap key, skips replies, resolved comments, and comments already sent, and creates ONE task for the lead. Each sent comment gets a `[comb:sent task=<id>]` reply from the swarm service account. A comment is sent at most once. An optional `note` from the sender goes into the task text. When an earlier send lost its reply, the batch posts that reply again (`repaired`). Answers 404 while COMB_ENABLED is off.",
         "tags": [
           "Comb"
         ],
@@ -17453,6 +17780,10 @@
                     "type": "string",
                     "minLength": 1,
                     "maxLength": 1024
+                  },
+                  "note": {
+                    "type": "string",
+                    "maxLength": 4000
                   }
                 },
                 "required": [
@@ -17529,6 +17860,14 @@
                           "taskId"
                         ]
                       }
+                    },
+                    "lead": {
+                      "type": "string",
+                      "enum": [
+                        "online",
+                        "offline",
+                        "none"
+                      ]
                     }
                   },
                   "required": [
@@ -17604,6 +17943,14 @@
                           "taskId"
                         ]
                       }
+                    },
+                    "lead": {
+                      "type": "string",
+                      "enum": [
+                        "online",
+                        "offline",
+                        "none"
+                      ]
                     }
                   },
                   "required": [
@@ -17761,6 +18108,537 @@
         }
       }
     },
+    "/api/config/pool-keys": {
+      "get": {
+        "summary": "List credential pool suffixes and status",
+        "tags": [
+          "Config"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "key",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Credential pool",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "source": {
+                      "type": "string",
+                      "enum": [
+                        "stored",
+                        "env",
+                        "none"
+                      ]
+                    },
+                    "readOnly": {
+                      "type": "boolean"
+                    },
+                    "keys": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "index": {
+                            "type": "integer",
+                            "minimum": 0
+                          },
+                          "suffix": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "rejected",
+                              "rate_limited",
+                              "unchecked"
+                            ]
+                          },
+                          "error": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "checkedAt": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "rateLimitedUntil": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "index",
+                          "suffix",
+                          "status",
+                          "error",
+                          "checkedAt",
+                          "rateLimitedUntil"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "source",
+                    "readOnly",
+                    "keys"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid pool variable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Secret read permission required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Test and append keys to a credential pool",
+        "tags": [
+          "Config"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "key": {
+                    "type": "string"
+                  },
+                  "value": {
+                    "type": "string"
+                  },
+                  "baseUrl": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "Base URL for the check only. Null tests the provider default. Omit to use the stored URL."
+                  }
+                },
+                "required": [
+                  "key",
+                  "value"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated credential pool and checks",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "source": {
+                      "type": "string",
+                      "enum": [
+                        "stored",
+                        "env",
+                        "none"
+                      ]
+                    },
+                    "readOnly": {
+                      "type": "boolean"
+                    },
+                    "keys": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "index": {
+                            "type": "integer",
+                            "minimum": 0
+                          },
+                          "suffix": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "rejected",
+                              "rate_limited",
+                              "unchecked"
+                            ]
+                          },
+                          "error": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "checkedAt": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "rateLimitedUntil": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "index",
+                          "suffix",
+                          "status",
+                          "error",
+                          "checkedAt",
+                          "rateLimitedUntil"
+                        ]
+                      }
+                    },
+                    "checks": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "suffix": {
+                            "type": "string"
+                          },
+                          "result": {
+                            "type": "string",
+                            "enum": [
+                              "verified",
+                              "rejected",
+                              "not_tested"
+                            ]
+                          },
+                          "httpStatus": {
+                            "type": [
+                              "number",
+                              "null"
+                            ]
+                          },
+                          "error": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "suffix",
+                          "result",
+                          "httpStatus",
+                          "error"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "source",
+                    "readOnly",
+                    "keys",
+                    "checks"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid key",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Config administration and permission to read all secrets required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Duplicate key or deployment env pool",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Provider rejected a key. Nothing was saved.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "checks": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "suffix": {
+                            "type": "string"
+                          },
+                          "result": {
+                            "type": "string",
+                            "enum": [
+                              "verified",
+                              "rejected",
+                              "not_tested"
+                            ]
+                          },
+                          "httpStatus": {
+                            "type": [
+                              "number",
+                              "null"
+                            ]
+                          },
+                          "error": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "suffix",
+                          "result",
+                          "httpStatus",
+                          "error"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "error",
+                    "checks"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "summary": "Remove one credential pool member",
+        "tags": [
+          "Config"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "key",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "required": false,
+            "name": "index",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 5
+            },
+            "required": true,
+            "name": "suffix",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Updated credential pool",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "source": {
+                      "type": "string",
+                      "enum": [
+                        "stored",
+                        "env",
+                        "none"
+                      ]
+                    },
+                    "readOnly": {
+                      "type": "boolean"
+                    },
+                    "keys": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "index": {
+                            "type": "integer",
+                            "minimum": 0
+                          },
+                          "suffix": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "ok",
+                              "rejected",
+                              "rate_limited",
+                              "unchecked"
+                            ]
+                          },
+                          "error": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "checkedAt": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "rateLimitedUntil": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "index",
+                          "suffix",
+                          "status",
+                          "error",
+                          "checkedAt",
+                          "rateLimitedUntil"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "source",
+                    "readOnly",
+                    "keys"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid pool member",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Config administration and permission to read all secrets required",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The pool changed or comes from the deployment env",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/tasks/{id}/context": {
       "post": {
         "summary": "Record a context usage snapshot for a task",
@@ -18212,6 +19090,120 @@
         }
       }
     },
+    "/api/keys/report-validation": {
+      "post": {
+        "summary": "Record live validation results for a credential pool",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keys": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "keyIndex": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
+                        "keySuffix": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 10
+                        },
+                        "ok": {
+                          "type": "boolean"
+                        },
+                        "httpStatus": {
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "keyIndex",
+                        "keySuffix",
+                        "ok"
+                      ]
+                    },
+                    "minItems": 1,
+                    "maxItems": 100
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keys"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Validation recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean",
+                      "enum": [
+                        true
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "success",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/keys/report-auth-failure": {
       "post": {
         "summary": "Record an auth failure for a pooled key; bench it after 2 in a row",
@@ -18631,6 +19623,12 @@
                         "type": "integer"
                       }
                     },
+                    "rejectedIndices": {
+                      "type": "array",
+                      "items": {
+                        "type": "integer"
+                      }
+                    },
                     "totalKeys": {
                       "type": "integer"
                     },
@@ -18872,6 +19870,18 @@
                               "null"
                             ]
                           },
+                          "lastValidationError": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "lastValidationFailedAt": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
                           "modelLimits": {
                             "type": "array",
                             "items": {
@@ -18931,6 +19941,8 @@
                           "lastSeatMismatchModel",
                           "consecutiveAuthFailures",
                           "lastAuthFailureAt",
+                          "lastValidationError",
+                          "lastValidationFailedAt",
                           "modelLimits",
                           "createdAt",
                           "updatedAt"
@@ -29471,7 +30483,7 @@
     "/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; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; 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, plus the Comb settings (COMB_ENABLED, the browser-facing agent-fs URL, the shared org and drive ids, and the agent-fs user id of the swarm service account); telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
+        "description": "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min, leads that can take work (status idle or busy), and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set, plus the Comb settings (COMB_ENABLED, the browser-facing agent-fs URL, the shared org and drive ids, and the agent-fs user id of the swarm service account); telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
         "tags": [
           "Status"
         ],
@@ -29664,6 +30676,10 @@
                           "type": "integer",
                           "minimum": 0
                         },
+                        "leads_ready": {
+                          "type": "integer",
+                          "minimum": 0
+                        },
                         "recent_tasks_count": {
                           "type": "integer",
                           "minimum": 0
@@ -29672,6 +30688,7 @@
                       "required": [
                         "agents_online",
                         "leads_online",
+                        "leads_ready",
                         "recent_tasks_count"
                       ]
                     },
@@ -30590,13 +31607,27 @@
                               "verifiedWorkers": {
                                 "type": "integer",
                                 "minimum": 0
+                              },
+                              "error": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
+                              },
+                              "warning": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
                               }
                             },
                             "required": [
                               "provider",
                               "state",
                               "workers",
-                              "verifiedWorkers"
+                              "verifiedWorkers",
+                              "error",
+                              "warning"
                             ]
                           }
                         },
@@ -31590,13 +32621,27 @@
                               "verifiedWorkers": {
                                 "type": "integer",
                                 "minimum": 0
+                              },
+                              "error": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
+                              },
+                              "warning": {
+                                "type": [
+                                  "string",
+                                  "null"
+                                ]
                               }
                             },
                             "required": [
                               "provider",
                               "state",
                               "workers",
-                              "verifiedWorkers"
+                              "verifiedWorkers",
+                              "error",
+                              "warning"
                             ]
                           }
                         },
@@ -31991,6 +33036,15 @@
             "name": "scheduleId",
             "in": "query"
           },
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": false,
+            "name": "workflowRunId",
+            "in": "query"
+          },
           {
             "schema": {
               "type": "string",
@@ -49605,6 +50659,12 @@
                 "schema": {
                   "type": "object",
                   "properties": {
+                    "labels": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    },
                     "groups": {
                       "type": "array",
                       "items": {
@@ -50362,6 +51422,9 @@
                     "owner": {
                       "$ref": "#/components/schemas/SessionOwner"
                     },
+                    "groupKey": {
+                      "type": "string"
+                    },
                     "approvals": {
                       "type": "array",
                       "items": {
@@ -50408,7 +51471,8 @@
                     "root",
                     "chain",
                     "access",
-                    "owner"
+                    "owner",
+                    "groupKey"
                   ]
                 }
               }
@@ -55599,6 +56663,71 @@
                             "batchSize",
                             "slowestStatementMs"
                           ]
+                        },
+                        "scriptRuns": {
+                          "type": "object",
+                          "properties": {
+                            "at": {
+                              "type": "string"
+                            },
+                            "rowsDeleted": {
+                              "type": "number"
+                            },
+                            "batches": {
+                              "type": "number"
+                            },
+                            "durationMs": {
+                              "type": "number"
+                            },
+                            "dryRun": {
+                              "type": "boolean"
+                            },
+                            "cumulativeRowsDeleted": {
+                              "type": "number"
+                            },
+                            "outcome": {
+                              "type": "string",
+                              "enum": [
+                                "converged",
+                                "budget_exhausted",
+                                "error"
+                              ]
+                            },
+                            "drained": {
+                              "type": "boolean"
+                            },
+                            "backlogRemaining": {
+                              "type": "number"
+                            },
+                            "batchSize": {
+                              "type": "number"
+                            },
+                            "slowestStatementMs": {
+                              "type": "number"
+                            },
+                            "lastError": {
+                              "type": "string"
+                            },
+                            "lastErrorAt": {
+                              "type": "string"
+                            },
+                            "lastSuccessAt": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "at",
+                            "rowsDeleted",
+                            "batches",
+                            "durationMs",
+                            "dryRun",
+                            "cumulativeRowsDeleted",
+                            "outcome",
+                            "drained",
+                            "backlogRemaining",
+                            "batchSize",
+                            "slowestStatementMs"
+                          ]
                         }
                       }
                     }
@@ -61334,6 +62463,19 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[\\x21-\\x7E]{1,255}$",
+              "description": "Optional client-generated key, 1-255 visible ASCII characters (a UUID works). The first request the server accepts under a key creates one workflow; a retry with the same key and an equivalent body gets that request's status and body back (with `Idempotent-Replayed: true`) and changes nothing. The key is scoped to the caller's identity and this operation; it is not a credential. The same key with a different body is a 409. A request rejected before it is accepted (validation, auth, not found, disabled) does not use up the key. Accepted keys do not expire."
+            },
+            "required": false,
+            "description": "Optional client-generated key, 1-255 visible ASCII characters (a UUID works). The first request the server accepts under a key creates one workflow; a retry with the same key and an equivalent body gets that request's status and body back (with `Idempotent-Replayed: true`) and changes nothing. The key is scoped to the caller's identity and this operation; it is not a credential. The same key with a different body is a 409. A request rejected before it is accepted (validation, auth, not found, disabled) does not use up the key. Accepted keys do not expire.",
+            "name": "Idempotency-Key",
+            "in": "header"
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -61635,7 +62777,27 @@
             }
           },
           "400": {
-            "description": "Invalid definition",
+            "description": "Invalid definition, or a malformed Idempotency-Key",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Idempotency-Key was already used for a different request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "410": {
+            "description": "The workflow created under this Idempotency-Key was deleted",
             "content": {
               "application/json": {
                 "schema": {
@@ -62341,6 +63503,7 @@
     "/api/workflows/{id}/trigger": {
       "post": {
         "summary": "Trigger a workflow execution",
+        "description": "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
         "tags": [
           "Workflows"
         ],
@@ -62357,6 +63520,17 @@
             "required": true,
             "name": "id",
             "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^[\\x21-\\x7E]{1,255}$",
+              "description": "Optional client-generated key, 1-255 visible ASCII characters (a UUID works). The first request the server accepts under a key starts one run; a retry with the same key and an equivalent body gets that request's status and body back (with `Idempotent-Replayed: true`) and changes nothing. The key is scoped to the caller's identity and this operation; it is not a credential. The same key with a different body is a 409. A request rejected before it is accepted (validation, auth, not found, disabled) does not use up the key. Accepted keys do not expire."
+            },
+            "required": false,
+            "description": "Optional client-generated key, 1-255 visible ASCII characters (a UUID works). The first request the server accepts under a key starts one run; a retry with the same key and an equivalent body gets that request's status and body back (with `Idempotent-Replayed: true`) and changes nothing. The key is scoped to the caller's identity and this operation; it is not a credential. The same key with a different body is a 409. A request rejected before it is accepted (validation, auth, not found, disabled) does not use up the key. Accepted keys do not expire.",
+            "name": "Idempotency-Key",
+            "in": "header"
           }
         ],
         "responses": {
@@ -62383,7 +63557,7 @@
             }
           },
           "400": {
-            "description": "Workflow is disabled",
+            "description": "Workflow is disabled, or a malformed Idempotency-Key",
             "content": {
               "application/json": {
                 "schema": {
@@ -62411,6 +63585,26 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "Idempotency-Key was already used for a different request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "410": {
+            "description": "The workflow triggered under this Idempotency-Key was deleted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
@@ -62599,6 +63793,7 @@
     "/api/workflow-runs/{id}": {
       "get": {
         "summary": "Get a workflow run with steps (includes retry columns)",
+        "description": "Returns the run with its `context` and every step with its `input` by default. A step's `input` is a snapshot of the context when the step started, so in runs with loops (polling, `wait`, iterations) the response grows with steps × context size. Pass `fields=slim` to drop `run.context` and `steps[].input`; outputs, errors, diagnostics, retry fields and `parent` stay.",
         "tags": [
           "Workflows"
         ],
@@ -62615,32 +63810,134 @@
             "required": true,
             "name": "id",
             "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "full",
+                "slim"
+              ]
+            },
+            "required": false,
+            "name": "fields",
+            "in": "query"
           }
         ],
         "responses": {
           "200": {
             "description": "Workflow run details with steps including retry info",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "run": {
+                          "$ref": "#/components/schemas/WorkflowRun"
+                        },
+                        "steps": {
+                          "type": "array",
+                          "items": {
+                            "$ref": "#/components/schemas/WorkflowRunStep"
+                          }
+                        },
+                        "parent": {
+                          "$ref": "#/components/schemas/WorkflowRunParent"
+                        }
+                      },
+                      "required": [
+                        "run",
+                        "steps"
+                      ]
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "run": {
+                          "$ref": "#/components/schemas/WorkflowRunSummary"
+                        },
+                        "steps": {
+                          "type": "array",
+                          "items": {
+                            "$ref": "#/components/schemas/WorkflowRunStepSlim"
+                          }
+                        },
+                        "parent": {
+                          "$ref": "#/components/schemas/WorkflowRunParent"
+                        }
+                      },
+                      "required": [
+                        "run",
+                        "steps"
+                      ]
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Run not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/workflow-runs/{id}/tree": {
+      "get": {
+        "summary": "Get a workflow run and every sub-workflow run below it",
+        "description": "Follows stored parent links (`parentStepId` → step → run) through every attempt of every step, terminal runs included. `runs` holds list rows without `context`, root first. `hasOpenWork` is true while any run in the tree is live, has a pending, running or waiting step, a queued retry, an open task or a pending approval; after a cancel it turns false once the tree has settled. Both come from one read snapshot. The tree is not paginated. Links that form a cycle or nest deeper than 32 levels return 409.",
+        "tags": [
+          "Workflows"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The run tree",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "run": {
-                      "$ref": "#/components/schemas/WorkflowRun"
+                    "rootRunId": {
+                      "type": "string"
                     },
-                    "steps": {
+                    "runs": {
                       "type": "array",
                       "items": {
-                        "$ref": "#/components/schemas/WorkflowRunStep"
+                        "$ref": "#/components/schemas/WorkflowRunSummary"
                       }
                     },
-                    "parent": {
-                      "$ref": "#/components/schemas/WorkflowRunParent"
+                    "hasOpenWork": {
+                      "type": "boolean"
                     }
                   },
                   "required": [
-                    "run",
-                    "steps"
+                    "rootRunId",
+                    "runs",
+                    "hasOpenWork"
                   ]
                 }
               }
@@ -62655,6 +63952,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "Stored parent links form a cycle or nest past the depth bound",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }