@desplega.ai/agent-swarm 2.4.0 → 2.4.2

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "2.4.0",
+    "version": "2.4.2",
     "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": [
@@ -613,6 +613,9 @@
           "bedrock": {
             "$ref": "#/components/schemas/AgentBedrockStatus"
           },
+          "opencodeGo": {
+            "$ref": "#/components/schemas/AgentOpencodeGoStatus"
+          },
           "acp": {
             "$ref": "#/components/schemas/AgentAcpStatus"
           }
@@ -766,6 +769,28 @@
           "ready"
         ]
       },
+      "AgentOpencodeGoStatus": {
+        "type": [
+          "object",
+          "null"
+        ],
+        "properties": {
+          "probedAt": {
+            "type": "number"
+          },
+          "models": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "default": []
+          }
+        },
+        "default": null,
+        "required": [
+          "probedAt"
+        ]
+      },
       "AgentAcpStatus": {
         "type": [
           "object",
@@ -7502,6 +7527,14 @@
                                 },
                                 {
                                   "type": "boolean"
+                                },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
                                 }
                               ]
                             }
@@ -7530,6 +7563,14 @@
                                   },
                                   {
                                     "type": "boolean"
+                                  },
+                                  {
+                                    "type": "object",
+                                    "additionalProperties": {}
+                                  },
+                                  {
+                                    "type": "array",
+                                    "items": {}
                                   }
                                 ]
                               }
@@ -7545,6 +7586,14 @@
                                 {
                                   "type": "boolean"
                                 },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
+                                },
                                 {
                                   "type": "null"
                                 }
@@ -7576,6 +7625,14 @@
                                 {
                                   "type": "boolean"
                                 },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
+                                },
                                 {
                                   "type": "null"
                                 }
@@ -8030,6 +8087,14 @@
                                 },
                                 {
                                   "type": "boolean"
+                                },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
                                 }
                               ]
                             }
@@ -8058,6 +8123,14 @@
                                   },
                                   {
                                     "type": "boolean"
+                                  },
+                                  {
+                                    "type": "object",
+                                    "additionalProperties": {}
+                                  },
+                                  {
+                                    "type": "array",
+                                    "items": {}
                                   }
                                 ]
                               }
@@ -8073,6 +8146,14 @@
                                 {
                                   "type": "boolean"
                                 },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
+                                },
                                 {
                                   "type": "null"
                                 }
@@ -8104,6 +8185,14 @@
                                 {
                                   "type": "boolean"
                                 },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
+                                },
                                 {
                                   "type": "null"
                                 }
@@ -8391,6 +8480,14 @@
                                 },
                                 {
                                   "type": "boolean"
+                                },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
                                 }
                               ]
                             }
@@ -8419,6 +8516,14 @@
                                   },
                                   {
                                     "type": "boolean"
+                                  },
+                                  {
+                                    "type": "object",
+                                    "additionalProperties": {}
+                                  },
+                                  {
+                                    "type": "array",
+                                    "items": {}
                                   }
                                 ]
                               }
@@ -8434,6 +8539,14 @@
                                 {
                                   "type": "boolean"
                                 },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
+                                },
                                 {
                                   "type": "null"
                                 }
@@ -8465,6 +8578,14 @@
                                 {
                                   "type": "boolean"
                                 },
+                                {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                },
+                                {
+                                  "type": "array",
+                                  "items": {}
+                                },
                                 {
                                   "type": "null"
                                 }
