@huynle/hub 0.11.0 → 0.11.1

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

@@ -0,0 +1,679 @@
+{
+  "paths": {
+    "/api/v1/events": {
+      "get": {
+        "operationId": "streamEvents",
+        "tags": ["events"],
+        "x-hub-access": "user",
+        "summary": "The live stream: catalog, status, streamed text, speech and every other change, as server-sent events",
+        "description": "The user's live updates as server-sent events (text/event-stream, UTF-8). The body is a sequence of blocks, each ended by an empty line; a line is `field: value`. The hub writes these blocks:\n\n- `: open` (a comment), at once, before anything else, so the response head is sent without waiting. Ignore every line starting with `:`.\n- A message: an optional `id: <id>` line, then one `data: <JSON>` line holding one StreamMessage (the JSON never spans lines). Messages have no `event:` field.\n- A heartbeat: `event: ping` and `data: 0`, without an id, every 20 seconds. It is not a message: a client uses it only to tell a live stream from a dead one (the console reopens a stream that brought nothing for 45 seconds).\n- `retry: 2000` (milliseconds), when the hub is draining before a shutdown: the stream then ends, and the client reconnects after that delay (to another instance) with its last id. A stream opened while the hub drains gets only this block.\n\nIds are opaque strings (today `<epoch>.<n>`, with a new epoch at every hub start; never parse them). Keep the id of the last message that had one. To resume, send it as the Last-Event-ID header (or the `last` query parameter): if the hub still holds every message after it (the last 2000, at most 5 minutes old), it replays them in order, each with its id, then a fresh catalog if the catalog changed meanwhile, and goes on live; nothing else is sent first, so a resume with nothing missed sends only `: open` until the next message. Otherwise it starts over: a catalog, then a `resync` message, after which the client must refetch everything it shows (sessions, timelines, Decisions). A stream that does not resume starts with the catalog. The catalog that starts a stream carries the id of the user's latest message; in a hub cluster a resumed stream's catalog has none.\n\nThe order of a stream: `: open`; `scope` when the request has `sessions`; the catalog (and `resync`), or the replay; then live messages as they happen, and heartbeats.\n\nWhat a stream carries: every message for the user's own sessions and account; `prefs` and `reads` changes only from the user's other devices; `enrollment` only for admins. With lite=1, `delta` and `reasoning` messages are left out except those of the trees of the sessions in `session` and `sessions` (also when replayed). Sessions the user does not own are dropped from `session` and `sessions` silently.",
+        "parameters": [
+          {
+            "name": "lite",
+            "in": "query",
+            "required": false,
+            "description": "1: leave out streamed text and reasoning (`delta`, `reasoning`) except of the trees of the shown sessions (`session`, `sessions`). Any other value is ignored.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "session",
+            "in": "query",
+            "required": false,
+            "description": "The session the client shows (at most 300 characters).",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sessions",
+            "in": "query",
+            "required": false,
+            "description": "Every session the client shows, comma-separated (the parameter may also repeat), at most 4 with `session`, each at most 300 characters. Its presence also makes the stream start with a `scope` message.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "last",
+            "in": "query",
+            "required": false,
+            "description": "The id of the last message received, to resume after it, for clients that cannot set Last-Event-ID. The header wins when both are sent.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "Last-Event-ID",
+            "in": "header",
+            "required": false,
+            "description": "The id of the last message received, to resume after it.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The stream: open until the client closes it or the hub drains. Fails before it starts with 400 invalid for a session ID over 300 characters or more than 4 sessions.",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "$ref": "#/components/schemas/StreamMessage"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "StreamMessage": {
+        "description": "A message of the live stream (GET /api/v1/events), told apart by `type`. A client skips a type it does not know: a newer hub may send more.",
+        "x-hub-union": true,
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/CatalogStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/StatusStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/DeltaStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ReasoningStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ActivityStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ConversationStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/SayStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/HeardStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/TurnStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/DecisionStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/MessageStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/PrefsStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ReadsStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/HandoffStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/EnrollmentStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/IntentStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ContextCardStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/LaunchStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/AgentStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ConciergeStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/RecordingStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ScopeStreamMessage"
+          },
+          {
+            "$ref": "#/components/schemas/ResyncStreamMessage"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "catalog": "#/components/schemas/CatalogStreamMessage",
+            "status": "#/components/schemas/StatusStreamMessage",
+            "delta": "#/components/schemas/DeltaStreamMessage",
+            "reasoning": "#/components/schemas/ReasoningStreamMessage",
+            "activity": "#/components/schemas/ActivityStreamMessage",
+            "conversation": "#/components/schemas/ConversationStreamMessage",
+            "say": "#/components/schemas/SayStreamMessage",
+            "heard": "#/components/schemas/HeardStreamMessage",
+            "turn": "#/components/schemas/TurnStreamMessage",
+            "decision": "#/components/schemas/DecisionStreamMessage",
+            "message": "#/components/schemas/MessageStreamMessage",
+            "prefs": "#/components/schemas/PrefsStreamMessage",
+            "reads": "#/components/schemas/ReadsStreamMessage",
+            "handoff": "#/components/schemas/HandoffStreamMessage",
+            "enrollment": "#/components/schemas/EnrollmentStreamMessage",
+            "intent": "#/components/schemas/IntentStreamMessage",
+            "contextCard": "#/components/schemas/ContextCardStreamMessage",
+            "launch": "#/components/schemas/LaunchStreamMessage",
+            "agent": "#/components/schemas/AgentStreamMessage",
+            "concierge": "#/components/schemas/ConciergeStreamMessage",
+            "recording": "#/components/schemas/RecordingStreamMessage",
+            "scope": "#/components/schemas/ScopeStreamMessage",
+            "resync": "#/components/schemas/ResyncStreamMessage"
+          }
+        }
+      },
+      "ActivityStreamMessage": {
+        "type": "object",
+        "description": "One of two forms. A tool call or stretch of reasoning was created or changed state: `rootID` and `item` (the session's activity feed, as in GET /api/v1/sessions/{session}). Or the user's own activity on a session changed (what they last did there, for the session list): `activity`, without `rootID` and `item`.",
+        "required": ["type", "sessionID"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["activity"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "Where it happened: with `item`, the root or the subagent session; with `activity`, the session the user acted on."
+          },
+          "rootID": {
+            "type": "string",
+            "description": "With `item`: the root session of `sessionID`."
+          },
+          "item": {
+            "$ref": "#/components/schemas/ActivityItem"
+          },
+          "activity": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The user's activity entry for the session (at, kind, last, buckets), as GET /api/v1/activity/mine lists it. That area is not specified yet: until it is, any JSON."
+          }
+        }
+      },
+      "AgentStreamMessage": {
+        "type": "object",
+        "description": "An entry was added to the user's agent audit (an agent acted, or the user answered for one).",
+        "required": ["type", "entry"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["agent"]
+          },
+          "entry": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The audit entry. The agent audit area is not specified yet: until it is, any JSON."
+          }
+        }
+      },
+      "CatalogStreamMessage": {
+        "type": "object",
+        "description": "The user's machines, processes and sessions: the same list as GET /api/v1/machines, sent whole. The first message of every stream that does not resume (and the last of a resumed one whose missed messages included a catalog change), then again whenever the catalog changes: a machine or process connects, goes away or reports its sessions; a session's title, conversation mode or voice front changes.",
+        "required": ["type", "machines"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["catalog"]
+          },
+          "machines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CatalogMachine"
+            }
+          }
+        }
+      },
+      "ConciergeStreamMessage": {
+        "type": "object",
+        "description": "The user's Concierge changed. One of two forms: `status` (its state changed) or `armed` (the Decision it armed, or null when disarmed). Tell `armed: null` from a message without `armed` by the key: a generated model reads both as null.",
+        "required": ["type"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["concierge"]
+          },
+          "status": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The Concierge's status. The Concierge area is not specified yet: until it is, any JSON."
+          },
+          "armed": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The armed Decision ({decisionID, at, expiresAt}) or null. The Concierge area is not specified yet: until it is, any JSON."
+          }
+        }
+      },
+      "ContextCardStreamMessage": {
+        "type": "object",
+        "description": "A context card of a session was made: refetch the session's cards.",
+        "required": ["type", "sessionID", "provider", "generatedAt"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["contextCard"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it is about."
+          },
+          "provider": {
+            "type": "string",
+            "description": "The card's provider."
+          },
+          "primary": {
+            "type": "boolean",
+            "description": "Present (true) when it is the session's primary card."
+          },
+          "generatedAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was made, in epoch milliseconds."
+          }
+        }
+      },
+      "ConversationStreamMessage": {
+        "type": "object",
+        "description": "A session's conversation (Voice) mode changed. A catalog follows with the same state.",
+        "required": ["type", "sessionID", "on"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["conversation"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it is about."
+          },
+          "on": {
+            "type": "boolean",
+            "description": "Whether conversation mode is on."
+          },
+          "front": {
+            "type": "boolean",
+            "description": "Present once a voice front was asked for: whether a front session is in front of this one now."
+          },
+          "reason": {
+            "type": "string",
+            "x-hub-known": ["front_failed"],
+            "description": "front_failed: the voice front could not be made; utterances go to the session itself."
+          }
+        }
+      },
+      "DecisionStreamMessage": {
+        "type": "object",
+        "description": "A Decision of the user was opened, answered, escalated or expired: the Decision as it is now.",
+        "required": ["type", "decision"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["decision"]
+          },
+          "decision": {
+            "$ref": "#/components/schemas/Decision"
+          }
+        }
+      },
+      "DeltaStreamMessage": {
+        "type": "object",
+        "description": "Assistant text streamed in a root or subagent session, at most one message per session per 100 ms (later text within that window is joined). Append `text` to the text part (`messageID`, `ordinal`). Left out of a lite stream unless the session is in the tree of a shown session.",
+        "required": ["type", "sessionID", "rootID", "text"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["delta"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session the text is written in."
+          },
+          "rootID": {
+            "type": "string",
+            "description": "The root session of `sessionID`'s tree (the same ID for a root session)."
+          },
+          "messageID": {
+            "type": "string",
+            "description": "The assistant message, when the harness reports it."
+          },
+          "ordinal": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The text part of the message (0-based), when known."
+          },
+          "text": {
+            "type": "string",
+            "description": "The new text."
+          }
+        }
+      },
+      "EnrollmentStreamMessage": {
+        "type": "object",
+        "description": "Machine enrollment requests changed: refetch them. Admins only; no fields.",
+        "required": ["type"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["enrollment"]
+          }
+        }
+      },
+      "HandoffStreamMessage": {
+        "type": "object",
+        "description": "A harness asked to hand the session over to the user's devices (open it here).",
+        "required": ["type", "sessionID"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["handoff"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it is about."
+          }
+        }
+      },
+      "HeardStreamMessage": {
+        "type": "object",
+        "description": "An utterance sent with POST /api/v1/sessions/{session}/utterance reached the agent.",
+        "required": ["type", "sessionID", "inboxID"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["heard"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it is about."
+          },
+          "inboxID": {
+            "type": "string",
+            "description": "The utterance's inbox ID, as its answer gave it."
+          }
+        }
+      },
+      "IntentStreamMessage": {
+        "type": "object",
+        "description": "A session's intent changed: refetch it (the text never rides the stream).",
+        "required": ["type", "sessionID", "source", "revision"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["intent"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it is about."
+          },
+          "source": {
+            "type": "string",
+            "x-hub-known": ["user", "launch", "self", "prompt", "title"],
+            "description": "Who set the intent now in place."
+          },
+          "revision": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The intent's revision."
+          }
+        }
+      },
+      "LaunchStreamMessage": {
+        "type": "object",
+        "description": "One of the user's launches changed.",
+        "required": ["type", "launch"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["launch"]
+          },
+          "launch": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The launch as the launches area answers it. That area is not specified yet: until it is, any JSON."
+          }
+        }
+      },
+      "MessageStreamMessage": {
+        "type": "object",
+        "description": "A message to or from one of the user's sessions was stored (agent messaging).",
+        "required": ["type", "message"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["message"]
+          },
+          "message": {
+            "$ref": "#/components/schemas/AgentMessage"
+          }
+        }
+      },
+      "PrefsStreamMessage": {
+        "type": "object",
+        "description": "The user's view preferences changed on another of their devices (never sent to the device that made the change).",
+        "required": ["type", "prefs"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["prefs"]
+          },
+          "prefs": {
+            "$ref": "#/components/schemas/ViewPrefs"
+          }
+        }
+      },
+      "ReadsStreamMessage": {
+        "type": "object",
+        "description": "The user's read marks changed on another of their devices (never sent to the device that made the change): all of them, as GET /api/v1/reads answers.",
+        "required": ["type", "reads"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["reads"]
+          },
+          "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."
+          }
+        }
+      },
+      "ReasoningStreamMessage": {
+        "type": "object",
+        "description": "Reasoning text streamed in a root or subagent session, throttled and filtered like `delta`.",
+        "required": ["type", "sessionID", "rootID", "delta"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["reasoning"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session the reasoning happens in."
+          },
+          "rootID": {
+            "type": "string",
+            "description": "The root session of `sessionID`'s tree (the same ID for a root session)."
+          },
+          "messageID": {
+            "type": "string",
+            "description": "The assistant message, when the harness reports it."
+          },
+          "delta": {
+            "type": "string",
+            "description": "The new reasoning text."
+          }
+        }
+      },
+      "RecordingStreamMessage": {
+        "type": "object",
+        "description": "The user's voice recordings changed. One of these forms: `settings` (the recording setting changed on another device); `recordingID` with `developer: false` (Developer mode was turned off for a running recording), with `state` ended and a `reason`, with `state` deleted, or with `audio: false` (its audio stopped at a cap).",
+        "required": ["type"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["recording"]
+          },
+          "settings": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The recording settings. The recordings area is not specified yet: until it is, any JSON."
+          },
+          "recordingID": {
+            "type": "string",
+            "description": "The recording it is about."
+          },
+          "developer": {
+            "type": "boolean",
+            "description": "false: the recording goes on without its Developer mode extras."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["ended", "deleted"],
+            "description": "The recording ended or was deleted."
+          },
+          "reason": {
+            "type": "string",
+            "x-hub-known": [
+              "stopped",
+              "conversation_off",
+              "disabled",
+              "max_duration",
+              "stale",
+              "limit",
+              "superseded",
+              "session_deleted"
+            ],
+            "description": "With state ended: why."
+          },
+          "audio": {
+            "type": "boolean",
+            "description": "false: the recording goes on without audio (a cap was reached)."
+          }
+        }
+      },
+      "ResyncStreamMessage": {
+        "type": "object",
+        "description": "Sent after the catalog when a stream asked to resume (Last-Event-ID or `last`) and the hub could not replay what was missed (a hub restart, an unknown ID, or more than the hub keeps): the client must refetch everything it shows. No fields.",
+        "required": ["type"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["resync"]
+          }
+        }
+      },
+      "SayStreamMessage": {
+        "type": "object",
+        "description": "Text to speak, of a root session in conversation mode: while the reply streams, one message per completed sentence (with `seq`); a subagent's final result as one message for the whole text part (without `seq`).",
+        "required": ["type", "sessionID", "messageID", "ordinal", "text"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["say"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The root session that speaks."
+          },
+          "messageID": {
+            "type": "string",
+            "description": "The assistant message the text belongs to."
+          },
+          "ordinal": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The text part of the message (0-based)."
+          },
+          "seq": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The sentence's number within the text part, from 0. Absent for a whole text part."
+          },
+          "text": {
+            "type": "string",
+            "description": "What to say."
+          }
+        }
+      },
+      "ScopeStreamMessage": {
+        "type": "object",
+        "description": "The sessions this stream streams the text of, after leaving out those the user does not own: sent first, and only when the request has `sessions` (a console with several panes). Tells a client the hub honours `sessions`.",
+        "required": ["type", "sessions"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["scope"]
+          },
+          "sessions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The session IDs, `session` first."
+          }
+        }
+      },
+      "StatusStreamMessage": {
+        "type": "object",
+        "description": "A root session's status tree changed (states, blockers, retries, jobs): the whole tree, the root first. It replaces the `status` of every catalog session with this ID.",
+        "required": ["type", "sessionID", "sessions"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["status"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The root session."
+          },
+          "sessions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SessionStatus"
+            },
+            "description": "The root's own status, then one per subagent session below it."
+          }
+        }
+      },
+      "TurnStreamMessage": {
+        "type": "object",
+        "description": "The result of a turn that POST /api/v1/sessions/{session}/turn accepted with Prefer: respond-async (202). The fields after `sessionID` are a TurnResult; a turn the hub stopped waiting for is outcome timeout, any other failure outcome failed with a message.",
+        "required": ["type", "sessionID", "outcome", "reply"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["turn"]
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session it is about."
+          },
+          "outcome": {
+            "type": "string",
+            "x-hub-known": ["succeeded", "failed", "interrupted", "timeout"],
+            "description": "As in TurnResult."
+          },
+          "reply": {
+            "type": "string",
+            "description": "The turn's reply text, possibly partial or empty."
+          },
+          "message": {
+            "type": "string",
+            "description": "Why it failed or was interrupted."
+          }
+        }
+      }
+    }
+  }
+}