@desplega.ai/agent-swarm 1.131.0 → 1.133.1

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.131.0",
+    "version": "1.133.1",
     "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": [
@@ -69,6 +69,12 @@
               "null"
             ]
           },
+          "runtimeInstanceId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
           "startedAt": {
             "type": "string",
             "format": "date-time"
@@ -1264,6 +1270,8 @@
               "system.boot",
               "system.migration",
               "system.error",
+              "system.profile_sync_rejected",
+              "system.profile_sync_reconciled",
               "script.global_upsert",
               "schedule.deleted"
             ]
@@ -2329,6 +2337,20 @@
           "changeReason"
         ]
       },
+      "UserCommsPrefs": {
+        "type": "object",
+        "properties": {
+          "tone": {
+            "type": "string"
+          },
+          "language": {
+            "type": "string"
+          },
+          "verbosity": {
+            "type": "string"
+          }
+        }
+      },
       "BudgetRefusedTrigger": {
         "type": "object",
         "properties": {
@@ -4289,6 +4311,9 @@
           "error": {
             "type": "string"
           },
+          "createdBy": {
+            "type": "string"
+          },
           "startedAt": {
             "type": "string"
           },
@@ -4694,6 +4719,9 @@
                   },
                   "runnerSessionId": {
                     "type": "string"
+                  },
+                  "runtimeInstanceId": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -5048,6 +5076,108 @@
         }
       }
     },
+    "/ping": {
+      "post": {
+        "summary": "Report agent liveness",
+        "description": "Refreshes the calling agent's status. Workers may send `X-Runtime-Instance-ID`, the per-boot identifier of the calling process. It is ignored unless MULTI_RUNTIME_ENABLED is set. With multi-runtime mode on, the header must identify a live runtime of this agent; an absent, unknown, offline, or foreign identifier makes the call a no-op instead of an error, so workers predating the flag keep running.",
+        "tags": [
+          "Core"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to refresh a runtime's liveness when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise."
+            },
+            "required": false,
+            "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to refresh a runtime's liveness when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+            "name": "X-Runtime-Instance-ID",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Liveness recorded (or accepted as a no-op)"
+          },
+          "400": {
+            "description": "Missing X-Agent-ID header",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/close": {
+      "post": {
+        "summary": "Mark an agent or runtime offline on shutdown",
+        "description": "Retires the calling process. Workers may send `X-Runtime-Instance-ID`, the per-boot identifier of the calling process. It is ignored unless MULTI_RUNTIME_ENABLED is set. With multi-runtime mode on, the header is required and only that runtime is retired; the agent goes offline once no live runtime remains. With the flag off, the agent is marked offline as before.",
+        "tags": [
+          "Core"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to retire a runtime when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise."
+            },
+            "required": false,
+            "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to retire a runtime when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+            "name": "X-Runtime-Instance-ID",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Runtime (and agent, when last) marked offline"
+          },
+          "400": {
+            "description": "Missing X-Agent-ID, or missing X-Runtime-Instance-ID in multi-runtime mode",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/apps/{id}/user-config": {
       "get": {
         "summary": "Get app user configuration",
@@ -8386,6 +8516,26 @@
                 }
               }
             }
+          },
+          "408": {
+            "description": "Query exceeded its wall-clock budget and was terminated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Too many concurrent bounded db-query executions; retry shortly",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
           }
         }
       }
@@ -8450,6 +8600,10 @@
                       "claude-managed",
                       "opencode"
                     ]
+                  },
+                  "runtimeInstanceId": {
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "required": [
@@ -9090,6 +9244,116 @@
         }
       }
     },