@@ -15336,7 +15457,7 @@
     "/api/used-by": {
       "post": {
         "summary": "Grant or revoke the 'used by' logo consent",
-        "description": "Records whether agent-swarm.dev may show this organization's logo as a company that uses Agent Swarm. Sends the organization name and website to the telemetry proxy, where a person approves each logo by hand. An explicit admin action, so it is not gated by the telemetry opt-out.",
+        "description": "Records consent to show the organization's logo on agent-swarm.dev. A grant requires a valid contact email. It sends organization identity, contact details, and an optional quote to the proxy for manual review. This explicit admin action works when telemetry is off. A revoke clears the stored contact details and quote.",
         "tags": [
           "Telemetry"
         ],
@@ -15353,6 +15474,26 @@
                 "properties": {
                   "granted": {
                     "type": "boolean"
+                  },
+                  "contactEmail": {
+                    "type": "string",
+                    "maxLength": 320,
+                    "format": "email"
+                  },
+                  "contactFunction": {
+                    "type": "string",
+                    "enum": [
+                      "engineer",
+                      "eng_lead",
+                      "founder",
+                      "product",
+                      "ops",
+                      "other"
+                    ]
+                  },
+                  "quote": {
+                    "type": "string",
+                    "maxLength": 280
                   }
                 },
                 "required": [
@@ -15386,7 +15527,7 @@
             }
           },
           "400": {
-            "description": "Organization name or website is not set (a revoke falls back to the identity of the last grant)",
+            "description": "Invalid contact details, or missing organization name or website",
             "content": {
               "application/json": {
                 "schema": {
@@ -15431,7 +15572,7 @@
     "/api/ranking": {
       "get": {
         "summary": "Public ranking state",
-        "description": "Whether this install can join the public agent-swarm.dev ranking (telemetry on, organization name and website set), whether it is opted in, and its stored listing. The listing carries the private ranking claim, so only a config admin can read it.",
+        "description": "Whether this install can join the public agent-swarm.dev ranking (telemetry on, organization name and website set), whether it is opted in, and its stored listing. Only a config admin can read it.",
         "tags": [
           "Telemetry"
         ],
@@ -15491,9 +15632,6 @@
                             1
                           ]
                         },
-                        "claim": {
-                          "type": "string"
-                        },
                         "name": {
                           "type": "string"
                         },
@@ -15535,7 +15673,6 @@
                       },
                       "required": [
                         "v",
-                        "claim",
                         "name",
                         "domain",
                         "category",
@@ -15548,18 +15685,6 @@
                     "listingMatchesDomain": {
                       "type": "boolean"
                     },
-                    "fileJson": {
-                      "type": [
-                        "string",
-                        "null"
-                      ]
-                    },
-                    "prUrl": {
-                      "type": [
-                        "string",
-                        "null"
-                      ]
-                    },
                     "verifyUrl": {
                       "type": [
                         "string",
@@ -15576,8 +15701,6 @@
                     "domain",
                     "listing",
                     "listingMatchesDomain",
-                    "fileJson",
-                    "prUrl",
                     "verifyUrl"
                   ]
                 }
@@ -15610,7 +15733,7 @@
     "/api/ranking/opt-in": {
       "post": {
         "summary": "Opt this install into the public ranking",
-        "description": "Builds the telemetry_ranking listing from the organization name and website plus the chosen category, stores it, turns PUBLIC_RANKING_ENABLED on and sends ranking.opted_in. The install is ranked only after a ranking PR with the returned file is merged into desplega-ai/agent-swarm.",
+        "description": "Builds the telemetry_ranking listing from the organization name and website plus the chosen category, stores it, turns PUBLIC_RANKING_ENABLED on and sends ranking.opted_in. That is the whole opt-in: the install shows on agent-swarm.dev/ranking at the next hourly refresh.",
         "tags": [
           "Telemetry"
         ],
@@ -15673,9 +15796,6 @@
                     "domain": {
                       "type": "string"
                     },
-                    "claim": {
-                      "type": "string"
-                    },
                     "listing": {
                       "type": "object",
                       "properties": {
@@ -15685,9 +15805,6 @@
                             1
                           ]
                         },
-                        "claim": {
-                          "type": "string"
-                        },
                         "name": {
                           "type": "string"
                         },
@@ -15729,7 +15846,6 @@
                       },
                       "required": [
                         "v",
-                        "claim",
                         "name",
                         "domain",
                         "category",
@@ -15739,22 +15855,13 @@
                         "updatedAt"
                       ]
                     },
-                    "fileJson": {
-                      "type": "string"
-                    },
-                    "prUrl": {
-                      "type": "string"
-                    },
                     "verifyUrl": {
                       "type": "string"
                     }
                   },
                   "required": [
                     "domain",
-                    "claim",
                     "listing",
-                    "fileJson",
-                    "prUrl",
                     "verifyUrl"
                   ]
                 }
@@ -15807,7 +15914,7 @@
     "/api/ranking/opt-out": {
       "post": {
         "summary": "Leave the public ranking",
-        "description": "Turns PUBLIC_RANKING_ENABLED off and sends ranking.opted_out, so workers stop sending ranking.usage. Returns the GitHub page that deletes the ranking entry.",
+        "description": "Turns PUBLIC_RANKING_ENABLED off and sends ranking.opted_out, so workers stop sending ranking.usage. The install leaves agent-swarm.dev/ranking at the next hourly refresh.",
         "tags": [
           "Telemetry"
         ],
@@ -15829,17 +15936,10 @@
                       "enum": [
                         false
                       ]
-                    },
-                    "leaveUrl": {
-                      "type": [
-                        "string",
-                        "null"
-                      ]
                     }
                   },
                   "required": [
-                    "enabled",
-                    "leaveUrl"
+                    "enabled"
                   ]
                 }
               }
@@ -32912,6 +33012,302 @@
         }
       }
     },
