@huynle/hub 0.9.2 → 0.10.0

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

@@ -0,0 +1,410 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/huynle/hub/packages/protocol/schema/app-front/v1.schema.json",
+  "title": "Hub app-front surface",
+  "description": "What an external app (a server-side BFF) uses to make Hub its AI layer: connect with consent (AF1), speech (AF2), the conversation stream (AF3), answering its own sessions' confirm-tier Decisions (AF4), frozen by docs/plans/2026-11-08-app-front-contracts.md. Every definition lives in $defs; validate against `<$id>#/$defs/<Name>`. A description starting `(AFn)` is contract-only until that task ships its `/.well-known/hub` feature flag (APP_FRONT_SHIPPED in packages/protocol/src/app-front.ts); `(shipped)` validates today's hub. REST views are open (clients ignore unknown fields); stream frames are closed allowlists: a new frame field needs a schema change in the same commit. OAuth endpoints (`/connect/*`) answer the OAuth error body (TokenErrorResponse), never the /api/agent ErrorBody. `schemaVersion` is an annotation keyword (ajv.addVocabulary(['schemaVersion'])).",
+  "schemaVersion": 1,
+  "$defs": {
+    "SchemaVersion": { "description": "The version of this schema document (APP_FRONT_VERSION); additive changes keep 1.", "const": 1 },
+    "EpochMs": { "description": "Milliseconds since the Unix epoch.", "type": "integer", "minimum": 0 },
+
+    "AppFrontScope": {
+      "description": "The scopes the app front adds to APP_SCOPES (APP_FRONT_SCOPES). speech:use (AF2) transcribe/speak; conversation:read (AF3) the stream and the log of the app's sessions; conversation:write (AF3) conversation, utterance, interrupt and typed turns, each also behind a grant allowing prompt; decisions:answer (AF4) confirm-tier Decisions of the app's sessions. A scope never implies another.",
+      "enum": ["speech:use", "conversation:read", "conversation:write", "decisions:answer"]
+    },
+    "AppFrontFeature": {
+      "description": "`/.well-known/hub` features flags (APP_FRONT_FEATURES): app-connect (AF1), app-speech (AF2), app-conversation (AF3), app-decisions (AF4). A hub lists a flag only once it ships it; clients ignore flags they do not know.",
+      "enum": ["app-connect", "app-speech", "app-conversation", "app-decisions"]
+    },
+    "WellKnownHub": {
+      "description": "(shipped) GET /.well-known/hub (wellKnown in src/central/agent/routes.ts): public discovery. `features` is [] until an AF task ships its flag.",
+      "type": "object",
+      "required": ["publicURL", "version", "minClientVersion", "auth", "features"],
+      "properties": {
+        "publicURL": { "type": "string" },
+        "version": { "type": "string" },
+        "minClientVersion": { "type": "string" },
+        "auth": { "type": "object", "required": ["modes"], "properties": { "modes": { "type": "array", "items": { "enum": ["pairing", "oidc"] } } } },
+        "features": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$" } }
+      }
+    },
+
+    "ErrorCode": {
+      "description": "The /api/agent error codes the app-front routes answer: today's AGENT_ERROR_STATUS codes plus (AF2) `upstream_failed` 502 (the speech provider failed). Bodies: {error: {code, message, hint?, retryAfter?, ...}} as in the app-delivery schema.",
+      "enum": ["invalid", "unauthorized", "token_expired", "forbidden", "not_found", "conflict", "gone", "unsupported", "paused", "rate_limited", "offline", "busy", "upstream_failed"]
+    },
+    "NewErrorCodeStatus": { "description": "(AF2) Error codes the app front adds to AGENT_ERROR_STATUS, with their status.", "const": { "upstream_failed": 502 } },
+    "ErrorBody": {
+      "type": "object",
+      "required": ["error"],
+      "properties": {
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z_]{0,39}$" }, "message": { "type": "string" }, "hint": { "type": "string" }, "retryAfter": { "type": "integer", "minimum": 0 } }
+        }
+      }
+    },
+
+    "AppActor": {
+      "description": "(shipped for hat_ tokens) GET /api/agent/whoami `actor` of an app credential. (AF1) A connected app's access token answers `connection: true` and `clientID`; its `tokenID` is the connection ID (stable across refresh and re-consent), so `app:<tokenID>` (launch `by`, grant holders, message parties) keeps naming the same app.",
+      "type": "object",
+      "required": ["kind", "userID", "tokenID", "scopes"],
+      "properties": {
+        "kind": { "const": "app" },
+        "userID": { "type": "string" },
+        "tokenID": { "$ref": "#/$defs/ConnectionID" },
+        "scopes": { "type": "array", "items": { "type": "string" } },
+        "label": { "type": "string" },
+        "clientID": { "$ref": "#/$defs/ClientID" },
+        "connection": { "const": true }
+      }
+    },
+
+    "ClientID": { "description": "(AF1) A registered client's public ID.", "type": "string", "pattern": "^hcl_[0-9a-f]{16}$" },
+    "ClientSecret": { "description": "(AF1) Shown once at registration and on rotation; only its sha256 is stored.", "type": "string", "pattern": "^hcs_[A-Za-z0-9_-]{43}$" },
+    "FlowID": { "description": "(AF1) A pending connect flow (authorize → consent), CONNECT_FLOW_TTL_MS.", "type": "string", "pattern": "^hcf_[0-9a-f]{24}$" },
+    "AuthorizationCode": { "description": "(AF1) One-time, AUTHORIZATION_CODE_TTL_MS; a second use revokes the connection it issued.", "type": "string", "pattern": "^hco_[A-Za-z0-9_-]{43}$" },
+    "AccessToken": { "description": "(AF1) Bearer for /api/agent, ACCESS_TOKEN_TTL_MS; carries the connection ID.", "type": "string", "pattern": "^hca_[0-9a-f]{16}_[A-Za-z0-9_-]{43}$" },
+    "RefreshToken": { "description": "(AF1) Rotating, single use, REFRESH_TOKEN_IDLE_MS sliding; the just-rotated one answers the same new pair for REFRESH_GRACE_MS, any other reuse revokes the connection.", "type": "string", "pattern": "^hcr_[0-9a-f]{16}_[A-Za-z0-9_-]{43}$" },
+    "ConnectionID": { "description": "A hand-made token's ID or (AF1) a connection's ID: 16 hex.", "type": "string", "pattern": "^[0-9a-f]{16}$" },
+    "ConnectLifetimes": {
+      "description": "(AF1) Lifetimes in ms (ACCESS_TOKEN_TTL_MS, REFRESH_TOKEN_IDLE_MS, AUTHORIZATION_CODE_TTL_MS, CONNECT_FLOW_TTL_MS, REFRESH_GRACE_MS: the just-rotated refresh token answers the same new pair this long, decision nixct956 3).",
+      "const": { "accessToken": 3600000, "refreshTokenIdle": 2592000000, "authorizationCode": 60000, "flow": 600000, "refreshGrace": 30000 }
+    },
+    "ConnectLimits": {
+      "description": "(AF1) CONNECT_LIMITS: clients = hub-wide clients; personalClientsPerUser; authorizePerMinute per client and client address; tokenPerMinute per client, authenticated requests only; failedClientAuthPerMinute per client and client address (beyond: 429 for that address's failures only).",
+      "const": { "clients": 50, "personalClientsPerUser": 10, "redirectURIsPerClient": 10, "clientNameMax": 100, "stateMax": 1024, "connectionsPerUser": 50, "authorizePerMinute": 20, "tokenPerMinute": 60, "failedClientAuthPerMinute": 10 }
+    },
+    "RedirectURI": {
+      "description": "(AF1) Absolute https URL (http only on 127.0.0.1, [::1] or localhost), ≤ 2048 characters, no user info, fragment or wildcard (redirectUriProblem is authoritative; this pattern is a coarse check). Matched by exact string comparison.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048,
+      "pattern": "^https?://[^\\s#*]+$"
+    },
+
+    "AuthorizationServerMetadata": {
+      "description": "(AF1) GET /.well-known/oauth-authorization-server (RFC 8414), public. The same document shape Brain v2 G1 publishes.",
+      "type": "object",
+      "required": ["issuer", "authorization_endpoint", "token_endpoint", "revocation_endpoint", "response_types_supported", "grant_types_supported", "code_challenge_methods_supported", "token_endpoint_auth_methods_supported", "scopes_supported", "authorization_response_iss_parameter_supported"],
+      "properties": {
+        "issuer": { "description": "The hub's public URL.", "type": "string" },
+        "authorization_endpoint": { "type": "string" },
+        "token_endpoint": { "type": "string" },
+        "revocation_endpoint": { "type": "string" },
+        "response_types_supported": { "const": ["code"] },
+        "grant_types_supported": { "const": ["authorization_code", "refresh_token"] },
+        "code_challenge_methods_supported": { "const": ["S256"] },
+        "token_endpoint_auth_methods_supported": { "const": ["client_secret_basic", "client_secret_post"] },
+        "scopes_supported": { "type": "array", "items": { "type": "string" } },
+        "authorization_response_iss_parameter_supported": { "const": true },
+        "service_documentation": { "type": "string" }
+      }
+    },
+    "AuthorizeRequest": {
+      "description": "(AF1) GET /connect/authorize query. An unknown client_id or a redirect_uri not registered for it shows an error page and never redirects; every other problem redirects with AuthorizeErrorRedirect.",
+      "type": "object",
+      "required": ["response_type", "client_id", "redirect_uri", "scope", "state", "code_challenge", "code_challenge_method"],
+      "additionalProperties": false,
+      "properties": {
+        "response_type": { "const": "code" },
+        "client_id": { "$ref": "#/$defs/ClientID" },
+        "redirect_uri": { "$ref": "#/$defs/RedirectURI" },
+        "scope": { "description": "Space-separated (parseScopeParam), within the client's allowed scopes.", "type": "string", "minLength": 1, "pattern": "^[a-z:]+( [a-z:]+)*$" },
+        "state": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "code_challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" },
+        "code_challenge_method": { "const": "S256" }
+      }
+    },
+    "AuthorizeSuccessRedirect": {
+      "description": "(AF1) Query added to redirect_uri on approval (RFC 9207 `iss`).",
+      "type": "object",
+      "required": ["code", "state", "iss"],
+      "additionalProperties": false,
+      "properties": { "code": { "$ref": "#/$defs/AuthorizationCode" }, "state": { "type": "string" }, "iss": { "type": "string" } }
+    },
+    "AuthorizeError": { "description": "(AF1) AUTHORIZE_ERRORS (RFC 6749 §4.1.2.1).", "enum": ["invalid_request", "unauthorized_client", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", "temporarily_unavailable"] },
+    "AuthorizeErrorRedirect": {
+      "description": "(AF1) Query added to redirect_uri on a refusal (only once client_id and redirect_uri are valid).",
+      "type": "object",
+      "required": ["error", "iss"],
+      "additionalProperties": false,
+      "properties": { "error": { "$ref": "#/$defs/AuthorizeError" }, "error_description": { "type": "string", "maxLength": 200 }, "state": { "type": "string" }, "iss": { "type": "string" } }
+    },
+    "ConnectFlowView": {
+      "description": "(AF1) GET /api/connect/flows/:flow (console, the signed-in user): what the consent page shows. `scopes` is what the app asked for (within its client's allowed scopes); `connection` the user's current connection to this client, if any.",
+      "type": "object",
+      "required": ["id", "client", "scopes", "expiresAt"],
+      "properties": {
+        "id": { "$ref": "#/$defs/FlowID" },
+        "client": { "type": "object", "required": ["id", "name", "redirectOrigin"], "properties": { "id": { "$ref": "#/$defs/ClientID" }, "name": { "type": "string" }, "redirectOrigin": { "type": "string" } } },
+        "scopes": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "expiresAt": { "$ref": "#/$defs/EpochMs" },
+        "connection": { "type": "object", "required": ["id", "scopes"], "properties": { "id": { "$ref": "#/$defs/ConnectionID" }, "scopes": { "type": "array", "items": { "type": "string" } } } }
+      }
+    },
+    "ConnectApproveRequest": {
+      "description": "(AF1) POST /api/connect/flows/:flow/approve (cookie only, same origin): the scopes the user grants, a non-empty subset of the flow's.",
+      "type": "object",
+      "required": ["scopes"],
+      "additionalProperties": false,
+      "properties": { "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } } }
+    },
+    "ConnectDecisionResponse": {
+      "description": "(AF1) Approve or deny answers where the page navigates: redirect_uri with AuthorizeSuccessRedirect or (deny) error=access_denied.",
+      "type": "object",
+      "required": ["redirect"],
+      "properties": { "redirect": { "type": "string" } }
+    },
+    "TokenRequestCode": {
+      "description": "(AF1) POST /connect/token, application/x-www-form-urlencoded, client authenticated (client_secret_basic or client_secret_post).",
+      "type": "object",
+      "required": ["grant_type", "code", "redirect_uri", "code_verifier"],
+      "properties": {
+        "grant_type": { "const": "authorization_code" },
+        "code": { "$ref": "#/$defs/AuthorizationCode" },
+        "redirect_uri": { "$ref": "#/$defs/RedirectURI" },
+        "code_verifier": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{43,128}$" },
+        "client_id": { "$ref": "#/$defs/ClientID" },
+        "client_secret": { "$ref": "#/$defs/ClientSecret" }
+      }
+    },
+    "TokenRequestRefresh": {
+      "description": "(AF1) POST /connect/token with a refresh token: a new access token and a new refresh token; the old refresh token is spent. `scope` may only narrow.",
+      "type": "object",
+      "required": ["grant_type", "refresh_token"],
+      "properties": {
+        "grant_type": { "const": "refresh_token" },
+        "refresh_token": { "$ref": "#/$defs/RefreshToken" },
+        "scope": { "type": "string" },
+        "client_id": { "$ref": "#/$defs/ClientID" },
+        "client_secret": { "$ref": "#/$defs/ClientSecret" }
+      }
+    },
+    "TokenResponse": {
+      "description": "(AF1) 200, cache-control no-store.",
+      "type": "object",
+      "required": ["access_token", "token_type", "expires_in", "refresh_token", "scope", "connection_id"],
+      "properties": {
+        "access_token": { "$ref": "#/$defs/AccessToken" },
+        "token_type": { "const": "Bearer" },
+        "expires_in": { "const": 3600 },
+        "refresh_token": { "$ref": "#/$defs/RefreshToken" },
+        "scope": { "type": "string" },
+        "connection_id": { "$ref": "#/$defs/ConnectionID" }
+      }
+    },
+    "TokenErrorStatus": { "description": "(AF1) TOKEN_ERROR_STATUS: RFC 6749 §5.2 codes and their status (temporarily_unavailable 429 with Retry-After: rate limit).", "const": { "invalid_request": 400, "invalid_client": 401, "invalid_grant": 400, "unauthorized_client": 400, "unsupported_grant_type": 400, "invalid_scope": 400, "temporarily_unavailable": 429 } },
+    "TokenErrorResponse": {
+      "description": "(AF1) The body of every /connect/token and /connect/revoke refusal.",
+      "type": "object",
+      "required": ["error"],
+      "additionalProperties": false,
+      "properties": {
+        "error": { "enum": ["invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope", "temporarily_unavailable"] },
+        "error_description": { "type": "string", "maxLength": 200 }
+      }
+    },
+    "RevokeRequest": {
+      "description": "(AF1) POST /connect/revoke (RFC 7009), form-encoded, client authenticated. Either token ends the whole connection (access and refresh). Always 200 with an empty body, also for an unknown or already revoked token.",
+      "type": "object",
+      "required": ["token"],
+      "properties": { "token": { "type": "string" }, "token_type_hint": { "enum": ["access_token", "refresh_token"] } }
+    },
+    "ClientAudience": { "description": "(AF1) CLIENT_AUDIENCES (decision nixct956 5): hub = hub-wide (admins register; every user may connect); user = personal (only its owner sees and uses it).", "enum": ["hub", "user"] },
+    "AppClientRegisterRequest": {
+      "description": "(AF1) POST /api/agent/app-clients (a user actor, cookie or device token; never an app or session). Admins register hub-wide clients (audience hub, their default) or personal ones; other users only personal ones (audience user, their default). No dynamic registration.",
+      "type": "object",
+      "required": ["name", "redirectURIs", "scopes"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "redirectURIs": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/$defs/RedirectURI" } },
+        "scopes": { "description": "The ceiling: what a consent may grant (APP_SCOPES plus AppFrontScope).", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } },
+        "audience": { "$ref": "#/$defs/ClientAudience" }
+      }
+    },
+    "AppClientUpdateRequest": {
+      "description": "(AF1) PATCH /api/agent/app-clients/:id: hub-wide clients by an admin, personal ones by their owner only (else 404). Narrowing scopes narrows every connection; disabled true revokes every connection. The audience never changes.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "redirectURIs": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "$ref": "#/$defs/RedirectURI" } },
+        "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } },
+        "disabled": { "type": "boolean" }
+      }
+    },
+    "AppClientView": {
+      "description": "(AF1) A registered client as GET /api/agent/app-clients {clients} shows it (hub-wide ones and the caller's own personal ones): never the secret or its hash.",
+      "type": "object",
+      "required": ["id", "name", "redirectURIs", "scopes", "created", "createdBy", "audience"],
+      "properties": {
+        "id": { "$ref": "#/$defs/ClientID" },
+        "secret": false,
+        "name": { "type": "string" },
+        "redirectURIs": { "type": "array", "items": { "type": "string" } },
+        "scopes": { "type": "array", "items": { "type": "string" } },
+        "created": { "$ref": "#/$defs/EpochMs" },
+        "createdBy": { "type": "string" },
+        "audience": { "$ref": "#/$defs/ClientAudience" },
+        "disabled": { "const": true }
+      }
+    },
+    "AppClientRegisterResponse": {
+      "description": "(AF1) 201; the secret is shown only here (and by POST …/:id/secret, which rotates it).",
+      "type": "object",
+      "required": ["client", "secret"],
+      "properties": { "client": { "$ref": "#/$defs/AppClientView" }, "secret": { "$ref": "#/$defs/ClientSecret" } }
+    },
+    "ConnectionView": {
+      "description": "(AF1) GET /api/agent/connections (the user's own): never a token or hash. DELETE …/:id revokes it.",
+      "type": "object",
+      "required": ["id", "clientID", "clientName", "scopes", "created", "refreshExpiresAt"],
+      "properties": {
+        "id": { "$ref": "#/$defs/ConnectionID" },
+        "clientID": { "$ref": "#/$defs/ClientID" },
+        "clientName": { "type": "string" },
+        "scopes": { "type": "array", "items": { "type": "string" } },
+        "created": { "$ref": "#/$defs/EpochMs" },
+        "lastUsed": { "$ref": "#/$defs/EpochMs" },
+        "refreshExpiresAt": { "$ref": "#/$defs/EpochMs" }
+      }
+    },
+
+    "SpeechRateLimits": { "description": "(AF2) SPEECH_RATE_LIMITS per app credential; beyond: 429 rate_limited with retryAfter.", "const": { "transcribe": { "perMinute": 20, "perHour": 300 }, "speak": { "perMinute": 60, "perHour": 1000, "charsPerHour": 100000 } } },
+    "TranscribeResponse": {
+      "description": "(AF2) POST /api/agent/speech/transcribe: raw audio body (Content-Type an accepted audio type, ≤ the hub's maxAudioBytes) → 200 {text}.",
+      "type": "object",
+      "required": ["text"],
+      "properties": { "text": { "type": "string" } }
+    },
+    "SpeakRequest": {
+      "description": "(AF2) POST /api/agent/speech/speak → 200 audio/mpeg (streamed). text: 1–maxSpeechChars after speakable(); counts toward charsPerHour.",
+      "type": "object",
+      "required": ["text"],
+      "additionalProperties": false,
+      "properties": { "text": { "type": "string", "minLength": 1 } }
+    },
+
+    "ConversationRequest": {
+      "description": "(AF3) POST /api/agent/sessions/:addr/conversation (conversation:write + a prompt grant covering the session).",
+      "type": "object",
+      "required": ["on"],
+      "additionalProperties": false,
+      "properties": { "on": { "type": "boolean" }, "front": { "type": "boolean" } }
+    },
+    "ConversationResponse": {
+      "description": "(AF3) As the console route answers.",
+      "type": "object",
+      "required": ["on"],
+      "properties": { "on": { "type": "boolean" }, "agent": { "type": "string" }, "front": { "type": "boolean" } }
+    },
+    "UtteranceRequest": {
+      "description": "(AF3) POST /api/agent/sessions/:addr/utterance: a final transcript, 1–4000 characters (MAX_UTTERANCE_CHARS). One action under the grant's maxActionsPerHour.",
+      "type": "object",
+      "required": ["text"],
+      "additionalProperties": false,
+      "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }
+    },
+    "UtteranceResponse": { "description": "(AF3) 202; a `heard` frame with this inboxID follows when it reached the agent.", "type": "object", "required": ["inboxID"], "properties": { "inboxID": { "type": "string" } } },
+
+    "StreamLimits": { "description": "(AF3) APP_STREAM_LIMITS.", "const": { "heartbeatMs": 20000, "retryMs": 2000, "recheckMs": 30000, "bufferMaxBytes": 1048576, "streamsPerApp": 4, "streamsPerUser": 20 } },
+    "StreamFrameType": { "description": "(AF3) APP_STREAM_FRAME_TYPES.", "enum": ["ready", "delta", "say", "heard", "status", "conversation", "reset", "end"] },
+    "StreamEndReason": { "description": "(AF3) APP_STREAM_END_REASONS.", "enum": ["token_expired", "revoked", "grant", "gone", "slow"] },
+    "StreamRefresh": { "description": "(AF3) APP_STREAM_REFRESH: what a reset asks to re-read.", "enum": ["log", "status", "conversation", "decisions"] },
+    "SessionState": { "description": "SessionState in packages/protocol.", "enum": ["idle", "working", "blocked", "error"] },
+    "StreamReady": {
+      "description": "(AF3) First frame, once subscribed: the session's state now.",
+      "type": "object",
+      "required": ["type", "at", "sessionID", "status", "conversation"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "ready" },
+        "at": { "$ref": "#/$defs/EpochMs" },
+        "sessionID": { "type": "string" },
+        "status": { "$ref": "#/$defs/SessionState" },
+        "conversation": { "type": "object", "required": ["on"], "additionalProperties": false, "properties": { "on": { "type": "boolean" }, "front": { "type": "boolean" } } }
+      }
+    },
+    "StreamDelta": {
+      "description": "(AF3) Assistant text of the session itself (never a subagent's, never reasoning), coalesced per STREAM_INTERVAL_MS. Untrusted text.",
+      "type": "object",
+      "required": ["type", "sessionID", "text"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "delta" }, "sessionID": { "type": "string" }, "messageID": { "type": "string" }, "ordinal": { "type": "integer", "minimum": 0 }, "text": { "type": "string" } }
+    },
+    "StreamSay": {
+      "description": "(AF3) A sentence to speak in conversation mode (also the voice front's, with sessionID = main). Untrusted text.",
+      "type": "object",
+      "required": ["type", "sessionID", "messageID", "ordinal", "text"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "say" }, "sessionID": { "type": "string" }, "messageID": { "type": "string" }, "ordinal": { "type": "integer", "minimum": 0 }, "seq": { "type": "integer", "minimum": 0 }, "text": { "type": "string" } }
+    },
+    "StreamHeard": {
+      "description": "(AF3) An utterance reached the agent.",
+      "type": "object",
+      "required": ["type", "sessionID", "inboxID"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "heard" }, "sessionID": { "type": "string" }, "inboxID": { "type": "string" } }
+    },
+    "StreamStatus": {
+      "description": "(AF3) The session's state changed: an enum and a count, never blocker text.",
+      "type": "object",
+      "required": ["type", "sessionID", "state", "blockers"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "status" }, "sessionID": { "type": "string" }, "state": { "$ref": "#/$defs/SessionState" }, "blockers": { "type": "integer", "minimum": 0 }, "since": { "$ref": "#/$defs/EpochMs" } }
+    },
+    "StreamConversation": {
+      "description": "(AF3) Conversation mode changed (front: voice front P1; reason front_failed: utterances go to the session itself).",
+      "type": "object",
+      "required": ["type", "sessionID", "on"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "conversation" }, "sessionID": { "type": "string" }, "on": { "type": "boolean" }, "front": { "type": "boolean" }, "reason": { "const": "front_failed" } }
+    },
+    "StreamReset": {
+      "description": "(AF3) The resume point is not covered (or, in cluster mode, streamed text may be missing): re-read `refresh`, then continue.",
+      "type": "object",
+      "required": ["type", "at", "refresh"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "reset" }, "at": { "$ref": "#/$defs/EpochMs" }, "refresh": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/StreamRefresh" } } }
+    },
+    "StreamEnd": {
+      "description": "(AF3) The last frame before the hub closes the stream.",
+      "type": "object",
+      "required": ["type", "at", "reason"],
+      "additionalProperties": false,
+      "properties": { "type": { "const": "end" }, "at": { "$ref": "#/$defs/EpochMs" }, "reason": { "$ref": "#/$defs/StreamEndReason" } }
+    },
+    "StreamFrame": {
+      "description": "(AF3) One `data:` line of GET /api/agent/sessions/:addr/stream. `id:` lines carry the resume cursor (Last-Event-ID); `event: ping` heartbeats are not data frames.",
+      "oneOf": [
+        { "$ref": "#/$defs/StreamReady" },
+        { "$ref": "#/$defs/StreamDelta" },
+        { "$ref": "#/$defs/StreamSay" },
+        { "$ref": "#/$defs/StreamHeard" },
+        { "$ref": "#/$defs/StreamStatus" },
+        { "$ref": "#/$defs/StreamConversation" },
+        { "$ref": "#/$defs/StreamReset" },
+        { "$ref": "#/$defs/StreamEnd" }
+      ]
+    },
+
+    "AnswerableTier": { "description": "(AF4) APP_ANSWERABLE_TIERS: the only tier an app answers (decision w6lfbfaq 1).", "enum": ["confirm"] },
+    "DecisionAnswerRequest": {
+      "description": "(AF4) POST /api/agent/decisions/:id/answer (decisions:answer): an option (and an optional note) or text for a Decision without options. No `via`.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": { "option": { "type": "string", "minLength": 1, "maxLength": 64 }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }
+    },
+    "AppDecisionAnswer": {
+      "description": "(AF4) Decision.answer when an app answered: answeredBy app, the app's party and (when it has one) its label.",
+      "type": "object",
+      "required": ["answeredBy", "app", "at"],
+      "properties": { "answeredBy": { "const": "app" }, "app": { "type": "string", "pattern": "^app:[0-9a-f]{16}$" }, "appLabel": { "type": "string" }, "option": { "type": "string" }, "text": { "type": "string" }, "at": { "$ref": "#/$defs/EpochMs" } }
+    }
+  }
+}