+    "/api/agents/{id}/runtime-instances": {
+      "get": {
+        "summary": "List runtime instances serving an agent",
+        "description": "Read-only view of the worker processes currently registered for a logical agent. Rows exist only for multi-runtime registrations (MULTI_RUNTIME_ENABLED), so the list is empty in the default configuration. `isLive` combines `status` with `lastSeenAt` freshness against the server's staleness cutoff (`staleThresholdMinutes`); `reportedSlots` is each process's self-reported capacity, distinct from the agent's logical `maxTasks` policy.",
+        "tags": [
+          "Agents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Runtime instances for the agent (empty when none are registered)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "runtimeInstances": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string"
+                          },
+                          "agentId": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "active",
+                              "offline"
+                            ]
+                          },
+                          "reportedSlots": {
+                            "type": "integer"
+                          },
+                          "credentialReady": {
+                            "type": [
+                              "boolean",
+                              "null"
+                            ]
+                          },
+                          "lastSeenAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "createdAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updatedAt": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "isLive": {
+                            "type": "boolean"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "agentId",
+                          "status",
+                          "reportedSlots",
+                          "lastSeenAt",
+                          "createdAt",
+                          "updatedAt",
+                          "isLive"
+                        ]
+                      }
+                    },
+                    "staleThresholdMinutes": {
+                      "type": "integer"
+                    }
+                  },
+                  "required": [
+                    "runtimeInstances",
+                    "staleThresholdMinutes"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/agents/{id}/profile": {
       "put": {
         "summary": "Update agent profile (role, description, capabilities, etc.)",
@@ -9131,24 +9395,20 @@
                     }
                   },
                   "claudeMd": {
-                    "type": "string",
-                    "maxLength": 262144
+                    "type": "string"
                   },
                   "soulMd": {
-                    "type": "string",
-                    "maxLength": 262144
+                    "type": "string"
                   },
                   "identityMd": {
-                    "type": "string",
-                    "maxLength": 262144
+                    "type": "string"
                   },
                   "setupScript": {
                     "type": "string",
                     "maxLength": 262144
                   },
                   "toolsMd": {
-                    "type": "string",
-                    "maxLength": 262144
+                    "type": "string"
                   },
                   "heartbeatMd": {
                     "type": "string",
@@ -9242,11 +9502,56 @@
             }
           },
           "400": {
-            "description": "Validation error",
+            "description": "Validation or identity-field budget error",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "profileSyncRejection": {
+                      "type": "object",
+                      "properties": {
+                        "field": {
+                          "type": "string",
+                          "enum": [
+                            "soulMd",
+                            "identityMd",
+                            "claudeMd",
+                            "toolsMd"
+                          ]
+                        },
+                        "diskSize": {
+                          "type": "integer"
+                        },
+                        "dbSize": {
+                          "type": "integer"
+                        },
+                        "budget": {
+                          "type": "integer"
+                        },
+                        "delta": {
+                          "type": "integer"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "field",
+                        "diskSize",
+                        "dbSize",
+                        "budget",
+                        "delta",
+                        "reason"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
                 }
               }
             }
@@ -9405,6 +9710,16 @@
             "required": true,
             "name": "id",
             "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to report credential readiness when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise."
+            },
+            "required": false,
+            "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to report credential readiness when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+            "name": "X-Runtime-Instance-ID",
+            "in": "header"
           }
         ],
         "requestBody": {
@@ -9485,6 +9800,16 @@
               }
             }
           },
+          "400": {
+            "description": "Missing X-Runtime-Instance-ID in multi-runtime mode",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Agent not found",
             "content": {
@@ -14018,6 +14343,8 @@
                       "system.boot",
                       "system.migration",
                       "system.error",
+                      "system.profile_sync_rejected",
+                      "system.profile_sync_reconciled",
                       "script.global_upsert",
                       "schedule.deleted"
                     ]
@@ -14163,6 +14490,8 @@
                 "system.boot",
                 "system.migration",
                 "system.error",
+                "system.profile_sync_rejected",
+                "system.profile_sync_reconciled",
                 "script.global_upsert",
                 "schedule.deleted"
               ]
@@ -14224,6 +14553,14 @@
             "name": "sessionId",
             "in": "query"
           },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "dataField",
