@desplega.ai/agent-swarm 1.159.0 → 1.161.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.159.0",
+    "version": "1.161.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": [
@@ -165,6 +165,7 @@
               "ui",
               "github",
               "gitlab",
+              "azure-devops",
               "agentmail",
               "system",
               "schedule",
@@ -285,7 +286,8 @@
             "type": "string",
             "enum": [
               "github",
-              "gitlab"
+              "gitlab",
+              "azure-devops"
             ]
           },
           "vcsRepo": {
@@ -1842,19 +1844,35 @@
             "type": "string",
             "minLength": 1,
             "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
-            "description": "Name of a predefined extension in the catalog (`GET /api/extensions/catalog`)."
+            "description": "Name of a predefined extension in the catalog (`GET /api/extensions/catalog`). Mutually exclusive with `manifest` and `files`."
+          },
+          "manifest": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ExtensionManifest"
+              },
+              {
+                "description": "Inline bundle manifest. Requires `files`. Accepted only when `EXTENSION_ALLOW_INLINE_INSTALL` is on and the caller is a lead, operator, or dashboard user."
+              }
+            ]
+          },
+          "files": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Inline bundle files keyed by relative path. Requires `manifest`."
           },
           "priority": {
-            "type": "integer"
+            "type": "integer",
+            "description": "Handler priority. Lower values run first."
           },
           "config": {
             "type": "object",
-            "additionalProperties": {}
+            "additionalProperties": {},
+            "description": "Extension configuration."
           }
         },
-        "required": [
-          "template"
-        ],
         "additionalProperties": false
       },
       "ExtensionCatalogItem": {
@@ -4815,6 +4833,26 @@
                             "format",
                             "header"
                           ]
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "format": {
+                              "type": "string",
+                              "enum": [
+                                "standard-webhooks"
+                              ]
+                            },
+                            "toleranceSeconds": {
+                              "type": "integer",
+                              "exclusiveMinimum": 0,
+                              "default": 300,
+                              "description": "Maximum allowed clock skew, in seconds, for the webhook-timestamp header"
+                            }
+                          },
+                          "required": [
+                            "format"
+                          ]
                         }
                       ],
                       "description": "Optional webhook verification format. Omit to keep legacy HMAC-SHA256 behavior with fallback header scanning."
@@ -5443,6 +5481,26 @@
                             "format",
                             "header"
                           ]
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "format": {
+                              "type": "string",
+                              "enum": [
+                                "standard-webhooks"
+                              ]
+                            },
+                            "toleranceSeconds": {
+                              "type": "integer",
+                              "exclusiveMinimum": 0,
+                              "default": 300,
+                              "description": "Maximum allowed clock skew, in seconds, for the webhook-timestamp header"
+                            }
+                          },
+                          "required": [
+                            "format"
+                          ]
                         }
                       ],
                       "description": "Optional webhook verification format. Omit to keep legacy HMAC-SHA256 behavior with fallback header scanning."
@@ -14935,7 +14993,7 @@
     "/api/oauth/keep-warm/codex": {
       "post": {
         "summary": "Locked keep-warm refresh sweep across all Codex OAuth pool slots",
-        "description": "Enumerates codex_oauth_* slots and refreshes any older than ~7 days through the same locked getValidCodexOAuth path used at task time. Skips slots already benched by codex-auth-expiry-watch.",
+        "description": "Enumerates codex_oauth_* slots and refreshes any older than ~7 days through the same locked getValidCodexOAuth path used at task time. Skips slots with a codex-auth-watch bench marker (auth-failure bench or codex-auth-expiry-watch).",
         "tags": [
           "OAuth"
         ],
@@ -15607,6 +15665,115 @@
         }
       }
     },
+    "/api/keys/report-auth-failure": {
+      "post": {
+        "summary": "Record an auth failure for a pooled key; bench it after 2 in a row",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "keyIndex": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "taskId": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix",
+                  "keyIndex"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Failure recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean",
+                      "enum": [
+                        true
+                      ]
+                    },
+                    "consecutiveAuthFailures": {
+                      "type": "integer"
+                    },
+                    "benched": {
+                      "type": "boolean"
+                    },
+                    "rateLimitedUntil": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "success",
+                    "consecutiveAuthFailures",
+                    "benched",
+                    "rateLimitedUntil"
+                  ]
+                }
+              }
+            }
+          },
+          "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-rate-limit-windows": {
       "post": {
         "summary": "Record provider-emitted rate-limit window telemetry for an API key",
@@ -15733,6 +15900,110 @@
         }
       }
     },
