@huynle/hub 0.8.7 → 0.9.1

package/packages/protocol/schema/app-delivery/v1.schema.json

@@ -0,0 +1,677 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/huynle/hub/packages/protocol/schema/app-delivery/v1.schema.json",
+  "title": "Hub app delivery surface",
+  "description": "The app-facing delivery surface of a hub (msg/ask, launches, team intake, webhooks, error bodies), frozen by docs/plans/2026-11-06-app-delivery-contracts.md. Every definition lives in $defs; validate a body against `<$id>#/$defs/<Name>`. Fields marked `(H1)`-`(H6)` in a description were added by those tasks (H1-H5 shipped; H6 not started); they are optional, so bodies of older hubs validate. REST views are open (clients ignore unknown fields); event payloads (`*EventData`, `*Subject`) are closed allowlists: a new field there needs a schema change in the same commit. `schemaVersion` is an annotation keyword (Ajv strict mode: ajv.addVocabulary(['schemaVersion'])).",
+  "schemaVersion": 1,
+  "$defs": {
+    "SchemaVersion": { "description": "The version of this schema document; additive changes keep 1.", "const": 1 },
+
+    "EpochMs": { "description": "Milliseconds since the Unix epoch.", "type": "integer", "minimum": 0 },
+    "NotAfter": {
+      "description": "A hard deadline (msg/ask H2, team intake H4 and launches H3, all through parseNotAfter in src/central/agent/not-after.ts), epoch milliseconds (REST and SDK; the CLI and MCP also accept an ISO 8601 date-time and convert it). Must be in the future and at most 30 days (NotAfterLimitMs) out: a value already passed is 422 `expired` (nothing stored or delivered); one further out, or not an integer, is 400 `invalid`. It takes part in idempotency body comparison like any other field.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "NotAfterLimitMs": { "description": "The furthest notAfter accepted, relative to the hub's clock: 30 days (NOT_AFTER_MAX_MS).", "const": 2592000000 },
+    "ExpiredReason": {
+      "description": "Why a delivery expired (ExpiredReason in src/central/agent/not-after.ts): `not_after` (its notAfter passed), `pending_timeout` (the 24 h hold for an offline or busy session, PENDING_MS in src/central/agent/delivery.ts). On a message as `expiredReason`, on message.changed as `reason` (an enum, never text).",
+      "enum": ["not_after", "pending_timeout"]
+    },
+
+    "IdempotencyKey": {
+      "description": "The `Idempotency-Key` request header (IDEMPOTENCY_KEY in packages/protocol/src/contracts.ts). Same key + same body within IdempotencyTtlMs replays the first answer with 200 and header `idempotent-replayed: true`; another body under a live key is 409 `conflict`. On team intake, workspace/profile creates and (H1, shipped) POST /api/agent/msg and /ask, keyed per sender.",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.:-]{1,200}$"
+    },
+    "IdempotencyTtlMs": { "description": "How long a used Idempotency-Key replays (IDEMPOTENCY_TTL_MS: 24 h).", "const": 86400000 },
+    "ReplayedHeader": { "description": "Value of the response header `idempotent-replayed` on an idempotent replay.", "const": "true" },
+
+    "ErrorCode": {
+      "description": "The /api/agent error codes (AGENT_ERROR_STATUS in src/central/agent/errors.ts; `expired` shipped with H2).",
+      "enum": ["invalid", "invalid_cursor", "unauthorized", "token_expired", "needs_user", "forbidden", "not_found", "ambiguous", "name_taken", "conflict", "gone", "unsupported", "expired", "paused", "rate_limited", "internal", "offline", "busy"]
+    },
+    "ErrorCodeStatus": {
+      "description": "The HTTP status of each error code (AGENT_ERROR_STATUS). `expired` is 422 like `unsupported`.",
+      "const": {
+        "invalid": 400,
+        "invalid_cursor": 400,
+        "unauthorized": 401,
+        "token_expired": 401,
+        "needs_user": 403,
+        "forbidden": 403,
+        "not_found": 404,
+        "ambiguous": 409,
+        "name_taken": 409,
+        "conflict": 409,
+        "gone": 410,
+        "unsupported": 422,
+        "expired": 422,
+        "paused": 423,
+        "rate_limited": 429,
+        "internal": 500,
+        "offline": 503,
+        "busy": 503
+      }
+    },
+    "ErrorBody": {
+      "description": "Every /api/agent error: {error: {code, message, hint?, ...extra}} (src/central/agent/errors.ts agentError). `retryAfter` (seconds) is also sent as the Retry-After header. 409 conflict may carry `currentRevision`; 409 ambiguous `candidates`; 422 unsupported `feature`; 422 expired: a notAfter had already passed at submit (nothing stored, delivered or pushed).",
+      "type": "object",
+      "required": ["error"],
+      "properties": {
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": { "$ref": "#/$defs/ErrorCode" },
+            "message": { "type": "string" },
+            "hint": { "type": "string" },
+            "retryAfter": { "type": "number", "minimum": 0 },
+            "currentRevision": { "type": "integer", "minimum": 0 },
+            "candidates": { "type": "array" },
+            "feature": { "type": "string" },
+            "notAfter": { "$ref": "#/$defs/EpochMs" }
+          }
+        }
+      }
+    },
+
+    "Party": {
+      "description": "A message sender or recipient (Party in packages/sdk/src/types.ts).",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind", "sessionID"],
+          "properties": { "kind": { "const": "session" }, "sessionID": { "type": "string" }, "name": { "type": "string" }, "harness": { "type": "string" }, "machine": { "type": "string" } }
+        },
+        { "type": "object", "required": ["kind"], "properties": { "kind": { "const": "user" } } },
+        {
+          "type": "object",
+          "required": ["kind", "tokenID"],
+          "properties": { "kind": { "const": "app" }, "tokenID": { "type": "string" }, "label": { "type": "string" } }
+        }
+      ]
+    },
+    "MessageKind": { "enum": ["msg", "ask", "reply", "decline"] },
+    "MessageState": { "description": "`sent` for msg/reply/decline; asks are open until answered, declined or expired.", "enum": ["sent", "open", "answered", "declined", "expired"] },
+    "MessageDelivery": {
+      "description": "How a message reached its recipient session (Delivery in src/central/agent/messages.ts). `expired`: pending past PENDING_MS or (H2) past its notAfter; never delivered (see expiredReason).",
+      "enum": ["steer", "turn", "queued", "retained", "pending", "dropped", "expired"]
+    },
+    "WakeSkip": { "enum": ["wake_false", "subagent", "hop_cap", "budget"] },
+    "Message": {
+      "type": "object",
+      "required": ["id", "kind", "from", "to", "recipient", "text", "state", "at", "hop"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^msg_[A-Za-z0-9]{22}$" },
+        "kind": { "$ref": "#/$defs/MessageKind" },
+        "from": { "$ref": "#/$defs/Party" },
+        "to": { "type": "string" },
+        "recipient": { "$ref": "#/$defs/Party" },
+        "generation": { "type": "integer", "minimum": 0 },
+        "text": { "type": "string" },
+        "replyTo": { "type": "string" },
+        "state": { "$ref": "#/$defs/MessageState" },
+        "at": { "$ref": "#/$defs/EpochMs" },
+        "hop": { "type": "integer", "minimum": 0 },
+        "expiresAt": { "$ref": "#/$defs/EpochMs" },
+        "notAfter": { "description": "(H2) Not delivered after this; an ask's expiresAt is at most notAfter.", "$ref": "#/$defs/EpochMs" },
+        "delivery": { "$ref": "#/$defs/MessageDelivery" },
+        "expiredReason": { "description": "(H2) delivery expired only: which deadline passed.", "$ref": "#/$defs/ExpiredReason" },
+        "deliveredAt": { "$ref": "#/$defs/EpochMs" },
+        "answer": { "type": "object", "required": ["id", "at"], "properties": { "id": { "type": "string" }, "at": { "$ref": "#/$defs/EpochMs" } } }
+      }
+    },
+    "MsgRequest": {
+      "description": "POST /api/agent/msg (scope messages:send). Optional header Idempotency-Key (H1, per sender). The sender is the credential; the hub ignores any other field (listed here as not allowed so clients send only these).",
+      "type": "object",
+      "required": ["to", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "to": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1, "maxLength": 10000 },
+        "wake": { "type": "boolean" },
+        "urgent": { "type": "boolean" },
+        "all": { "type": "boolean" },
+        "notAfter": { "$ref": "#/$defs/NotAfter" }
+      }
+    },
+    "AskRequest": {
+      "description": "POST /api/agent/ask (scope messages:send). Optional header Idempotency-Key (H1, per sender). expiresIn and wait are seconds (wait at most 60, never with all). The Decision fields (options … about) are for asks to @me only.",
+      "type": "object",
+      "required": ["to", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "to": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1, "maxLength": 10000 },
+        "wake": { "type": "boolean" },
+        "urgent": { "type": "boolean" },
+        "all": { "type": "boolean" },
+        "expiresIn": { "type": "number", "minimum": 0 },
+        "wait": { "type": "number", "minimum": 0, "maximum": 60 },
+        "notAfter": { "$ref": "#/$defs/NotAfter" },
+        "options": {
+          "type": "array",
+          "items": { "type": "object", "required": ["id", "label"], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "safe": { "type": "boolean" } } }
+        },
+        "recommendation": { "type": "object", "required": ["option"], "properties": { "option": { "type": "string" }, "why": { "type": "string" } } },
+        "urgency": { "$ref": "#/$defs/DecisionUrgency" },
+        "tier": { "$ref": "#/$defs/DecisionTier" },
+        "deadline": { "type": "number", "minimum": 0 },
+        "onTimeout": { "type": "string" },
+        "about": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "Sent": {
+      "description": "One stored message and how it was delivered (absent: stored only, e.g. to @me).",
+      "type": "object",
+      "required": ["message"],
+      "properties": {
+        "message": { "$ref": "#/$defs/Message" },
+        "delivery": { "$ref": "#/$defs/MessageDelivery" },
+        "woke": { "type": "boolean" },
+        "wakeSkipped": { "$ref": "#/$defs/WakeSkip" }
+      }
+    },
+    "SentAll": {
+      "description": "`all: true`: one Sent per session the address names. (H1) An idempotent replay returns the same list.",
+      "type": "object",
+      "required": ["sent"],
+      "properties": { "sent": { "type": "array", "items": { "$ref": "#/$defs/Sent" } } }
+    },
+    "MsgResponse": {
+      "description": "POST /api/agent/msg: 201 (200 on an H1 replay).",
+      "oneOf": [{ "$ref": "#/$defs/SentAll" }, { "allOf": [{ "$ref": "#/$defs/Sent" }, { "properties": { "sent": false } }] }]
+    },
+    "Asked": {
+      "description": "An ask after any wait: the message, its answer once closed, and (ask @me) the Decision it opened.",
+      "allOf": [
+        { "$ref": "#/$defs/Sent" },
+        { "type": "object", "properties": { "answer": { "$ref": "#/$defs/Message" }, "decision": { "$ref": "#/$defs/Decision" } } }
+      ]
+    },
+    "AskResponse": {
+      "description": "POST /api/agent/ask: 201 (200 on an H1 replay: the first answer as it was, not the ask's current state; read GET /api/agent/messages/:id for that).",
+      "oneOf": [{ "$ref": "#/$defs/SentAll" }, { "allOf": [{ "$ref": "#/$defs/Asked" }, { "properties": { "sent": false } }] }]
+    },
+    "DecisionState": { "enum": ["open", "answered", "expired", "closed"] },
+    "DecisionUrgency": { "enum": ["low", "normal", "high"] },
+    "DecisionTier": { "enum": ["confirm", "tap"] },
+    "Decision": {
+      "description": "An ask to @me (Decision in src/central/agent/decisions.ts). Answered only by the user on the console.",
+      "type": "object",
+      "required": ["id", "messageID", "from", "about", "question", "options", "urgency", "tier", "state", "at", "expiresAt"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^dec_[A-Za-z0-9]{22}$" },
+        "messageID": { "type": "string" },
+        "from": { "$ref": "#/$defs/Party" },
+        "about": { "type": "array", "items": { "type": "string" } },
+        "sessionID": { "type": "string" },
+        "question": { "type": "string" },
+        "options": {
+          "type": "array",
+          "items": { "type": "object", "required": ["id", "label"], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "safe": { "const": true } } }
+        },
+        "recommendation": { "type": "object", "required": ["option"], "properties": { "option": { "type": "string" }, "why": { "type": "string" } } },
+        "urgency": { "$ref": "#/$defs/DecisionUrgency" },
+        "tier": { "$ref": "#/$defs/DecisionTier" },
+        "deadline": { "$ref": "#/$defs/EpochMs" },
+        "onTimeout": { "type": "string" },
+        "state": { "$ref": "#/$defs/DecisionState" },
+        "at": { "$ref": "#/$defs/EpochMs" },
+        "expiresAt": { "$ref": "#/$defs/EpochMs" },
+        "escalatedAt": { "$ref": "#/$defs/EpochMs" },
+        "answer": {
+          "type": "object",
+          "required": ["answeredBy", "at"],
+          "properties": { "option": { "type": "string" }, "text": { "type": "string" }, "answeredBy": { "enum": ["user", "timeout"] }, "at": { "$ref": "#/$defs/EpochMs" } }
+        },
+        "closed": { "type": "object", "required": ["at", "reason"], "properties": { "at": { "$ref": "#/$defs/EpochMs" }, "reason": { "type": "string" } } }
+      }
+    },
+
+    "LaunchState": { "enum": ["queued", "placing", "provisioning", "running", "ended"] },
+    "LaunchOutcome": {
+      "description": "How an ended launch ended (LAUNCH_OUTCOMES). `expired` (H3): its notAfter passed while it was still queued or placing; it never started.",
+      "enum": ["idle", "needs_user", "failed", "timeout", "stopped", "lost", "expired"]
+    },
+    "LaunchWait": { "enum": ["capacity", "no_match", "active"] },
+    "LaunchSpecRequest": {
+      "description": "POST /api/agent/launches (scope sessions:launch, plus a launch grant on the repo for apps and sessions). Unknown fields are 400 invalid. Idempotency is the body field `key` (not the header): same key + equivalent body → 200 with the same launch; another body → 400 invalid.",
+      "type": "object",
+      "required": ["workspace"],
+      "additionalProperties": false,
+      "properties": {
+        "key": { "type": "string", "pattern": "^[!-~]{1,200}$" },
+        "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,39}$" },
+        "roles": { "type": "array", "maxItems": 10, "items": { "type": "string" } },
+        "harness": { "type": "string" },
+        "agent": { "type": "string" },
+        "model": { "type": "string", "maxLength": 200 },
+        "workspace": {
+          "type": "object",
+          "required": ["repo"],
+          "additionalProperties": false,
+          "properties": {
+            "repo": { "type": "string", "pattern": "^/" },
+            "mode": { "enum": ["worktree", "checkout", "clone"] },
+            "branch": { "type": "string", "maxLength": 200 },
+            "base": { "type": "string", "maxLength": 200 },
+            "remote": { "type": "string", "maxLength": 500 }
+          }
+        },
+        "runtime": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": ["host", "openshell"] }, "profile": { "type": "string" } } },
+        "placement": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "machine": { "type": "string" }, "mode": { "enum": ["require", "prefer"] } }
+        },
+        "prompt": { "type": "string", "maxLength": 10000 },
+        "intent": { "type": "string" },
+        "labels": { "type": "object", "maxProperties": 32, "additionalProperties": { "type": "string", "maxLength": 256 } },
+        "end": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "when": { "enum": ["idle", "asked", "never"] }, "timeout": { "type": ["string", "number"] }, "cleanup": { "enum": ["keep", "remove"] } }
+        },
+        "agentProfile": {
+          "type": "object",
+          "required": ["profileID", "version"],
+          "additionalProperties": false,
+          "properties": { "profileID": { "type": "string" }, "version": { "type": "integer", "minimum": 1 } }
+        },
+        "notAfter": { "description": "(H3) Start-by deadline: applies while queued or placing only. Already passed on a new launch: 422 expired before the grant check; a key replay is answered even after it.", "$ref": "#/$defs/NotAfter" }
+      }
+    },
+    "LaunchSpecView": {
+      "description": "The validated spec as the API shows it (defaults filled in; end.timeout as a duration).",
+      "type": "object",
+      "required": ["roles", "harness", "workspace", "runtime", "placement", "labels", "end"],
+      "properties": {
+        "key": { "type": "string" },
+        "name": { "type": "string" },
+        "roles": { "type": "array", "items": { "type": "string" } },
+        "harness": { "type": "string" },
+        "agent": { "type": "string" },
+        "model": { "type": "string" },
+        "workspace": {
+          "type": "object",
+          "required": ["repo", "mode"],
+          "properties": { "repo": { "type": "string" }, "mode": { "enum": ["worktree", "checkout", "clone"] }, "branch": { "type": "string" }, "base": { "type": "string" }, "remote": { "type": "string" } }
+        },
+        "runtime": { "type": "object", "required": ["kind"], "properties": { "kind": { "enum": ["host", "openshell"] }, "profile": { "type": "string" } } },
+        "placement": {
+          "type": "object",
+          "required": ["labels", "mode"],
+          "properties": { "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "machine": { "type": "string" }, "mode": { "enum": ["require", "prefer"] } }
+        },
+        "prompt": { "type": "string" },
+        "intent": { "type": "string" },
+        "labels": { "type": "object", "additionalProperties": { "type": "string" } },
+        "end": {
+          "type": "object",
+          "required": ["when", "cleanup"],
+          "properties": { "when": { "enum": ["idle", "asked", "never"] }, "timeout": { "type": "string" }, "cleanup": { "enum": ["keep", "remove"] } }
+        },
+        "agentProfile": { "type": "object", "required": ["profileID", "version"], "properties": { "profileID": { "type": "string" }, "version": { "type": "integer" } } },
+        "notAfter": { "description": "(H3) As submitted.", "$ref": "#/$defs/EpochMs" }
+      }
+    },
+    "LaunchStep": {
+      "type": "object",
+      "required": ["state", "reason", "at"],
+      "properties": { "state": { "$ref": "#/$defs/LaunchState" }, "reason": { "type": "string" }, "at": { "$ref": "#/$defs/EpochMs" }, "outcome": { "$ref": "#/$defs/LaunchOutcome" } }
+    },
+    "Launch": {
+      "description": "A launch as the API shows it (launchInfo in src/central/agent/launch-routes.ts). An ended launch carries its outcome; no other state does.",
+      "type": "object",
+      "required": ["id", "state", "reason", "spec", "created", "updated", "history"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^l_[0-9a-f]{16}$" },
+        "state": { "$ref": "#/$defs/LaunchState" },
+        "reason": { "type": "string" },
+        "spec": { "$ref": "#/$defs/LaunchSpecView" },
+        "created": { "$ref": "#/$defs/EpochMs" },
+        "updated": { "$ref": "#/$defs/EpochMs" },
+        "by": { "type": "string" },
+        "byLabel": { "type": "string" },
+        "launcherRevoked": { "const": true },
+        "waiting": {
+          "type": "object",
+          "required": ["wait", "reason", "since"],
+          "properties": { "wait": { "$ref": "#/$defs/LaunchWait" }, "reason": { "type": "string" }, "since": { "$ref": "#/$defs/EpochMs" } }
+        },
+        "machineID": { "type": "string" },
+        "directory": { "type": "string" },
+        "sessionID": { "type": "string" },
+        "name": { "type": "string" },
+        "outcome": { "$ref": "#/$defs/LaunchOutcome" },
+        "artifacts": { "type": "object" },
+        "history": { "type": "array", "items": { "$ref": "#/$defs/LaunchStep" } }
+      },
+      "if": { "properties": { "state": { "const": "ended" } } },
+      "then": { "required": ["outcome"], "properties": { "outcome": { "$ref": "#/$defs/LaunchOutcome" } } },
+      "else": { "properties": { "outcome": false } }
+    },
+    "LaunchResponse": {
+      "description": "POST /api/agent/launches (201, or 200 for an idempotent repeat), GET /:id, DELETE /:id.",
+      "type": "object",
+      "required": ["launch"],
+      "properties": { "launch": { "$ref": "#/$defs/Launch" } }
+    },
+    "LaunchListResponse": { "type": "object", "required": ["launches"], "properties": { "launches": { "type": "array", "items": { "$ref": "#/$defs/Launch" } } } },
+
+    "IntakePriority": { "enum": ["low", "normal", "high", "urgent"] },
+    "IntakeStatus": { "description": "Unchanged by H4: an expired queued item is `cancelled` with reason `not_after` (NOT_AFTER_REASON in src/central/teams/intake.ts).", "enum": ["queued", "routed", "done", "cancelled", "failed"] },
+    "IntakeProgress": { "enum": ["open", "in_progress", "blocked"] },
+    "IntakeStatusInput": { "enum": ["open", "in_progress", "blocked", "done", "failed", "cancelled"] },
+    "IntakeExpiryReason": { "description": "(H4) The exact `reason` (item) and `reasonCode` (team.intake event) of an intake the hub cancelled because its notAfter passed while queued (NOT_AFTER_REASON).", "const": "not_after" },
+    "IntakeSource": {
+      "oneOf": [
+        { "type": "object", "required": ["kind"], "properties": { "kind": { "const": "user" } } },
+        { "type": "object", "required": ["kind", "tokenID"], "properties": { "kind": { "const": "app" }, "tokenID": { "type": "string" } } },
+        { "type": "object", "required": ["kind", "sessionID"], "properties": { "kind": { "const": "session" }, "sessionID": { "type": "string" } } }
+      ]
+    },
+    "IntakeSubmitRequest": {
+      "description": "POST /api/agent/teams/:id/intake (scope teams:submit). Optional header Idempotency-Key (keyed per submitter and team; same body → 200 replay, other body → 409 conflict). Unknown fields are 400 invalid.",
+      "type": "object",
+      "required": ["title"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "brief": { "type": "string", "maxLength": 16000 },
+        "priority": { "$ref": "#/$defs/IntakePriority" },
+        "labels": { "type": "array", "maxItems": 32, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z0-9-]{2,40}$" } },
+        "due": { "description": "Informational due time for the worker, epoch ms (never enforced, unlike notAfter).", "type": "integer", "minimum": 1 },
+        "criteria": { "type": "array", "maxItems": 8, "items": { "type": "string", "minLength": 1, "maxLength": 200 } },
+        "ref": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "notAfter": { "description": "(H4) Route-by deadline: a still-queued item is cancelled (reason not_after) once it passes; a routed item's task message inherits it.", "$ref": "#/$defs/NotAfter" }
+      }
+    },
+    "Intake": {
+      "description": "A team intake item as read (StoredIntake in src/central/teams/intake.ts).",
+      "type": "object",
+      "required": ["v", "id", "teamID", "title", "source", "status", "revision", "createdAt", "priority", "updatedAt"],
+      "properties": {
+        "v": { "const": 1 },
+        "id": { "type": "string", "pattern": "^itk_[A-Za-z0-9]{16,32}$" },
+        "teamID": { "type": "string", "pattern": "^team_[A-Za-z0-9]{16,32}$" },
+        "title": { "type": "string" },
+        "source": { "$ref": "#/$defs/IntakeSource" },
+        "ref": { "type": "string" },
+        "assignmentID": { "type": "string" },
+        "status": { "$ref": "#/$defs/IntakeStatus" },
+        "revision": { "type": "integer", "minimum": 1 },
+        "createdAt": { "$ref": "#/$defs/EpochMs" },
+        "priority": { "$ref": "#/$defs/IntakePriority" },
+        "labels": { "type": "array", "items": { "type": "string" } },
+        "due": { "$ref": "#/$defs/EpochMs" },
+        "criteria": { "type": "array", "items": { "type": "string" } },
+        "workspaceID": { "type": "string" },
+        "sessionID": { "type": "string" },
+        "messageID": { "type": "string" },
+        "progress": { "$ref": "#/$defs/IntakeProgress" },
+        "reason": { "description": "Why it failed or was cancelled (free text, at most 200; exactly `not_after` when the hub expired it, H4).", "type": "string" },
+        "lastError": { "type": "string" },
+        "updatedAt": { "$ref": "#/$defs/EpochMs" },
+        "routedAt": { "$ref": "#/$defs/EpochMs" },
+        "closedAt": { "$ref": "#/$defs/EpochMs" },
+        "notAfter": { "description": "(H4) As submitted.", "$ref": "#/$defs/EpochMs" }
+      }
+    },
+    "IntakeResponse": { "type": "object", "required": ["intake"], "properties": { "intake": { "$ref": "#/$defs/Intake" } } },
+    "IntakeListResponse": {
+      "type": "object",
+      "required": ["items"],
+      "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/Intake" } }, "cursor": { "type": "string" } }
+    },
+    "IntakeStatusRequest": {
+      "description": "POST /api/agent/teams/:id/intake/:intake/status.",
+      "type": "object",
+      "required": ["status", "expectedRevision"],
+      "additionalProperties": false,
+      "properties": {
+        "status": { "$ref": "#/$defs/IntakeStatusInput" },
+        "expectedRevision": { "type": "integer", "minimum": 0 },
+        "reason": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "IntakeStatusResponse": {
+      "type": "object",
+      "required": ["intake"],
+      "properties": { "intake": { "$ref": "#/$defs/Intake" }, "assignment": { "type": "object", "required": ["id", "status", "revision"], "properties": { "id": { "type": "string" }, "status": { "enum": ["open", "in_progress", "blocked", "done", "cancelled"] }, "revision": { "type": "integer", "minimum": 1 } } } }
+    },
+
+    "EventID": { "description": "Journal events: evt_ + 20 hex; legacy launch.<state> webhook events: evt_ + 24 hex.", "type": "string", "pattern": "^evt_[0-9a-f]{20}([0-9a-f]{4})?$" },
+    "AgentEvent": {
+      "description": "A journal event as GET /api/agent/events returns it (AgentEvent in src/central/agent/events.ts).",
+      "type": "object",
+      "required": ["id", "at", "type", "subject", "data"],
+      "properties": {
+        "id": { "$ref": "#/$defs/EventID" },
+        "at": { "$ref": "#/$defs/EpochMs" },
+        "type": { "type": "string" },
+        "subject": { "type": "object", "additionalProperties": { "type": "string" } },
+        "data": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean"] } }
+      }
+    },
+
+    "LaunchChangedSubject": {
+      "type": "object",
+      "required": ["launchID"],
+      "additionalProperties": false,
+      "properties": { "launchID": { "type": "string" }, "sessionID": { "type": "string" } }
+    },
+    "LaunchChangedEventData": {
+      "description": "launch.changed data (launchEvent in src/central/agent/events.ts): never prompt, reason or labels.",
+      "type": "object",
+      "required": ["state"],
+      "additionalProperties": false,
+      "properties": {
+        "state": { "$ref": "#/$defs/LaunchState" },
+        "outcome": { "$ref": "#/$defs/LaunchOutcome" },
+        "name": { "type": "string" },
+        "wait": { "$ref": "#/$defs/LaunchWait" }
+      }
+    },
+    "MessageChangedSubject": {
+      "type": "object",
+      "required": ["messageID"],
+      "additionalProperties": false,
+      "properties": { "messageID": { "type": "string" }, "sessionID": { "type": "string" }, "senderID": { "type": "string" } }
+    },
+    "MessageChangedEventData": {
+      "description": "message.changed data (messageEvent in src/central/agent/events.ts): never the text.",
+      "type": "object",
+      "required": ["kind", "state", "from", "to"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "$ref": "#/$defs/MessageKind" },
+        "state": { "$ref": "#/$defs/MessageState" },
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "replyTo": { "type": "string" },
+        "delivery": { "$ref": "#/$defs/MessageDelivery" },
+        "reason": { "description": "(H2) Only with delivery expired: which deadline passed (an enum, never text).", "$ref": "#/$defs/ExpiredReason" }
+      }
+    },
+    "TeamIntakeSubject": {
+      "type": "object",
+      "required": ["teamID", "intakeID"],
+      "additionalProperties": false,
+      "properties": { "teamID": { "type": "string" }, "intakeID": { "type": "string" }, "assignmentID": { "type": "string" }, "workspaceID": { "type": "string" }, "sessionID": { "type": "string" } }
+    },
+    "TeamIntakeEventData": {
+      "description": "team.intake data (intakeEvent in src/central/teams/intake.ts): enums, revision and timestamps only; never title, brief, labels, criteria or the free-text reason.",
+      "type": "object",
+      "required": ["status", "revision", "source", "priority", "createdAt", "updatedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "status": { "$ref": "#/$defs/IntakeStatus" },
+        "revision": { "type": "integer", "minimum": 1 },
+        "source": { "enum": ["user", "app", "session"] },
+        "priority": { "$ref": "#/$defs/IntakePriority" },
+        "progress": { "$ref": "#/$defs/IntakeProgress" },
+        "reasonCode": { "description": "A code, never text: the last routing failure's error code (lastError, an ErrorCode) or (H4) `not_after` on an item cancelled because its notAfter passed while queued.", "type": "string", "pattern": "^[a-z][a-z_]{0,39}$" },
+        "createdAt": { "$ref": "#/$defs/EpochMs" },
+        "updatedAt": { "$ref": "#/$defs/EpochMs" },
+        "routedAt": { "$ref": "#/$defs/EpochMs" },
+        "closedAt": { "$ref": "#/$defs/EpochMs" }
+      }
+    },
+
+    "CanonicalWebhookEventType": {
+      "description": "Event types a webhook can select today (CANONICAL_WEBHOOK_EVENT_TYPES in src/central/agent/webhooks.ts). Patterns may also be `<family>.*`, except for ExactOnlyWebhookEventType.",
+      "enum": ["session.added", "session.removed", "session.changed", "session.archived", "session.named", "session.pinned", "blocker.opened", "blocker.closed", "machine.changed", "role.claimed", "role.released", "message.changed", "launch.changed", "team.intake"]
+    },
+    "ExactOnlyWebhookEventType": { "description": "(H5) Types no family wildcard selects: register them by exact name (`team.*` is 400 invalid).", "enum": ["team.intake"] },
+    "LegacyLaunchWebhookType": {
+      "description": "Pre-canonical registration patterns kept for rollback compatibility: a registration for launch.<state> receives the launch.changed body of that state.",
+      "type": "string",
+      "pattern": "^launch\\.(queued|placing|provisioning|running|ended)$"
+    },
+    "WebhookEnvelope": {
+      "description": "Every webhook POST body (CloudEvents-shaped; WebhookEvent in src/central/agent/webhooks.ts). Headers: WebhookHeaders.",
+      "type": "object",
+      "required": ["id", "type", "source", "subject", "time", "user", "schemaVersion", "data"],
+      "properties": {
+        "id": { "$ref": "#/$defs/EventID" },
+        "type": { "type": "string" },
+        "source": { "description": "The hub's public URL.", "type": "string" },
+        "subject": { "description": "The launch, message, intake, session or machine ID (first present, in that order), else the event ID.", "type": "string" },
+        "time": { "description": "ISO 8601 (Date.prototype.toISOString).", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" },
+        "user": { "type": "string" },
+        "schemaVersion": { "const": 1 },
+        "data": {}
+      }
+    },
+    "CanonicalWebhookData": {
+      "description": "The data of a canonical webhook event: the journal event's subject and data.",
+      "type": "object",
+      "required": ["subject", "data"],
+      "additionalProperties": false,
+      "properties": { "subject": { "type": "object" }, "data": { "type": "object" } }
+    },
+    "LaunchChangedWebhook": {
+      "allOf": [
+        { "$ref": "#/$defs/WebhookEnvelope" },
+        {
+          "properties": {
+            "type": { "const": "launch.changed" },
+            "data": {
+              "allOf": [{ "$ref": "#/$defs/CanonicalWebhookData" }, { "properties": { "subject": { "$ref": "#/$defs/LaunchChangedSubject" }, "data": { "$ref": "#/$defs/LaunchChangedEventData" } } }]
+            }
+          }
+        }
+      ]
+    },
+    "LegacyLaunchWebhook": {
+      "description": "The pre-canonical `launch.<state>` body (launchEvent in src/central/agent/webhooks.ts: data {launch}). Webhooks.onLaunch builds it but the current hub never calls it (src/central/http.ts publishes canonical events only); kept for receivers of older hubs.",
+      "allOf": [
+        { "$ref": "#/$defs/WebhookEnvelope" },
+        {
+          "properties": {
+            "type": { "$ref": "#/$defs/LegacyLaunchWebhookType" },
+            "data": { "type": "object", "required": ["launch"], "properties": { "launch": { "$ref": "#/$defs/Launch" } } }
+          }
+        }
+      ]
+    },
+    "MessageChangedWebhook": {
+      "allOf": [
+        { "$ref": "#/$defs/WebhookEnvelope" },
+        {
+          "properties": {
+            "type": { "const": "message.changed" },
+            "data": {
+              "allOf": [{ "$ref": "#/$defs/CanonicalWebhookData" }, { "properties": { "subject": { "$ref": "#/$defs/MessageChangedSubject" }, "data": { "$ref": "#/$defs/MessageChangedEventData" } } }]
+            }
+          }
+        }
+      ]
+    },
+    "TeamIntakeWebhook": {
+      "description": "(H5) team.intake; envelope subject = the intake ID. A user's registrations get every one; an app's only those of intake that app submitted (event audience by app:<tokenID>).",
+      "allOf": [
+        { "$ref": "#/$defs/WebhookEnvelope" },
+        {
+          "properties": {
+            "type": { "const": "team.intake" },
+            "data": {
+              "allOf": [{ "$ref": "#/$defs/CanonicalWebhookData" }, { "properties": { "subject": { "$ref": "#/$defs/TeamIntakeSubject" }, "data": { "$ref": "#/$defs/TeamIntakeEventData" } } }]
+            }
+          }
+        }
+      ]
+    },
+    "HubSignature": {
+      "description": "The Hub-Signature header as the hub sends it: t=<unix seconds>,v1=<hex HMAC-SHA256 over `<t>.<raw body>` keyed with the registration's whsec_ secret>; one v1 per active secret while a secret rotates. Receivers accept any matching v1, compare in constant time, refuse |now - t| > 300 s, and ignore unknown schemes (packages/protocol/src/webhook.ts).",
+      "type": "string",
+      "maxLength": 2048,
+      "pattern": "^t=[0-9]{1,12}(,v1=[0-9a-f]{64})+$"
+    },
+    "WebhookHeaders": {
+      "description": "Headers of every webhook POST (names lower-cased). Hub-Delivery is stable across retries: deduplicate on it.",
+      "type": "object",
+      "required": ["hub-signature", "hub-event", "hub-delivery", "content-type"],
+      "properties": {
+        "hub-signature": { "$ref": "#/$defs/HubSignature" },
+        "hub-event": { "type": "string" },
+        "hub-delivery": { "type": "string", "pattern": "^whd_[0-9a-f]{24}$" },
+        "content-type": { "const": "application/json" }
+      }
+    },
+    "WebhookRegisterRequest": {
+      "description": "POST /api/agent/webhooks. Users; apps need webhookRequiredScopes(events): events:subscribe plus each selected type's scope, except that events [\"team.intake\"] alone needs only teams:submit. events default [\"launch.*\"].",
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "events": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string" } },
+        "label": { "type": ["string", "null"], "maxLength": 100 }
+      }
+    },
+    "WebhookView": {
+      "type": "object",
+      "required": ["id", "url", "events", "by", "created"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^wh_[0-9a-f]{16}$" },
+        "secret": false,
+        "url": { "type": "string" },
+        "events": { "type": "array", "items": { "type": "string" } },
+        "by": { "type": "string", "pattern": "^(user|app:.+)$" },
+        "label": { "type": "string" },
+        "created": { "$ref": "#/$defs/EpochMs" }
+      }
+    },
+    "WebhookRegisterResponse": {
+      "description": "201: the secret is shown only here.",
+      "type": "object",
+      "required": ["webhook", "secret"],
+      "properties": { "webhook": { "$ref": "#/$defs/WebhookView" }, "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$" } }
+    },
+
+    "RelayState": { "description": "(H6) The state of one store-and-forward relay item.", "enum": ["queued", "delivered", "conflicted", "failed", "expired"] },
+    "RelayItem": {
+      "description": "(H6) A hub-initiated write to a connected app, as the hub shows it (never its body or the app's URL).",
+      "type": "object",
+      "required": ["id", "connection", "state", "attempts", "created"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^rly_[0-9a-f]{24}$" },
+        "connection": { "type": "string" },
+        "state": { "$ref": "#/$defs/RelayState" },
+        "attempts": { "type": "integer", "minimum": 0 },
+        "created": { "$ref": "#/$defs/EpochMs" },
+        "nextAt": { "$ref": "#/$defs/EpochMs" },
+        "notAfter": { "$ref": "#/$defs/EpochMs" },
+        "expiredReason": { "$ref": "#/$defs/ExpiredReason" },
+        "last": {
+          "type": "object",
+          "required": ["at"],
+          "properties": { "at": { "$ref": "#/$defs/EpochMs" }, "status": { "type": "integer" }, "error": { "type": "string", "maxLength": 300 } }
+        }
+      }
+    }
+  }
+}