+    "/api/tasks/{id}/lineage": {
+      "get": {
+        "summary": "Get the tree a task belongs to (ancestors and descendants)",
+        "description": "Follows `parentTaskId` up to the topmost ancestor, then returns every descendant of that root as slim task rows, the task's own subtree first. Bounded: at most 50 hops up, `maxDepth` levels down and about twice `maxNodes` rows; `truncated` is true when any task in the tree is missing from the response.",
+        "tags": [
+          "Tasks"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 500
+            },
+            "required": false,
+            "name": "maxNodes",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 30
+            },
+            "required": false,
+            "name": "maxDepth",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The lineage tree as a flat list linked by `parentTaskId`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "rootTaskId": {
+                      "type": "string"
+                    },
+                    "tasks": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "key": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 255,
+                            "description": "Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form."
+                          },
+                          "agentId": {
+                            "type": [
+                              "string",
+                              "null"
+                            ]
+                          },
+                          "creatorAgentId": {
+                            "type": "string"
+                          },
+                          "task": {
+                            "type": "string",
+                            "minLength": 1
+                          },
+                          "title": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "draft",
+                              "backlog",
+                              "unassigned",
+                              "offered",
+                              "reviewing",
+                              "pending",
+                              "in_progress",
+                              "paused",
+                              "completed",
+                              "failed",
+                              "cancelled",
+                              "superseded"
+                            ]
+                          },
+                          "source": {
+                            "type": "string",
+                            "enum": [
+                              "mcp",
+                              "slack",
+                              "api",
+                              "ui",
+                              "github",
+                              "gitlab",
+                              "azure-devops",
+                              "agentmail",
+                              "system",
+                              "schedule",
+                              "workflow",
+                              "linear",
+                              "jira",
+                              "comb",
+                              "chat"
+                            ],
+                            "default": "mcp"
+                          },
+                          "taskType": {
+                            "type": "string",
+                            "maxLength": 50
+                          },
+                          "tags": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            },
+                            "default": []
+                          },
+                          "priority": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "maximum": 100,
+                            "default": 50
+                          },
+                          "dependsOn": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            },
+                            "default": []
+                          },
+                          "offeredTo": {
+                            "type": "string"
+                          },
+                          "acceptedAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "parentTaskId": {
+                            "type": "string"
+                          },
+                          "scheduleId": {
+                            "type": "string"
+                          },
+                          "model": {
+                            "type": "string"
+                          },
+                          "modelTier": {
+                            "type": "string",
+                            "enum": [
+                              "smol",
+                              "regular",
+                              "smart",
+                              "ultra"
+                            ]
+                          },
+                          "resolvedModel": {
+                            "type": "string"
+                          },
+                          "modelSource": {
+                            "type": "string"
+                          },
+                          "modelAlias": {
+                            "type": "string"
+                          },
+                          "effort": {
+                            "type": "string",
+                            "enum": [
+                              "off",
+                              "low",
+                              "medium",
+                              "high",
+                              "xhigh",
+                              "max"
+                            ]
+                          },
+                          "resolvedEffort": {
+                            "type": "string",
+                            "enum": [
+                              "off",
+                              "low",
+                              "medium",
+                              "high",
+                              "xhigh",
+                              "max"
+                            ]
+                          },
+                          "provider": {
+                            "type": "string",
+                            "enum": [
+                              "claude",
+                              "codex",
+                              "pi",
+                              "devin",
+                              "claude-managed",
+                              "opencode",
+                              "acp",
+                              "dsh",
+                              "amp",
+                              "cursor",
+                              "grok"
+                            ]
+                          },
+                          "requestedByUserId": {
+                            "type": "string"
+                          },
+                          "progress": {
+                            "type": "string"
+                          },
+                          "createdAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "lastUpdatedAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "finishedAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "peakContextPercent": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 100
+                          },
+                          "totalCostUsd": {
+                            "type": "number",
+                            "minimum": 0
+                          },
+                          "workflowRunId": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "key",
+                          "agentId",
+                          "task",
+                          "status",
+                          "createdAt",
+                          "lastUpdatedAt"
+                        ]
+                      }
+                    },
+                    "truncated": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "rootTaskId",
+                    "tasks",
+                    "truncated"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "A user caller cannot read the task's session",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Task not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/tasks/{id}/progress": {
       "post": {
         "summary": "Update task progress text",
@@ -54216,7 +54612,8 @@
                     "type": "string",
                     "enum": [
                       "banner",
-                      "settings"
+                      "settings",
+                      "benchmark"
                     ],
                     "default": "banner"
                   }