+    "/api/keys/report-seat-mismatch": {
+      "post": {
+        "summary": "Record that an API key's subscription seat cannot run a model family",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string"
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "keyIndex": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "model": {
+                    "type": "string",
+                    "enum": [
+                      "fable",
+                      "opus",
+                      "sonnet",
+                      "haiku"
+                    ]
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix",
+                  "keyIndex",
+                  "model"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Seat mismatch 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/available": {
       "get": {
         "summary": "Get available (non-rate-limited) key indices for a credential type",
@@ -15827,12 +16098,22 @@
                         "string",
                         "null"
                       ]
+                    },
+                    "seatBlockedIndices": {
+                      "type": "array",
+                      "items": {
+                        "type": "integer"
+                      }
+                    },
+                    "authFailureFence": {
+                      "type": "integer"
                     }
                   },
                   "required": [
                     "success",
                     "availableIndices",
-                    "totalKeys"
+                    "totalKeys",
+                    "authFailureFence"
                   ]
                 }
               }
@@ -16023,6 +16304,27 @@
                               null
                             ]
                           },
+                          "lastSeatMismatchAt": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "lastSeatMismatchModel": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "consecutiveAuthFailures": {
+                            "type": "integer"
+                          },
+                          "lastAuthFailureAt": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
                           "modelLimits": {
                             "type": "array",
                             "items": {
@@ -16078,6 +16380,10 @@
                           "rateLimitWindows",
                           "plan",
                           "planSource",
+                          "lastSeatMismatchAt",
+                          "lastSeatMismatchModel",
+                          "consecutiveAuthFailures",
+                          "lastAuthFailureAt",
                           "modelLimits",
                           "createdAt",
                           "updatedAt"
@@ -16350,6 +16656,17 @@
                   },
                   "scopeId": {
                     "type": "string"
+                  },
+                  "clearAuthBench": {
+                    "type": "boolean"
+                  },
+                  "keyIndex": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "authFence": {
+                    "type": "integer",
+                    "minimum": 0
                   }
                 },
                 "required": [
@@ -17248,8 +17565,8 @@
     "/api/extensions/install": {
       "post": {
         "operationId": "extensions_install",
-        "summary": "Install a predefined extension from the catalog",
-        "description": "Installs the named template from `GET /api/extensions/catalog`. Inline bundles (`manifest`/`files`) are rejected with `inline_install_disabled`. Any authenticated agent can install a disabled draft owned by its agent ID. Workers can update only their own bundles; activation remains lead/operator-only.",
+        "summary": "Install an extension from the catalog or an inline bundle",
+        "description": "Installs the named `template` from `GET /api/extensions/catalog`, or an inline `manifest` plus `files`. Inline bundles are rejected with `inline_install_disabled` unless `EXTENSION_ALLOW_INLINE_INSTALL` is on, and then only lead, operator, and dashboard-user callers may send them (workers get 403). Any authenticated agent can install a catalog draft owned by its agent ID. Workers can update only their own bundles. A new extension is always disabled; activation remains lead/operator-only.",
         "tags": [
           "Extensions"
         ],
@@ -17432,7 +17749,7 @@
             }
           },
           "400": {
-            "description": "Inline bundle rejected or bundle validation failed",
+            "description": "Inline install disabled, invalid body (template and manifest/files are mutually exclusive), or bundle validation failed",
             "content": {
               "application/json": {
                 "schema": {
@@ -17442,7 +17759,7 @@
             }
           },
           "403": {
-            "description": "Permission denied",
+            "description": "Permission denied, including inline bundles from workers",
             "content": {
               "application/json": {
                 "schema": {
@@ -20450,7 +20767,17 @@
             }
           },
           "400": {
-            "description": "Validation error",
+            "description": "Validation error, or a sourcePath under /longterm that is not an allowed memory key",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "sourcePath is under a lead-only /longterm root and the caller is not the lead",
             "content": {
               "application/json": {
                 "schema": {
@@ -20511,6 +20838,12 @@
                       "session_summary",
                       "task_completion"
                     ]
+                  },
+                  "keyPrefix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200,
+                    "description": "Only return memories whose key starts with this text (literal, case-sensitive), for example '/longterm/facts/'."
                   }
                 },
                 "required": [
@@ -21786,6 +22119,12 @@
                           "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."
+                        },
+                        "model": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 200,
+                          "description": "Optional. Model that produced an `llm` rating, as \"<provider>/<model-id>\" (e.g. \"openrouter/deepseek/deepseek-v4.1-flash\"). Stored in memory_rating.model for `llm` events and ignored for `explicit-self`."
                         }
                       },
                       "required": [
@@ -24798,7 +25137,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.",
+        "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; telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
         "tags": [
           "Status"
         ],
@@ -25145,6 +25484,17 @@
                         "degraded",
                         "broken"
                       ]
+                    },
+                    "telemetry": {
+                      "type": "object",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean"
+                        }
+                      },
+                      "required": [
+                        "enabled"
+                      ]
                     }
                   },
                   "required": [
@@ -38997,6 +39347,9 @@
                     "type": "string",
                     "minLength": 1
                   },
