agent-relay-server 0.10.20 → 0.10.21

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.10.19",
+    "version": "0.10.20",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -2631,10 +2631,11 @@
     "/api/orchestrators/{id}/actions": {
       "post": {
         "operationId": "postOrchestratorAction",
-        "summary": "Post Orchestrator Action",
+        "summary": "Run an orchestrator action",
         "tags": [
           "Orchestrators"
         ],
+        "description": "Dispatches a host action to the orchestrator over the command bus. `restart`/`shutdown` target a managed agent (omit `agentId` for all). `upgrade` triggers a remote self-upgrade: the relay stamps a desired version and the orchestrator installs it via the bundled `agent-relay upgrade --no-restart` CLI, then restarts itself decoupled (systemd-run) so the bus keepalive survives its own teardown. The upgrade command is intentionally left `running` — the relay settles it (succeeded/failed) by reconciling the version the orchestrator reports on its post-restart re-register, within a deadline. Safety rails: semver-only `targetVersion` (defaults to the relay's own version), npm-registry providers only, and no downgrade unless `force` is set. Requires systemd --user supervision on the orchestrator host.",
         "parameters": [
           {
             "name": "id",
@@ -2651,27 +2652,57 @@
             "application/json": {
               "schema": {
                 "type": "object",
+                "required": [
+                  "action"
+                ],
                 "properties": {
                   "action": {
-                    "type": "string"
+                    "type": "string",
+                    "enum": [
+                      "restart",
+                      "shutdown",
+                      "upgrade"
+                    ],
+                    "description": "Action to dispatch."
+                  },
+                  "targetVersion": {
+                    "type": "string",
+                    "description": "upgrade only — semver (e.g. 0.10.21) to install. Defaults to the relay's own version (fleet target) when omitted."
+                  },
+                  "providers": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "upgrade only — packages to upgrade. Defaults to [\"orchestrator\"]."
+                  },
+                  "force": {
+                    "type": "boolean",
+                    "description": "upgrade only — allow a downgrade (targetVersion < current)."
                   },
                   "agentId": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "restart/shutdown only — managed agent id to target; omit to target all."
                   },
                   "policyName": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "restart/shutdown only — managed policy correlation."
                   },
                   "spawnRequestId": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "restart/shutdown only — spawn request correlation."
                   },
                   "sessionName": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "restart/shutdown only."
                   },
                   "tmuxSession": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "restart/shutdown only."
                   },
                   "reason": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "restart/shutdown only — human-readable reason (default \"manual\")."
                   }
                 }
               }
@@ -2679,37 +2710,17 @@
           }
         },
         "responses": {
-          "200": {
-            "description": "Success",
-            "content": {
-              "application/json": {}
-            }
-          },
           "202": {
-            "description": "HTTP 202",
-            "content": {
-              "application/json": {}
-            }
+            "description": "Accepted. The command was created and emitted on the bus. For `upgrade`, the response includes the created command and the resolved `targetVersion`, and the orchestrator's `upgrade` state is stamped `pending` (settled later via version reconciliation)."
           },
           "400": {
-            "description": "Bad request",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
+            "description": "Invalid body — missing/unknown `action`, or `targetVersion` is not valid semver."
           },
           "404": {
-            "description": "Not found",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
+            "description": "Orchestrator not found."
+          },
+          "409": {
+            "description": "Refusing downgrade — `targetVersion` is older than the orchestrator's current version; pass `force: true` to override."
           }
         },
         "security": [
@@ -3492,6 +3503,95 @@
         ]
       }
     },