@@ -55323,7 +55720,7 @@
     "/api/fleet-benchmark": {
       "get": {
         "summary": "Compare this swarm with similar swarms",
-        "description": "Places this swarm's tasks per week and task success rate (last 30 days) in the fleet percentiles published by the telemetry proxy, against swarms with the same agent count when enough exist. Needs telemetry on and an organization name; otherwise `state` says what is missing and the proxy is not called. `unavailable` also covers an install whose first event the proxy saw cannot be established locally (until 30 days after the first accepted event). The fleet numbers are cached for a day.",
+        "description": "Compares local task volume and success rate with fleet percentiles over the last 30 days. Comparisons require telemetry, an organization name, and a known proxy ingest date. A website, team size, and use case enable full comparisons with peer filters. The response includes the proxy's peer group when available. With telemetry off, it returns local DB counts without a proxy request. The fleet cache key includes the peer filters.",
         "tags": [
           "Telemetry"
         ],
@@ -55350,6 +55747,41 @@
                         "unavailable"
                       ]
                     },
+                    "level": {
+                      "type": "string",
+                      "enum": [
+                        "basic",
+                        "full"
+                      ]
+                    },
+                    "peerGroup": {
+                      "type": [
+                        "object",
+                        "null"
+                      ],
+                      "properties": {
+                        "teamSize": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "useCase": {
+                          "type": [
+                            "string",
+                            "null"
+                          ]
+                        },
+                        "orgs": {
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "teamSize",
+                        "useCase",
+                        "orgs"
+                      ]
+                    },
                     "local": {
                       "type": [
                         "object",
@@ -55455,6 +55887,8 @@
                   },
                   "required": [
                     "state",
+                    "level",
+                    "peerGroup",
                     "local",
                     "minFinishedTasks",
                     "generatedAt",
@@ -55744,7 +56178,8 @@
                     "minLength": 1
                   },
                   "email": {
-                    "type": "string"
+                    "type": "string",
+                    "format": "email"
                   },
                   "role": {
                     "type": "string"
@@ -56524,7 +56959,11 @@
                     "minLength": 1
                   },
                   "email": {
-                    "type": "string"
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "format": "email"
                   },
                   "role": {
                     "type": "string"