+                  "allowCustomModel": {
+                    "type": "boolean"
+                  },
                   "parentTaskId": {
                     "type": "string",
                     "format": "uuid"
@@ -40428,6 +40781,7 @@
                                       "ui",
                                       "github",
                                       "gitlab",
+                                      "azure-devops",
                                       "agentmail",
                                       "system",
                                       "schedule",
@@ -44702,6 +45056,71 @@
                             "batchSize",
                             "slowestStatementMs"
                           ]
+                        },
+                        "contextVersions": {
+                          "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"
+                          ]
                         }
                       }
                     }
@@ -45698,6 +46117,7 @@
                                   "ui",
                                   "github",
                                   "gitlab",
+                                  "azure-devops",
                                   "agentmail",
                                   "system",
                                   "schedule",
@@ -46007,6 +46427,7 @@
                       "ui",
                       "github",
                       "gitlab",
+                      "azure-devops",
                       "agentmail",
                       "system",
                       "schedule",
@@ -46026,7 +46447,8 @@
                     "type": "string"
                   },
                   "model": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Concrete model override for this task, interpreted by the assignee's harness/provider. The model must run on the assignee's harness (an Anthropic model on a Claude agent, an OpenAI model on a Codex agent); a mismatch is rejected."
                   },
                   "modelTier": {
                     "type": "string",
@@ -46374,6 +46796,16 @@
               }
             }
           },
+          "403": {
+            "description": "Agent caller is neither a lead nor the task creator",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Task not found",
             "content": {
@@ -47096,7 +47528,7 @@
         },
         "responses": {
           "200": {
-            "description": "Progress updated",
+            "description": "Progress updated; a no-op once the task is terminal",
             "content": {
               "application/json": {
                 "schema": {
@@ -47116,6 +47548,16 @@
               }
             }
           },
+          "403": {
+            "description": "Task is assigned to another agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Task not found",
             "content": {
@@ -47171,6 +47613,19 @@
                   },
                   "force": {
                     "type": "boolean"
+                  },
+                  "provider": {
+                    "type": "string",
+                    "enum": [
+                      "claude",
+                      "codex",
+                      "pi",
+                      "devin",
+                      "claude-managed",
+                      "opencode",
+                      "acp",
+                      "dsh"
+                    ]
                   }
                 },
                 "required": [
@@ -47687,7 +48142,8 @@
                     "type": "string",
                     "enum": [
                       "github",
-                      "gitlab"
+                      "gitlab",
+                      "azure-devops"
                     ]
                   },
                   "vcsRepo": {
@@ -51344,6 +51800,78 @@
         }
       }
     },
+    "/api/azure-devops/webhook": {
+      "post": {
+        "summary": "Handle Azure DevOps service-hook events",
+        "tags": [
+          "Webhooks"
+        ],
+        "responses": {
+          "200": {
+            "description": "Event processed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "created": {
+                      "type": "boolean"
+                    },
+                    "taskId": {
+                      "type": "string"
+                    },
+                    "skipped": {
+                      "type": "boolean"
+                    },
+                    "reason": {
+                      "type": "string"
+                    },
+                    "extension": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "string"
+                        },
+                        "name": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "id",
+                        "name"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "created"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Invalid Basic auth credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Azure DevOps integration not configured",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/agentmail/webhook": {
       "post": {
         "summary": "Handle AgentMail webhook events",
@@ -51970,6 +52498,26 @@
                                     "format",
                                     "header"
                                   ]
+                                },
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "format": {
+                                      "type": "string",
+                                      "enum": [
+                                        "standard-webhooks"
+                                      ]
+                                    },
+                                    "toleranceSeconds": {
+                                      "type": "integer",
+                                      "exclusiveMinimum": 0,
+                                      "default": 300,
+                                      "description": "Maximum allowed clock skew, in seconds, for the webhook-timestamp header"
+                                    }
+                                  },
+                                  "required": [
+                                    "format"
+                                  ]
                                 }
                               ],
                               "description": "Optional webhook verification format. Omit to keep legacy HMAC-SHA256 behavior with fallback header scanning."
@@ -52342,6 +52890,26 @@
                                     "format",
                                     "header"
                                   ]
+                                },
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "format": {
+                                      "type": "string",
+                                      "enum": [
+                                        "standard-webhooks"
+                                      ]
+                                    },
+                                    "toleranceSeconds": {
+                                      "type": "integer",
+                                      "exclusiveMinimum": 0,
+                                      "default": 300,
+                                      "description": "Maximum allowed clock skew, in seconds, for the webhook-timestamp header"
+                                    }
+                                  },
+                                  "required": [
+                                    "format"
+                                  ]
                                 }
                               ],
                               "description": "Optional webhook verification format. Omit to keep legacy HMAC-SHA256 behavior with fallback header scanning."