+            "in": "query"
+          },
           {
             "schema": {
               "type": "string"
@@ -14333,6 +14670,8 @@
                             "system.boot",
                             "system.migration",
                             "system.error",
+                            "system.profile_sync_rejected",
+                            "system.profile_sync_reconciled",
                             "script.global_upsert",
                             "schedule.deleted"
                           ]
@@ -22344,6 +22683,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to poll for work when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise."
+            },
+            "required": false,
+            "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to poll for work when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+            "name": "X-Runtime-Instance-ID",
+            "in": "header"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Trigger data or null",
@@ -22368,6 +22719,30 @@
                             },
                             "task": {
                               "$ref": "#/components/schemas/AgentTask"
+                            },
+                            "requestedBy": {
+                              "type": "object",
+                              "properties": {
+                                "name": {
+                                  "type": "string",
+                                  "minLength": 1
+                                },
+                                "email": {
+                                  "type": "string"
+                                },
+                                "role": {
+                                  "type": "string"
+                                },
+                                "notes": {
+                                  "type": "string"
+                                },
+                                "comms": {
+                                  "$ref": "#/components/schemas/UserCommsPrefs"
+                                }
+                              },
+                              "required": [
+                                "name"
+                              ]
                             }
                           },
                           "required": [
@@ -22444,6 +22819,9 @@
                                 },
                                 "notes": {
                                   "type": "string"
+                                },
+                                "comms": {
+                                  "$ref": "#/components/schemas/UserCommsPrefs"
                                 }
                               },
                               "required": [
@@ -23492,7 +23870,9 @@
                     }
                   },
                   "priority": {
-                    "type": "integer"
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100
                   },
                   "targetAgentId": {
                     "type": "string"
@@ -24685,7 +25065,9 @@
                     }
                   },
                   "priority": {
-                    "type": "integer"
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100
                   },
                   "targetAgentId": {
                     "type": [
@@ -25013,7 +25395,9 @@
                     }
                   },
                   "priority": {
-                    "type": "integer"
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100
                   },
                   "targetAgentId": {
                     "type": [
@@ -31882,6 +32266,15 @@
                         },
                         "attributedCostUsd": {
                           "type": "number"
+                        },
+                        "attributableCostUsd": {
+                          "type": "number"
+                        },
+                        "excludedCostUsd": {
+                          "type": "number"
+                        },
+                        "excludedTaskCount": {
+                          "type": "integer"
                         }
                       },
                       "required": [
@@ -31893,7 +32286,10 @@
                         "totalDurationMs",
                         "totalSessions",
                         "avgCostPerSession",
-                        "attributedCostUsd"
+                        "attributedCostUsd",
+                        "attributableCostUsd",
+                        "excludedCostUsd",
+                        "excludedTaskCount"
                       ]
                     },
                     "daily": {
@@ -32021,6 +32417,92 @@
         }
       }
     },
+    "/api/attribution/by-person": {
+      "get": {
+        "summary": "Four-metric per-person attribution (problems initiated/shipped, reach)",
+        "tags": [
+          "Session Data"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "startDate",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "endDate",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Per-person attribution rows",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "rows": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "userId": {
+                            "type": "string"
+                          },
+                          "problemsInitiated": {
+                            "type": "integer"
+                          },
+                          "problemsShipped": {
+                            "type": "integer"
+                          },
+                          "agentsReached": {
+                            "type": "integer"
+                          },
+                          "reposReached": {
+                            "type": "integer"
+                          },
+                          "surfacesReached": {
+                            "type": "integer"
+                          },
+                          "firstPassYield": {
+                            "type": "null"
+                          }
+                        },
+                        "required": [
+                          "userId",
+                          "problemsInitiated",
+                          "problemsShipped",
+                          "agentsReached",
+                          "reposReached",
+                          "surfacesReached",
+                          "firstPassYield"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "rows"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/session-costs/dashboard": {
       "get": {
         "summary": "Cost today and month-to-date for dashboard",
@@ -33867,6 +34349,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to acquire work through the script SDK when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise."
+            },
+            "required": false,
+            "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to acquire work through the script SDK when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+            "name": "X-Runtime-Instance-ID",
+            "in": "header"
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -35297,6 +35791,18 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to acquire work through bridged tools when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise."
+            },
+            "required": false,
+            "description": "Identifies the concrete runtime instance (worker process) making the call, as generated at its boot. Required to acquire work through bridged tools when multi-runtime mode (MULTI_RUNTIME_ENABLED) is on; ignored otherwise.",
+            "name": "X-Runtime-Instance-ID",
+            "in": "header"
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -37435,7 +37941,9 @@
                     }
                   },
                   "priority": {
-                    "type": "integer"
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100
                   },
                   "dependsOn": {
                     "type": "array",
@@ -41244,6 +41752,24 @@
                     ],
                     "additionalProperties": {}
                   },
+                  "comms": {
+                    "type": [
+                      "object",
+                      "null"
+                    ],
+                    "properties": {
+                      "tone": {
+                        "type": "string"
+                      },
+                      "language": {
+                        "type": "string"
+                      },
+                      "verbosity": {
+                        "type": "string"
+                      }
+                    },
+                    "description": "Merges into metadata.comms without touching sibling metadata keys; null removes only the comms key. When metadata is also provided, it is applied first and replaces the whole blob."
+                  },
                   "dailyBudgetUsd": {
                     "type": [
                       "number",