@huynle/hub 0.11.0 → 0.11.1

package/packages/protocol/schema/api/v1/sessions.json

@@ -0,0 +1,2055 @@
+{
+  "paths": {
+    "/api/v1/machines": {
+      "get": {
+        "operationId": "listMachines",
+        "tags": ["sessions"],
+        "x-hub-access": "user",
+        "summary": "The catalog: the user's machines, their processes and sessions",
+        "description": "What the session list is built from. The live stream (GET /api/v1/events) sends the same list again as a catalog message whenever it changes.",
+        "responses": {
+          "200": {
+            "description": "Every machine of the user, online or not, with the processes connected now and the sessions they report.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MachineCatalog"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}": {
+      "get": {
+        "operationId": "getSession",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "One session: its status tree, blockers and activity",
+        "description": "A subagent session no process lists is answered from its root's status tree. Fails with 404 not_found for a session nobody reports (an offline one too) or another user's.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The session as the processes that report it see it, with its live state.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionView"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/timeline": {
+      "get": {
+        "operationId": "getTimeline",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "A page of the session's transcript",
+        "description": "Two ways to page. Forward: no `order` (or asc), `cursor` from the previous page; the oldest rows come first and `cursor` names the next newer page. Newest first: `order=desc` for the newest rows, then `before=<older>` for the page before them; the rows of a page are still in chronological order. Both cursors are opaque. Read from the session's machine: fails with 409 conflict when no process of the session is connected, 400 invalid for a bad query or a cursor whose row is gone (history reverted or compacted: start over), 404 not_found for an unknown or another user's session.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Rows per page, 1 to 200 (the spoke's default: 50).",
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 1,
+              "maximum": 200
+            }
+          },
+          {
+            "name": "order",
+            "in": "query",
+            "description": "desc: the newest page first (newest-first paging).",
+            "schema": {
+              "type": "string",
+              "enum": ["asc", "desc"]
+            }
+          },
+          {
+            "name": "before",
+            "in": "query",
+            "description": "Newest-first paging: the `older` of the page after this one.",
+            "schema": {
+              "type": "string",
+              "maxLength": 4096
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "description": "Forward paging: the `cursor` of the previous page. Not with `before` or order=desc.",
+            "schema": {
+              "type": "string",
+              "maxLength": 4096
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A page of rows, in chronological order.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TimelinePage"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/messages": {
+      "get": {
+        "operationId": "listSessionMessages",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "The agent messages the session sent or received",
+        "description": "Hub messages between sessions, the user and apps (the messaging area). Also answers for an offline session the user's directory knows. Messages of a history a committed revert removed are left out. Fails with 400 invalid for a bad limit.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "At most this many, 1 to 200 (default: every message the session keeps, up to 200).",
+            "schema": {
+              "type": "integer",
+              "format": "int32",
+              "minimum": 1,
+              "maximum": 200
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Newest first. A client merges them into the timeline by `at`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionMessageList"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/timeline/messages/{message}/parts/{part}": {
+      "get": {
+        "operationId": "getTimelinePart",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "The full detail of a tool row",
+        "description": "What a timeline row leaves out of a tool call: its whole input, output and state. Embedded images are replaced by small placeholders. Read from the session's machine (409 conflict when none is connected); a detail too large to display fails.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "message",
+            "in": "path",
+            "required": true,
+            "description": "The timeline row's messageID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "part",
+            "in": "path",
+            "required": true,
+            "description": "The tool row's partID.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The tool call's detail.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TimelinePart"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/timeline/messages/{message}/files/{index}": {
+      "get": {
+        "operationId": "getTimelineFile",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "An image attached to a user message, by position",
+        "description": "The same image as media/f<index>, which it is on a spoke with the timelineMedia feature (ETag, 304, ?download=1). An older spoke answers in one piece, without an ETag, and serves PNG, JPEG, WebP and GIF only. Fails with 400 invalid for an index outside 0–999, 404 not_found for no such image, 413 too_large for an image too large to show.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "message",
+            "in": "path",
+            "required": true,
+            "description": "The timeline row's messageID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "index",
+            "in": "path",
+            "required": true,
+            "description": "The attachment's position: a user row's files[].index (0–999).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "download",
+            "in": "query",
+            "description": "1: answer as an attachment (Content-Disposition), for saving the image.",
+            "schema": {
+              "type": "string",
+              "enum": ["1"]
+            }
+          },
+          {
+            "name": "If-None-Match",
+            "in": "header",
+            "description": "The ETag of a copy the client holds: the answer is then 304 when it is still current.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The image's bytes. Only image types are served.",
+            "headers": {
+              "ETag": {
+                "description": "The image's SHA-256 as a strong validator (\"sha256-<hex>\"); send it back as If-None-Match. Absent on an older spoke's answer (files/:index without timelineMedia).",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Content-Disposition": {
+                "description": "inline, or attachment with ?download=1 and for SVG, with a file name. Absent on an older spoke's answer.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "image/png": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/jpeg": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/webp": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/gif": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/svg+xml": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "304": {
+            "description": "Not modified: If-None-Match named the image's current ETag. No body."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/timeline/messages/{message}/media/{ref}": {
+      "get": {
+        "operationId": "getTimelineMedia",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "An image of a timeline row, by ref",
+        "description": "A user row's attachment, a tool row's image or an image path in an assistant text, pulled from the session's machine in chunks and cached by the hub. Needs the spoke's timelineMedia feature: else 422 unsupported (with feature and harness). Other failures: 400 invalid (a malformed ref or message ID), 404 (not_found, path: not in the session's files, hidden: hidden by a revert), 413 (too_large, dimensions), 415 type (not an image the hub shows), 429 rate_limited (at most 4 images at once per user, 2 per machine; Retry-After), 502 (bad_answer, integrity: the machine sent a broken image), 504 timeout, 409 conflict (no process of the session connected).",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "message",
+            "in": "path",
+            "required": true,
+            "description": "The timeline row's messageID.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "ref",
+            "in": "path",
+            "required": true,
+            "description": "A media ref, from a row's files[].ref or media[].ref: f<n>, t<part>.<item> or p:<path>. URL-encode it.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "download",
+            "in": "query",
+            "description": "1: answer as an attachment (Content-Disposition), for saving the image.",
+            "schema": {
+              "type": "string",
+              "enum": ["1"]
+            }
+          },
+          {
+            "name": "If-None-Match",
+            "in": "header",
+            "description": "The ETag of a copy the client holds: the answer is then 304 when it is still current.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The image's bytes, whole and verified (length and SHA-256), sniffed to be the type it claims. SVG is always an attachment.",
+            "headers": {
+              "ETag": {
+                "description": "The image's SHA-256 as a strong validator (\"sha256-<hex>\"); send it back as If-None-Match. Absent on an older spoke's answer (files/:index without timelineMedia).",
+                "schema": {
+                  "type": "string"
+                }
+              },
+              "Content-Disposition": {
+                "description": "inline, or attachment with ?download=1 and for SVG, with a file name. Absent on an older spoke's answer.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "image/png": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/jpeg": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/webp": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/gif": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/svg+xml": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "304": {
+            "description": "Not modified: If-None-Match named the image's current ETag. No body."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/reads": {
+      "get": {
+        "operationId": "getReads",
+        "tags": ["sessions"],
+        "x-hub-access": "user",
+        "summary": "When the user last read each session",
+        "description": "A session is unread while it changed after its mark. The live stream sends the marks again as a reads message when another device changes them.",
+        "responses": {
+          "200": {
+            "description": "The user's read marks, shared by all their devices.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ReadMarks"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/read": {
+      "post": {
+        "operationId": "markSessionRead",
+        "tags": ["sessions"],
+        "x-hub-access": "session",
+        "summary": "Mark a session read now",
+        "description": "A mark never moves back. The user's other devices get the marks on the live stream. The body is optional.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MarkReadRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Every read mark of the user, this one included.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ReadMarks"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/prefs/view": {
+      "get": {
+        "operationId": "getViewPrefs",
+        "tags": ["sessions"],
+        "x-hub-access": "user",
+        "summary": "The user's session list preferences",
+        "responses": {
+          "200": {
+            "description": "The hidden (archived) and pinned sessions and workspaces.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ViewPrefsState"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      },
+      "put": {
+        "operationId": "setViewPrefs",
+        "tags": ["sessions"],
+        "x-hub-access": "user",
+        "summary": "Change the user's session list preferences",
+        "description": "Each list given replaces the stored one (duplicates dropped); the others stay. The user's other devices get the change on the live stream. Fails with 400 invalid for an empty body, an unknown key or a list over its limit.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ViewPrefsChange"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The preferences after the change.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ViewPrefsState"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "MachineCatalog": {
+        "type": "object",
+        "required": ["machines"],
+        "properties": {
+          "machines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CatalogMachine"
+            }
+          }
+        }
+      },
+      "CatalogMachine": {
+        "type": "object",
+        "description": "A machine of the user (a computer running the Hub plugin or a harness).",
+        "required": ["id", "name", "created", "lastSeen", "online", "processes"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "created": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the machine was enrolled, in epoch milliseconds."
+          },
+          "lastSeen": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the hub last heard from it, in epoch milliseconds."
+          },
+          "online": {
+            "type": "boolean",
+            "description": "A process of the machine is connected now."
+          },
+          "processes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CatalogProcess"
+            },
+            "description": "Its connected processes, oldest connection first; empty when offline."
+          },
+          "terminals": {
+            "$ref": "#/components/schemas/MachineTerminals"
+          }
+        }
+      },
+      "MachineTerminals": {
+        "type": "object",
+        "description": "The machine's terminal context, as one of its processes reported it. May be empty.",
+        "properties": {
+          "herdr": {
+            "$ref": "#/components/schemas/HerdrTerminals"
+          }
+        }
+      },
+      "HerdrTerminals": {
+        "type": "object",
+        "required": ["workspaces"],
+        "properties": {
+          "workspaces": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/HerdrWorkspace"
+            }
+          }
+        }
+      },
+      "HerdrWorkspace": {
+        "type": "object",
+        "description": "A Herdr workspace on the machine: a place to open new sessions.",
+        "required": ["id", "label", "directories"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string",
+            "description": "e.g. \"research\"."
+          },
+          "directories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Folders of the workspace's panes, most used first."
+          }
+        }
+      },
+      "CatalogProcess": {
+        "type": "object",
+        "description": "A connected process of a machine (a spoke) and the sessions it reports.",
+        "required": [
+          "id",
+          "kind",
+          "directory",
+          "pid",
+          "mode",
+          "opencodeVersion",
+          "pluginVersion",
+          "harness",
+          "harnessVersion",
+          "evidence",
+          "features",
+          "connected",
+          "lastSeen",
+          "sessions"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The process ID the spoke chose."
+          },
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["service", "standalone"],
+            "description": "service: the machine's background service; standalone: a process of its own (an OpenCode TUI)."
+          },
+          "directory": {
+            "type": "string"
+          },
+          "pid": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The operating system's process ID."
+          },
+          "mode": {
+            "type": "string",
+            "x-hub-known": ["always", "session"],
+            "description": "always: every session has Voice; session: Voice is enabled per session."
+          },
+          "opencodeVersion": {
+            "type": "string",
+            "description": "OpenCode's version, as the process said (empty for other harnesses; see harnessVersion)."
+          },
+          "pluginVersion": {
+            "type": "string"
+          },
+          "harness": {
+            "type": "string",
+            "x-hub-known": ["opencode", "claude-code", "codex"],
+            "description": "The harness: opencode, claude-code, codex, …"
+          },
+          "harnessVersion": {
+            "type": "string"
+          },
+          "evidence": {
+            "type": "string",
+            "x-hub-known": ["native", "hooks", "rpc", "screen", "unknown"],
+            "description": "How the process observes a session's activity; a session with unknown evidence never counts as idle."
+          },
+          "features": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "What the process serves (its core operations and optional features), sorted. Clients show a control only when its feature is here."
+          },
+          "connected": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it connected, in epoch milliseconds."
+          },
+          "lastSeen": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the hub last heard from it, in epoch milliseconds."
+          },
+          "sessions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CatalogSession"
+            }
+          },
+          "sessionsPending": {
+            "type": "boolean",
+            "description": "True while the process has not reported its sessions yet: an empty `sessions` says nothing then."
+          }
+        }
+      },
+      "CatalogSession": {
+        "type": "object",
+        "description": "A session as one process reports it. A session reported by several processes appears under each.",
+        "required": ["id", "title", "directory", "updated", "owned", "exposed", "state", "blockers", "processID", "machineID", "status", "busy", "conversation"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "directory": {
+            "type": "string",
+            "description": "The working directory."
+          },
+          "parentID": {
+            "type": "string",
+            "description": "Set on a subagent session: its parent."
+          },
+          "project": {
+            "type": "string",
+            "description": "The workspace (project) root the session belongs to; differs from directory in worktrees and subfolders."
+          },
+          "projectName": {
+            "type": "string"
+          },
+          "updated": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the session last changed, in epoch milliseconds."
+          },
+          "open": {
+            "type": "boolean",
+            "description": "True while the session is open in a terminal (a Herdr pane or an OpenCode TUI)."
+          },
+          "terminal": {
+            "$ref": "#/components/schemas/TerminalInfo"
+          },
+          "revert": {
+            "$ref": "#/components/schemas/SessionRevert"
+          },
+          "revertCommitted": {
+            "$ref": "#/components/schemas/RevertCommitted"
+          },
+          "agent": {
+            "type": "string",
+            "description": "A locked (Concierge) session: the agent it last ran on."
+          },
+          "contextRevision": {
+            "type": "integer",
+            "format": "int64",
+            "description": "A locked (Concierge) session: the context revision its machine holds."
+          },
+          "owned": {
+            "type": "boolean",
+            "description": "This process owns the session: it viewed or ran it most recently."
+          },
+          "archived": {
+            "type": "boolean",
+            "description": "Archived in the harness."
+          },
+          "locked": {
+            "type": "boolean",
+            "description": "True for a session locked as a Concierge session."
+          },
+          "exposed": {
+            "type": "boolean",
+            "description": "Voice is enabled for the session. Reading and typed control do not depend on it; speech does."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["idle", "working", "blocked", "error"],
+            "description": "blocked when anything in the session or below it waits for the user; else error (the session itself failed), working (anything below runs) or idle."
+          },
+          "blockers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Blocker"
+            },
+            "description": "What waits for the user in the session and below it, each with sessionID and sessionTitle."
+          },
+          "now": {
+            "$ref": "#/components/schemas/NowActivity"
+          },
+          "processID": {
+            "type": "string",
+            "description": "The process that reports it."
+          },
+          "machineID": {
+            "type": "string"
+          },
+          "status": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SessionStatus"
+            },
+            "description": "The status tree of the session's root: the root first, then its subagent sessions."
+          },
+          "busy": {
+            "type": "boolean",
+            "description": "A turn the hub started runs in the session."
+          },
+          "conversation": {
+            "type": "boolean",
+            "description": "Conversation mode is on: the assistant's text is spoken."
+          }
+        }
+      },
+      "SessionView": {
+        "type": "object",
+        "description": "One session as the session screen shows it, merged from every process that reports it (the most recent report wins).",
+        "required": ["id", "title", "directory", "updated", "exposed", "state", "blockers", "busy", "conversation", "status", "activity"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "directory": {
+            "type": "string",
+            "description": "The working directory."
+          },
+          "parentID": {
+            "type": "string",
+            "description": "Set on a subagent session: its parent."
+          },
+          "project": {
+            "type": "string",
+            "description": "The workspace (project) root the session belongs to; differs from directory in worktrees and subfolders."
+          },
+          "projectName": {
+            "type": "string"
+          },
+          "updated": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the session last changed, in epoch milliseconds."
+          },
+          "open": {
+            "type": "boolean",
+            "description": "True while the session is open in a terminal (a Herdr pane or an OpenCode TUI)."
+          },
+          "terminal": {
+            "$ref": "#/components/schemas/TerminalInfo"
+          },
+          "revert": {
+            "$ref": "#/components/schemas/SessionRevert"
+          },
+          "revertCommitted": {
+            "$ref": "#/components/schemas/RevertCommitted"
+          },
+          "agent": {
+            "type": "string",
+            "description": "A locked (Concierge) session: the agent it last ran on."
+          },
+          "contextRevision": {
+            "type": "integer",
+            "format": "int64",
+            "description": "A locked (Concierge) session: the context revision its machine holds."
+          },
+          "exposed": {
+            "type": "boolean",
+            "description": "Voice is enabled for the session. Reading and typed control do not depend on it; speech does."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["idle", "working", "blocked", "error"],
+            "description": "blocked when anything in the session or below it waits for the user; else error (the session itself failed), working (anything below runs) or idle."
+          },
+          "blockers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Blocker"
+            },
+            "description": "What waits for the user in the session and below it, each with sessionID and sessionTitle."
+          },
+          "now": {
+            "$ref": "#/components/schemas/NowActivity"
+          },
+          "busy": {
+            "type": "boolean",
+            "description": "A turn the hub started runs in the session."
+          },
+          "conversation": {
+            "type": "boolean",
+            "description": "Conversation mode is on: the assistant's text is spoken."
+          },
+          "status": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SessionStatus"
+            },
+            "description": "The status tree of the root session that contains this one: the root first, then its subagent sessions."
+          },
+          "activity": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ActivityItem"
+            },
+            "description": "Recent activity of the root session and its subagent sessions (at most 30), newest last."
+          }
+        }
+      },
+      "TerminalInfo": {
+        "type": "object",
+        "description": "Where a session is open in a terminal.",
+        "required": ["source"],
+        "properties": {
+          "source": {
+            "type": "string",
+            "x-hub-known": ["herdr", "tui"],
+            "description": "Where it is open."
+          },
+          "workspaceID": {
+            "type": "string",
+            "description": "The Herdr workspace."
+          },
+          "workspace": {
+            "type": "string",
+            "description": "The Herdr workspace's label."
+          },
+          "title": {
+            "type": "string",
+            "description": "The pane's title, e.g. \"OC | Fix the login redirect\"."
+          },
+          "status": {
+            "type": "string",
+            "x-hub-known": ["idle", "working", "blocked", "done", "unknown"],
+            "description": "Herdr's agent status of the pane."
+          }
+        }
+      },
+      "SessionRevert": {
+        "type": "object",
+        "description": "A staged revert: restored with POST …/revert/restore, committed by the next prompt.",
+        "required": ["messageID", "hidden", "files", "filesTotal"],
+        "properties": {
+          "messageID": {
+            "type": "string",
+            "description": "The reverted user message: it and everything after it are hidden."
+          },
+          "hidden": {
+            "type": "integer",
+            "format": "int32",
+            "description": "User messages hidden."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the reverted message was created, in epoch milliseconds."
+          },
+          "files": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RevertFile"
+            },
+            "description": "Files restored (at most 50)."
+          },
+          "filesTotal": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Files restored in all."
+          },
+          "stagedAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was staged, in epoch milliseconds."
+          }
+        }
+      },
+      "RevertFile": {
+        "type": "object",
+        "description": "A file a revert restores.",
+        "required": ["file"],
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Its path in the session's directory."
+          },
+          "status": {
+            "type": "string",
+            "x-hub-known": ["added", "deleted", "modified"]
+          },
+          "additions": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "deletions": {
+            "type": "integer",
+            "format": "int32"
+          }
+        }
+      },
+      "RevertCommitted": {
+        "type": "object",
+        "description": "The latest committed revert's removed window.",
+        "required": ["messageID", "until", "at"],
+        "properties": {
+          "messageID": {
+            "type": "string",
+            "description": "The reverted message: it and everything after it were removed."
+          },
+          "from": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The reverted message's time, in epoch milliseconds."
+          },
+          "until": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the revert was staged, in epoch milliseconds. Hub messages between from and until belonged to the removed history."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was committed, in epoch milliseconds."
+          }
+        }
+      },
+      "NowActivity": {
+        "type": "object",
+        "description": "What the session (or a subagent below it) is doing now: its latest running activity.",
+        "required": ["kind"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["tool", "thinking"]
+          },
+          "tool": {
+            "type": "string",
+            "description": "The tool's name."
+          },
+          "summary": {
+            "type": "string",
+            "description": "A short summary of the tool's input: a command, a path."
+          }
+        }
+      },
+      "SessionStatus": {
+        "type": "object",
+        "description": "One entry of a status tree: a session's own state.",
+        "required": ["id", "title", "state", "blockers"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "parentID": {
+            "type": "string",
+            "description": "A subagent session's parent."
+          },
+          "title": {
+            "type": "string"
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["idle", "working", "blocked", "error"],
+            "description": "blocked: waits for the user (a blocker); error: the last run failed; working; idle."
+          },
+          "detail": {
+            "type": "string",
+            "description": "state error: the error; while retrying: \"Retrying: <why>\"."
+          },
+          "blockers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Blocker"
+            },
+            "description": "What waits for the user in this session (without sessionID and sessionTitle)."
+          },
+          "retry": {
+            "$ref": "#/components/schemas/RetryInfo"
+          },
+          "errorType": {
+            "type": "string",
+            "description": "state error: the error's type (\"provider.quota\", \"tool.execution\", …), when known."
+          },
+          "errorStatus": {
+            "type": "integer",
+            "format": "int32",
+            "description": "state error: the error's HTTP status, when known."
+          },
+          "jobs": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/JobInfo"
+            },
+            "description": "Shells and terminals of the session: running ones, then the last few that ended."
+          },
+          "since": {
+            "type": "integer",
+            "format": "int64",
+            "description": "state working: when the current run started, in epoch milliseconds."
+          },
+          "blockedSince": {
+            "type": "integer",
+            "format": "int64",
+            "description": "state blocked: when the oldest open blocker was first seen, in epoch milliseconds."
+          },
+          "health": {
+            "$ref": "#/components/schemas/SessionHealth"
+          }
+        }
+      },
+      "SessionHealth": {
+        "type": "object",
+        "description": "(SS-1) Why the session is not making progress, next to its state (a session retrying a provider request stays \"working\"). Absent: ok. A kind the client does not know should be shown as-is.",
+        "required": ["kind"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["ok", "retrying", "stalled", "quota", "auth", "model_unavailable", "context_overflow", "network", "failed"],
+            "description": "retrying: the provider request is being retried; stalled: still retrying after 3 attempts or 5 minutes; quota, auth, model_unavailable, context_overflow: retrying will not fix it; network: a connection failure; failed: any other failed run."
+          },
+          "since": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When this kind was first seen, in epoch milliseconds."
+          },
+          "resetAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "quota: when the provider says the limit resets, in epoch milliseconds (when its message says)."
+          },
+          "attempt": {
+            "type": "integer",
+            "format": "int32",
+            "description": "While retrying: the provider retry's attempt number."
+          },
+          "detail": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "The provider's message: one line, secrets redacted, at most 200 characters (untrusted text)."
+          }
+        }
+      },
+      "RetryInfo": {
+        "type": "object",
+        "description": "The model request is being retried (the state stays working).",
+        "properties": {
+          "attempt": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "message": {
+            "type": "string",
+            "description": "Why it retries."
+          },
+          "next": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the next attempt runs, in epoch milliseconds."
+          },
+          "errorType": {
+            "type": "string",
+            "description": "e.g. \"provider.rate-limit\"."
+          },
+          "errorStatus": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The error's HTTP status."
+          }
+        }
+      },
+      "JobInfo": {
+        "type": "object",
+        "description": "A shell or terminal of a session.",
+        "required": ["id", "kind", "status"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["shell", "pty"]
+          },
+          "command": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "x-hub-known": ["running", "exited", "timeout", "killed"]
+          },
+          "exit": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The exit code, once it ended."
+          },
+          "background": {
+            "type": "boolean"
+          },
+          "started": {
+            "type": "integer",
+            "format": "int64",
+            "description": "In epoch milliseconds."
+          },
+          "ended": {
+            "type": "integer",
+            "format": "int64",
+            "description": "In epoch milliseconds."
+          }
+        }
+      },
+      "Blocker": {
+        "description": "Something a session waits for the user to answer: a permission request (answered with POST /api/v1/sessions/{session}/permission) or a form, which includes the agent's questions (POST …/form). In a session's `blockers` (the catalog, the session view) each carries the session it was asked in (sessionID, sessionTitle); in a status entry's it does not.",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/PermissionBlocker"
+          },
+          {
+            "$ref": "#/components/schemas/FormBlocker"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "kind",
+          "mapping": {
+            "permission": "#/components/schemas/PermissionBlocker",
+            "form": "#/components/schemas/FormBlocker"
+          }
+        },
+        "x-hub-union": true
+      },
+      "PermissionBlocker": {
+        "type": "object",
+        "description": "A permission request.",
+        "required": ["kind", "id", "summary"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["permission"]
+          },
+          "id": {
+            "type": "string",
+            "description": "The request's ID."
+          },
+          "summary": {
+            "type": "string",
+            "description": "What it asks, as one line: \"<action>: <resources>\"."
+          },
+          "action": {
+            "type": "string",
+            "description": "What the agent asks to do: \"bash\", \"edit\", \"read\", an MCP tool, …"
+          },
+          "resources": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "What it applies to (commands, paths): at most 10, each shortened."
+          },
+          "recommendation": {
+            "$ref": "#/components/schemas/BlockerRecommendation"
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it was asked in."
+          },
+          "sessionTitle": {
+            "type": "string",
+            "description": "That session's title."
+          }
+        }
+      },
+      "FormBlocker": {
+        "type": "object",
+        "description": "A form, or a question of the agent.",
+        "required": ["kind", "id", "summary"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["form"]
+          },
+          "id": {
+            "type": "string",
+            "description": "The form's ID."
+          },
+          "summary": {
+            "type": "string",
+            "description": "The form's title (\"question\" when it has none)."
+          },
+          "question": {
+            "type": "boolean",
+            "description": "True when the agent's question tool asked it."
+          },
+          "fields": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FormField"
+            },
+            "description": "The fields a client can render (at most 20). Absent when the form was too large to carry: it is answered in the terminal then."
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it was asked in."
+          },
+          "sessionTitle": {
+            "type": "string",
+            "description": "That session's title."
+          }
+        }
+      },
+      "BlockerRecommendation": {
+        "type": "object",
+        "description": "An agent escalated the permission request (it was outside its grant) and recommends an answer.",
+        "required": ["by"],
+        "properties": {
+          "by": {
+            "type": "string",
+            "description": "The agent that recommends, as the hub names it."
+          },
+          "recommends": {
+            "type": "string",
+            "x-hub-known": ["approve"],
+            "description": "Absent: it recommends nothing and only links its Decision."
+          },
+          "why": {
+            "type": "string"
+          },
+          "decisionID": {
+            "type": "string",
+            "description": "The Decision the user answers it in."
+          }
+        }
+      },
+      "FormField": {
+        "type": "object",
+        "description": "A field of a form, with what a client needs to render and check it.",
+        "required": ["key", "type"],
+        "properties": {
+          "key": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string",
+            "x-hub-known": ["string", "number", "integer", "boolean", "multiselect", "external"],
+            "description": "A field of a type the client does not know cannot be answered there."
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FormOption"
+            },
+            "description": "string and multiselect: the choices."
+          },
+          "custom": {
+            "type": "boolean",
+            "description": "With options: free text is allowed besides them."
+          },
+          "placeholder": {
+            "type": "string"
+          },
+          "default": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The default: a string, a number, a boolean or a list of strings (multiselect)."
+          },
+          "minimum": {
+            "type": "number"
+          },
+          "maximum": {
+            "type": "number"
+          },
+          "minLength": {
+            "type": "number"
+          },
+          "maxLength": {
+            "type": "number"
+          },
+          "minItems": {
+            "type": "number"
+          },
+          "maxItems": {
+            "type": "number"
+          },
+          "format": {
+            "type": "string"
+          },
+          "pattern": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string",
+            "description": "external: the link the user follows."
+          },
+          "when": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FormCondition"
+            },
+            "description": "Shown only when all of these hold."
+          }
+        }
+      },
+      "FormOption": {
+        "type": "object",
+        "required": ["value", "label"],
+        "properties": {
+          "value": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          }
+        }
+      },
+      "FormCondition": {
+        "type": "object",
+        "description": "A condition on another field's value.",
+        "required": ["key", "op", "value"],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Another field's key."
+          },
+          "op": {
+            "type": "string",
+            "x-hub-known": ["eq", "neq"]
+          },
+          "value": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "A string, a number or a boolean."
+          }
+        }
+      },
+      "ActivityItem": {
+        "type": "object",
+        "description": "A tool call or a stretch of reasoning in a root session or below it.",
+        "required": ["id", "sessionID", "kind", "state", "at"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The tool call's ID, or thinking:<assistant message ID>."
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "Where it happened: the root or a subagent session."
+          },
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["tool", "thinking"]
+          },
+          "tool": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string",
+            "description": "A short summary of the tool's input."
+          },
+          "background": {
+            "type": "boolean",
+            "description": "The tool was started in the background."
+          },
+          "childSessionID": {
+            "type": "string",
+            "description": "A subagent tool: the session it runs."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["running", "done", "failed"]
+          },
+          "error": {
+            "type": "string"
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was created, then when its state last changed, in epoch milliseconds."
+          }
+        }
+      },
+      "TimelinePage": {
+        "type": "object",
+        "description": "A page of a session's transcript.",
+        "required": ["items"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimelineItem"
+            },
+            "description": "Rows in chronological order (sorted by pos where present)."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Forward paging: pass as `cursor` for the next newer page; absent at the end."
+          },
+          "older": {
+            "type": "string",
+            "description": "Newest-first paging: pass as `before` for the page before this one; absent at the beginning."
+          }
+        }
+      },
+      "TimelineItem": {
+        "type": "object",
+        "description": "One row of the transcript. Which fields a row has depends on its kind.",
+        "required": ["key", "messageID", "sessionID", "kind"],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Unique and stable in the session."
+          },
+          "messageID": {
+            "type": "string",
+            "description": "The harness's message (a message row: the hub message's ID)."
+          },
+          "partID": {
+            "type": "string",
+            "description": "The part of the message (assistant, reasoning and tool rows): the part of …/parts/{part}."
+          },
+          "sessionID": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["user", "assistant", "reasoning", "tool", "message", "error", "retry"],
+            "description": "user: the user's prompt; assistant: text of the agent; reasoning; tool: a tool call; message: a hub message delivered to the session; error: the turn failed; retry: the model request is being retried. A row of a kind the client does not know can be skipped."
+          },
+          "text": {
+            "type": "string",
+            "description": "user, assistant, reasoning, message: the text; error, retry: the error's message."
+          },
+          "name": {
+            "type": "string",
+            "description": "tool: the tool's name."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["running", "done", "failed"],
+            "description": "reasoning and tool rows."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was created, in epoch milliseconds (never used to order rows: see pos)."
+          },
+          "completed": {
+            "type": "integer",
+            "format": "int64",
+            "description": "reasoning and tool rows: when they ended, in epoch milliseconds."
+          },
+          "files": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimelineFile"
+            },
+            "description": "user: the message's attachments (metadata only; the bytes through …/files/{index} or …/media/{ref})."
+          },
+          "media": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimelineFile"
+            },
+            "description": "tool: its image results; assistant: local image paths in the text."
+          },
+          "pos": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The ordering position: rows sort by it. Stable while history pages or the context window move."
+          },
+          "callID": {
+            "type": "string",
+            "description": "tool: the tool call's ID (live activity items use it)."
+          },
+          "childSessionID": {
+            "type": "string",
+            "description": "A subagent tool: the session it runs in."
+          },
+          "summary": {
+            "type": "string",
+            "description": "tool: a short summary of its input."
+          },
+          "title": {
+            "type": "string",
+            "description": "A subagent tool: the task's short description."
+          },
+          "ordinal": {
+            "type": "integer",
+            "format": "int32",
+            "description": "assistant: which text part of the message this is (0, 1, …), as in live text deltas."
+          },
+          "direction": {
+            "type": "string",
+            "x-hub-known": ["in", "out"],
+            "description": "message: in (delivered to the session) or out (sent by it)."
+          },
+          "message": {
+            "$ref": "#/components/schemas/TimelineMessageMeta"
+          },
+          "errorType": {
+            "type": "string",
+            "description": "error and retry: the error's type."
+          },
+          "errorStatus": {
+            "type": "integer",
+            "format": "int32",
+            "description": "error and retry: the error's HTTP status."
+          },
+          "declined": {
+            "type": "boolean",
+            "description": "error: a denied permission stopped the turn."
+          },
+          "attempt": {
+            "type": "integer",
+            "format": "int32",
+            "description": "retry: the attempt."
+          },
+          "next": {
+            "type": "integer",
+            "format": "int64",
+            "description": "retry: when the next attempt starts, in epoch milliseconds."
+          }
+        }
+      },
+      "TimelineMessageMeta": {
+        "type": "object",
+        "description": "A message row's envelope.",
+        "required": ["kind", "from", "to"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["msg", "ask", "reply", "decline", "primer", "decision", "prompt"]
+          },
+          "from": {
+            "type": "string",
+            "description": "The sender's address, e.g. \"@api-refactor\"."
+          },
+          "to": {
+            "type": "string",
+            "description": "The address the sender wrote, e.g. \"@@reviewer\"."
+          },
+          "replyTo": {
+            "type": "string",
+            "description": "What a reply or decline answers."
+          }
+        }
+      },
+      "TimelineFile": {
+        "type": "object",
+        "description": "An image of a row.",
+        "required": ["index", "ref", "mime"],
+        "properties": {
+          "index": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Its position: in the user message's files, the tool's content, or among the text's images."
+          },
+          "ref": {
+            "type": "string",
+            "description": "Names it for …/media/{ref}: f<n>, t<part>.<item> or p:<path>."
+          },
+          "mime": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string",
+            "description": "A file name, or the image path as written."
+          },
+          "bytes": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Its size, when the machine knows it without reading the file."
+          },
+          "width": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "height": {
+            "type": "integer",
+            "format": "int32"
+          }
+        }
+      },
+      "TimelinePart": {
+        "type": "object",
+        "required": ["detail"],
+        "properties": {
+          "detail": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The harness's tool call: name, state (input, output, error, metadata) and time."
+          }
+        }
+      },
+      "SessionMessageList": {
+        "type": "object",
+        "required": ["messages"],
+        "properties": {
+          "messages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AgentMessage"
+            }
+          }
+        }
+      },
+      "AgentMessage": {
+        "type": "object",
+        "description": "A hub message between sessions, the user and apps.",
+        "required": ["id", "kind", "from", "to", "recipient", "text", "state", "at", "hop"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["msg", "ask", "reply", "decline"],
+            "description": "msg: a message; ask: a question awaiting a reply; reply and decline: the answer to an ask."
+          },
+          "from": {
+            "$ref": "#/components/schemas/Party"
+          },
+          "to": {
+            "type": "string",
+            "description": "The address as the sender wrote it, e.g. \"@@reviewer\"."
+          },
+          "recipient": {
+            "$ref": "#/components/schemas/Party"
+          },
+          "generation": {
+            "type": "integer",
+            "format": "int64",
+            "description": "A role address: the role holder generation it reached."
+          },
+          "text": {
+            "type": "string"
+          },
+          "replyTo": {
+            "type": "string",
+            "description": "What a reply or decline answers."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["sent", "open", "answered", "declined", "expired"],
+            "description": "sent for msg, reply and decline; an ask is open until answered, declined or expired."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was sent, in epoch milliseconds."
+          },
+          "hop": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Hops since a human turn (loop protection)."
+          },
+          "expiresAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "An ask: when it expires, in epoch milliseconds."
+          },
+          "notAfter": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Not delivered after this, in epoch milliseconds."
+          },
+          "delivery": {
+            "type": "string",
+            "x-hub-known": ["steer", "turn", "queued", "retained", "pending", "dropped", "expired"],
+            "description": "How it reached its recipient."
+          },
+          "expiredReason": {
+            "type": "string",
+            "x-hub-known": ["not_after", "pending_timeout"],
+            "description": "delivery expired: why."
+          },
+          "deliveredAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was first delivered, in epoch milliseconds."
+          },
+          "answer": {
+            "$ref": "#/components/schemas/MessageAnswerRef"
+          }
+        }
+      },
+      "MessageAnswerRef": {
+        "type": "object",
+        "description": "What closed an ask.",
+        "required": ["id", "at"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The reply or decline."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "In epoch milliseconds."
+          }
+        }
+      },
+      "Party": {
+        "description": "Who sends or receives a message: a session, the user (@me) or an app.",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/SessionParty"
+          },
+          {
+            "$ref": "#/components/schemas/UserParty"
+          },
+          {
+            "$ref": "#/components/schemas/AppParty"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "kind",
+          "mapping": {
+            "session": "#/components/schemas/SessionParty",
+            "user": "#/components/schemas/UserParty",
+            "app": "#/components/schemas/AppParty"
+          }
+        },
+        "x-hub-union": true
+      },
+      "SessionParty": {
+        "type": "object",
+        "required": ["kind", "sessionID"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["session"]
+          },
+          "sessionID": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string",
+            "description": "Its name in the directory, when known."
+          },
+          "harness": {
+            "type": "string"
+          },
+          "machine": {
+            "type": "string",
+            "description": "Its machine's name."
+          }
+        }
+      },
+      "UserParty": {
+        "type": "object",
+        "description": "The user (@me).",
+        "required": ["kind"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["user"]
+          }
+        }
+      },
+      "AppParty": {
+        "type": "object",
+        "required": ["kind", "tokenID"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["app"]
+          },
+          "tokenID": {
+            "type": "string",
+            "description": "The app token's ID."
+          },
+          "label": {
+            "type": "string"
+          }
+        }
+      },
+      "ReadMarks": {
+        "type": "object",
+        "required": ["reads"],
+        "properties": {
+          "reads": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "integer",
+              "format": "int64",
+              "description": "When it was read, in epoch milliseconds."
+            },
+            "description": "Session ID → when the user last read it."
+          }
+        }
+      },
+      "MarkReadRequest": {
+        "type": "object",
+        "properties": {
+          "open": {
+            "type": "boolean",
+            "description": "True when the user opened the session (navigated to it, or showed it again), not when a visible pane marks itself read: only an open counts as the user's activity."
+          }
+        }
+      },
+      "ViewPrefs": {
+        "type": "object",
+        "description": "The session list's hidden and pinned sessions and workspaces. A workspace key is herdr:<workspaceID> or a folder path.",
+        "required": ["hiddenSessions", "hiddenWorkspaces", "pinnedSessions", "pinnedWorkspaces"],
+        "properties": {
+          "hiddenSessions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Archived sessions."
+          },
+          "hiddenWorkspaces": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Hidden workspaces: herdr:<workspaceID> or a folder path."
+          },
+          "pinnedSessions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "pinnedWorkspaces": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ViewPrefsState": {
+        "type": "object",
+        "required": ["prefs"],
+        "properties": {
+          "prefs": {
+            "$ref": "#/components/schemas/ViewPrefs"
+          }
+        }
+      },
+      "ViewPrefsChange": {
+        "type": "object",
+        "description": "At least one list; each replaces the stored one. No other keys.",
+        "properties": {
+          "hiddenSessions": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096
+            },
+            "maxItems": 5000,
+            "description": "Replaces the archived sessions."
+          },
+          "hiddenWorkspaces": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096
+            },
+            "maxItems": 500
+          },
+          "pinnedSessions": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096
+            },
+            "maxItems": 500
+          },
+          "pinnedWorkspaces": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4096
+            },
+            "maxItems": 500
+          }
+        },
+        "minProperties": 1
+      }
+    }
+  }
+}