+    "/api/workspaces/orphans": {
+      "get": {
+        "operationId": "getWorkspaceOrphans",
+        "summary": "List orphaned worktrees",
+        "tags": [
+          "Other"
+        ],
+        "description": "Worktrees found on disk (agent/* branches) with no live workspace row — left behind by crashes or failed cleanups. Probes each known repo's owning online orchestrator and subtracts active DB rows. Returns `{ orphans: [...] }` (empty with a `reason` when no orchestrator is online). Reclaim via POST /api/workspaces/orphans/reclaim.",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/workspaces/orphans/reclaim": {
+      "post": {
+        "operationId": "postWorkspaceOrphanReclaim",
+        "summary": "Reclaim an orphaned worktree",
+        "tags": [
+          "Other"
+        ],
+        "description": "Removes an orphaned worktree (and its branch) from the host via a `workspace.cleanup` command. Body: `worktreePath`, `repoRoot`, optional `branch`. Refuses (409) if the path still backs a live workspace row, or if no online orchestrator owns the path. Requires `command:write`. Returns 202 with the created command.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "worktreePath",
+                  "repoRoot"
+                ],
+                "properties": {
+                  "worktreePath": {
+                    "type": "string",
+                    "description": "Absolute path of the orphaned worktree to remove."
+                  },
+                  "repoRoot": {
+                    "type": "string",
+                    "description": "Repo root the worktree belongs to (for orchestrator routing)."
+                  },
+                  "branch": {
+                    "type": "string",
+                    "description": "Agent branch to delete after worktree removal."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Reclaim command created and emitted."
+          },
+          "400": {
+            "description": "Missing worktreePath/repoRoot."
+          },
+          "409": {
+            "description": "Path backs a live workspace, or no online orchestrator owns it."
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/workspaces/{id}": {
       "get": {
         "operationId": "getWorkspaceById",
@@ -3538,15 +3638,201 @@
             "tokenQuery": []
           }
         ]
+      },
+      "delete": {
+        "operationId": "deleteWorkspaceById",
+        "summary": "Purge a workspace record (last resort)",
+        "tags": [
+          "Other"
+        ],
+        "description": "Removes the workspace's DB row only — it does NOT touch the worktree on disk. Use the `cleanup` action to remove the worktree. This is the escape hatch for rows whose owning orchestrator is gone for good and can no longer run a cleanup command. Requires `command:write` scope.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/workspaces/{id}/git-state": {
+      "get": {
+        "operationId": "getWorkspaceGitState",
+        "summary": "Get live git state of a workspace worktree",
+        "tags": [
+          "Other"
+        ],
+        "description": "Returns ahead/behind base commit counts, dirty file count, and last commit for the workspace's isolated worktree, computed on the host by the owning orchestrator. Degrades to `{ available: false, reason }` when no online orchestrator owns the path or the workspace has no worktree.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "strategy",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/workspaces/{id}/merge-preview": {
+      "get": {
+        "operationId": "getWorkspaceMergePreview",
+        "summary": "Pre-flight check for merging a workspace's work",
+        "tags": [
+          "Other"
+        ],
+        "description": "Returns whether the workspace's branch can be cleanly integrated into its base: ahead/behind counts, predicted conflict (three-way merge-tree), clean-fast-forward eligibility, whether a remote and `gh` are available, and the strategy `auto` would resolve to (`pr` when a remote + gh + base branch exist, else `rebase-ff`). Computed on the host by the owning orchestrator. Optional `?strategy=` (`pr`|`rebase-ff`|`auto`) overrides the resolved strategy. Degrades to `{ available: false, reason }` when no online orchestrator owns the path or the workspace has no worktree.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "strategy",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/workspaces/{id}/diff": {
+      "get": {
+        "operationId": "getWorkspaceDiff",
+        "summary": "Diff a workspace against its base",
+        "tags": [
+          "Other"
+        ],
+        "description": "Per-file line counts and a size-capped unified patch for the workspace's committed work (base...HEAD), computed on the host by the owning orchestrator. `?patch=0` omits the patch body (file list only). Degrades to `{ available: false, reason }` when the host is offline or there's no worktree.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "patch",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
       }
     },
     "/api/workspaces/{id}/actions": {
       "post": {
         "operationId": "postWorkspaceAction",
-        "summary": "Post Workspace Action",
+        "summary": "Run a workspace action",
         "tags": [
           "Other"
         ],
+        "description": "Transitions a workspace's lifecycle state and, for command actions, dispatches to the owning orchestrator over the command bus. Actions: `status` (read), `ready`, `request-review`, `conflict-found`, `merge-plan` (soft labels), `merge` (real integration — `workspace.merge` command: rebase + fast-forward into base or open a PR via `gh`, then delete the branch on success; accepts `strategy` (`pr`|`rebase-ff`|`auto`, default `auto`), `prTitle`, `prBody`, `deleteBranch`), `cleanup` (remove the worktree), and `abandon`. `merge`/`cleanup` require an online orchestrator owning the path and return 202 with the created command; the final status is reconciled from the command result.",
         "parameters": [
           {
             "name": "id",
@@ -3563,18 +3849,52 @@
             "application/json": {
               "schema": {
                 "type": "object",
+                "required": [
+                  "action"
+                ],
                 "properties": {
                   "action": {
-                    "type": "string"
+                    "type": "string",
+                    "enum": [
+                      "status",
+                      "ready",
+                      "request-review",
+                      "conflict-found",
+                      "merge-plan",
+                      "merge",
+                      "cleanup",
+                      "abandon"
+                    ],
+                    "description": "Lifecycle action to apply."
+                  },
+                  "strategy": {
+                    "type": "string",
+                    "enum": [
+                      "pr",
+                      "rebase-ff",
+                      "auto"
+                    ],
+                    "description": "merge only — integration strategy. `auto` picks PR when a remote + gh + base branch exist, else rebase-ff. Defaults to `auto`."
+                  },
+                  "prTitle": {
+                    "type": "string",
+                    "description": "merge (pr strategy) only — PR title. Defaults to the last commit subject."
+                  },
+                  "prBody": {
+                    "type": "string",
+                    "description": "merge (pr strategy) only — PR body."
+                  },
+                  "deleteBranch": {
+                    "type": "boolean",
+                    "description": "merge only — delete the agent branch + remove the worktree after a successful rebase-ff. Defaults to true."
                   },
                   "agentId": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Optional agent id recorded as the actor."
                   },
                   "detail": {
-                    "type": "string"
-                  },
-                  "metadata": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Optional human-readable note."
                   }
                 }
               }
@@ -3583,40 +3903,19 @@
         },
         "responses": {
           "200": {
-            "description": "Success",
-            "content": {
-              "application/json": {}
-            }
+            "description": "State updated (non-command actions)."
+          },
+          "202": {
+            "description": "Accepted — a `merge`/`cleanup` command was created and emitted on the bus. Final workspace status is reconciled from the command result."
           },
           "400": {
-            "description": "Bad request",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
+            "description": "Invalid body or unknown action."
           },
           "404": {
-            "description": "Not found",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
+            "description": "Workspace not found."
           },
           "409": {
-            "description": "Conflict",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
+            "description": "No online orchestrator owns the workspace path."
           }
         },
         "security": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.10.20",
+  "version": "0.10.21",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -32,7 +32,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.1"
+    "agent-relay-sdk": "0.2.2"
   },
   "scripts": {
     "postinstall": "node scripts/install-bin-shim.cjs",