@vinaverse/server 0.0.0-stage → 0.1.0-alpha.2

package/dist/vinaverse-v1.d-BVc4uyUd.d.ts

@@ -0,0 +1,3460 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+interface paths {
+    "/v1/sessions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create an agent session for one subject
+         * @description A session belongs to a conversation when it names one (`conversation_key`, `conversation_id`, or both) or when its agent runs a guided flow; a flow session that names none starts a new conversation. `Session` then returns its `conversation_id`, and a conversation started without a key can later be resumed by that id. A conversation is scoped to the tenant, the environment, the `subject.id` and the `agent`; `subject.type` is not part of it, so a guest who signs in keeps the conversation.
+         *     **`business_setup`.** The `business_setup` capability is only for a business's own people: a `subject.type` of `professional`, `host` or `staff`. Asked for any other subject, it is `400 invalid_request` with the pointer `/tool_access/capabilities`.
+         *     **`booking_proposals`.** The `booking_proposals` capability is only for a `client`: not a guest, who has no account in the tenant's app to confirm with. Asked for any other subject, it is `400 invalid_request` with the pointer `/tool_access/capabilities`.
+         *     **The checks, in this order:** 1. `conversation_id` is given, and is unknown, erased, or belongs to another tenant, environment, `agent` or
+         *        `subject.id`: `404 not_found`.
+         *     2. Both are given, and the key names a different conversation, or none: `409 conversation_mismatch`. 3. The conversation expired: `410 conversation_expired`. With `conversation_key` alone, an expired
+         *        conversation instead lets a new one start under the key; the id never starts one silently.
+         *     4. The conversation is completed (its flow was accepted): `409 conversation_completed`. This holds by key too,
+         *        so a finished survey is never started twice.
+         *
+         *     **Resuming** is the same however the conversation is named. The new session continues the conversation, and `conversation_id` stays the same. The agent gets the answers recorded so far and a short summary, and re-emits the pending question card under its original `id`. A question card keeps its `id` across the sessions of a conversation, so an answer resent on a later session still names it. `client_event_id`s are deduplicated across all the sessions of the conversation. The older open session of the conversation is replaced (`session.closed replaced`, close `4409`). Each session still has its own short-lived client secret.
+         */
+        post: operations["createSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/suggestions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pick, rank and word a few explore suggestions from the candidates the tenant sends
+         * @description Synchronous, with a service key that has `sessions:write` (a key without scopes has every scope). Feature `suggestions`, for caps and switches: when it is off or capped, the answer is `feature_unavailable`, as everywhere else.
+         *     **Time.** The tenant waits at most 1.5 seconds. The runtime answers within 1.2 seconds, with what it has by then, or an empty list. A request whose caller disconnected before the answer is not charged and does not count toward the `suggestions` cap, so the tenant's ledger, which records the `usage` it receives, stays exact.
+         *     **The split.** The tenant supplies the facts: `candidates` from its own live data, each with a `ref`, a `kind`, a `title` and open `facts`. The agent picks between `min` and `max` of them, ranks them, and writes a short `title` and `why` for each. It may also turn one into a question for the agent (`action: ask`). - **Never an invented target.** `ref` is always one of the request's candidates, and `null` only for `ask`. - **Never a claim beyond the facts.** `why` uses only the facts sent. An unknown `facts` key is ignored. - **No filler.** With fewer than `min` good suggestions, the list is empty. `min` greater than `max` is
+         *       `400 invalid_request` with the pointer `/max`.
+         *     - **Language and length.** `title`, `why` and `question` are in `subject.locale`, falling back to the
+         *       tenant's default locale and then English. Their lengths are counted in Unicode code points; a check in a
+         *       language whose strings are UTF-16 (.NET, JavaScript) must count code points, not UTF-16 units.
+         *
+         *     **Candidates are untrusted data.** Candidate `title`s and `facts` often come from other people (a host's listing title, a professional's name). They enter the model as quoted data in a delimited block, never as instructions, and the platform floor applies: every `title`, `why` and `question` passes the leak check and the blocked-topic filter before it is returned.
+         *     **Tool mode.** Only when `candidates` is omitted and `tool_access` is given does the agent read the tenant's `read` tools for candidates. With `candidates` present, the tools are not read, and every `ref` is a candidate's. In tool mode: - `why` uses only the tool results; - a `ref` is `<kind>:<id>`, with the `id` exactly as the tenant's read tool returned it: `professional` from
+         *       `get_professional` and the search tools, `space` from `get_workspace`, `service` from the catalogue's
+         *       `service_type`, `class` from a tool that returns classes;
+         *     - the tenant validates a `ref` by fetching that object again before it shows the suggestion.
+         *     **The agent's guardrails apply.** The suggestions follow the `scope` and `blocked_topics` of the request's `agent` (default `customer_assistant`). An `agent` the tenant does not have is `400 invalid_request` with the pointer `/agent`. `business_setup` or `booking_proposals` in `tool_access` is refused (`400 invalid_request`, `/tool_access/capabilities`): suggestions never propose, and the subject is a `client` or a `guest`.
+         *     **Privacy and caching.** `personalized` says whether any suggestion used the subject's own history, from a `facts` key such as `booked_by_subject` or from the tools. It is always `false` for a `guest`. A personalised answer never crosses subjects: its cache key includes the tenant, environment and `subject.id`, and the rest of the key (place, filters, a cell size) is the tenant's choice. A response with `personalized: false` may also be cached across subjects. The decision records are kept for the tenant's `transcript_retention` (at most 30 days; with `none`, not after the answer), and are erased with the subject (`eraseSubject`).
+         *     **An `ask` suggestion** opens the agent with `question` already typed in the composer. It becomes the person's message only when they send it, and they may edit it first. No session field carries the suggestion.
+         */
+        post: operations["createSuggestions"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/conversations/{conversation_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The state of one conversation, with all its answers
+         * @description The same `ConversationState` the conversation webhooks carry, always complete: `answers` and `remarks` are never omitted here, and `sequence` is the same counter the webhooks carry. Use it when a webhook arrives with `answers_omitted: true`, or to check where a person is.
+         *     **Access.** A service key only, never a client secret, and only for the key's own tenant and environment. The key needs the `conversations:read` scope (a key without scopes has every scope); otherwise `403 forbidden`.
+         *     **How long the state can be read.** - While the conversation lives. - **72 hours after it ends without acceptance** (`expired`, including one whose last submission
+         *       `failed`): the final state, answers included, stays readable, so a backend that missed an omitted
+         *       webhook can still fetch the answers.
+         *     - **Under `transcript_retention: none`,** the state is deleted on acceptance, and the tenant already holds
+         *       the accepted submission. The read then answers `410` at once.
+         *
+         *     After that window the read answers `410 conversation_expired`, from a tombstone that keeps no answers (see `docs/conversation-state.md`). An unknown or erased conversation, or one of another tenant or environment, is `404 not_found`.
+         */
+        get: operations["getConversation"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getSession"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/revoke": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["revokeSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/client_secret": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * A fresh client secret for an open session
+         * @description A service key with the `sessions:write` scope gets a new connect secret for an open session, for an app that missed the connect window or connects from another device (whose connection then replaces the open one, with close code 4409). The previous secret no longer authenticates a new connection or an SSE turn. A socket already open stays open and keeps its session: refreshing never drops the person's live connection. To cut it off, revoke the session (`revokeSession`). An ended session is `409 session_closed`.
+         */
+        post: operations["refreshClientSecret"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/turns": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Run one turn and stream its events as SSE (alternative to the WebSocket) */
+        post: operations["createTurnSse"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/turns/{turn_id}/actions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Send a card action and stream the resulting turn as SSE */
+        post: operations["createCardActionSse"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/moderation/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["createModerationJob"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/moderation/jobs/{job_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getModerationJob"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/moderation/items/{item_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getModerationItem"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listMediaJobs"];
+        put?: never;
+        /**
+         * @description Queue a media job. `moderate` is required; `transcode`, `poster` and `captions` are optional (video only)
+         *     and write to the tenant's destination under `<prefix>/<job id>/`. Same tenant, same `media.sha256`, same
+         *     steps and same policy version within 30 days returns the earlier completed job with `200` and
+         *     `deduplicated: true`, not charged; `force: true` reprocesses. When the expected wait exceeds the tenant's
+         *     soft limit the job is accepted with `delayed: true` and a later `estimated_completion_at`; past the hard
+         *     limit the request is refused with `429` and `Retry-After`.
+         */
+        post: operations["createMediaJob"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/jobs/{job_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getMediaJob"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/jobs/{job_id}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Stops the job at the next step boundary (within seconds) and deletes outputs already written. Idempotent:
+         *     cancelling an ended job returns it unchanged.
+         */
+        post: operations["cancelMediaJob"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/profiles": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listMediaProfiles"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/screening/text": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["screenText"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/document-checks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["createDocumentCheck"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/document-checks/{check_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Fields are present only within 24 hours of completion; afterwards only flags remain. */
+        get: operations["getDocumentCheck"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["sendFeedback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/subjects/{subject_id}/erase": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Erases the subject's data: transcripts, screening texts, memory, indexes, the conversation state of its guided flows (recorded answers, remarks, transcript), and the explore suggestion decisions made for it, and revokes its open sessions. `subject.erased` follows.
+         *     **A subject Vinaverse holds nothing for** (never seen, or already erased) is `404` with `code: not_found` and `type: https://docs.vinaverse.com/problems/subject-not-found`; a client matches on the `type` ending in `/problems/subject-not-found`. Only that answer means nothing is held, and nothing needs erasing. Vinaverse keeps no record of erased subjects to tell the two apart. Any other `404` (a wrong base URL, say) is not that answer, and the caller retries.
+         */
+        post: operations["eraseSubject"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Contract §13.1. Each event must validate against its type's JSON Schema in the event catalogue (`contracts/events/beauty_marketplace@1/`); one invalid event rejects the call. */
+        post: operations["sendEvents"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/knowledge/documents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["sendKnowledgeDocument"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/catalog/{type}/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put: operations["putCatalogEntity"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface webhooks {
+    "media.job.queued": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description The job was accepted (also after a retry). */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["MediaJob"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "media.job.progress": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description At most one per 10 s per job, and only to an endpoint that lists this event by name; an endpoint that takes every event does not get it. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["MediaJobProgress"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "media.job.step.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description A step completed; `completed_step` names it. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["MediaJobStepCompleted"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "media.job.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Every step ended; `outputs` lists the files (none after a `never` verdict). */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["MediaJob"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "media.job.failed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description A step failed after its retries; `error` says why. Completed steps are kept for a retry. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["MediaJob"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "media.job.cancelled": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description The job was cancelled; outputs already written are deleted. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["MediaJob"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "moderation.item.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["ModerationItem"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "moderation.job.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["ModerationJobSummary"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "document_check.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["DocumentCheck"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "session.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: components["schemas"]["SessionStatus"];
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "subject.erased": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: {
+                            subject_id: components["schemas"]["SubjectId"];
+                            /** Format: date-time */
+                            erased_at: string;
+                            scopes: ("transcripts" | "screening_texts" | "memory" | "indexes" | "sessions" | "local_payload_removal" | "index_and_cache_deletion")[];
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "usage.threshold_reached": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: {
+                            feature: components["schemas"]["Feature"];
+                            /** @enum {integer} */
+                            percent: 50 | 80 | 100;
+                            period: string;
+                            used: components["schemas"]["MicroMoney"];
+                            cap: components["schemas"]["MicroMoney"];
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "conversation.updated": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description The state changed while the conversation goes on: an answer was recorded, a rejection changed the state (for example a refused submission re-opened a question), the pending question changed, or a new session resumed it. `data.status` is `in_progress`, or `failed` while a submission's outcome is unknown. Guided-flow conversations only, delivered only to an endpoint that lists this type by name (never to one that takes every type). A test delivery (`data.test: true`) carries no state: skip it. See `docs/conversation-state.md`. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        /** @constant */
+                        type?: "conversation.updated";
+                        data?: components["schemas"]["ConversationState"] & {
+                            /** @enum {unknown} */
+                            status?: "in_progress" | "failed";
+                            flow?: string;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "conversation.completed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description The flow was submitted and the tenant accepted it; `data.status` is `completed`. Guided-flow conversations only, delivered only to an endpoint that lists this type by name (never to one that takes every type). A test delivery (`data.test: true`) carries no state: skip it. See `docs/conversation-state.md`. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        /** @constant */
+                        type?: "conversation.completed";
+                        data?: components["schemas"]["ConversationState"] & {
+                            /** @enum {unknown} */
+                            status?: "completed";
+                            flow?: string;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "conversation.failed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description A submission is not known to be accepted (`flow.completed` with `failed`); `data.status` is `failed`. Guided-flow conversations only, delivered only to an endpoint that lists this type by name (never to one that takes every type). A test delivery (`data.test: true`) carries no state: skip it. See `docs/conversation-state.md`. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        /** @constant */
+                        type?: "conversation.failed";
+                        data?: components["schemas"]["ConversationState"] & {
+                            /** @enum {unknown} */
+                            status?: "failed";
+                            flow?: string;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "conversation.expired": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Retention or the tenant's `conversation_max_days` (`admin-v1.yaml`, at most 30) ended the conversation; `data` is its last state, with `status: expired`. `getConversation` still returns it for 72 hours. Guided-flow conversations only, delivered only to an endpoint that lists this type by name (never to one that takes every type). A test delivery (`data.test: true`) carries no state: skip it. See `docs/conversation-state.md`. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        /** @constant */
+                        type?: "conversation.expired";
+                        data?: components["schemas"]["ConversationState"] & {
+                            /** @enum {unknown} */
+                            status?: "expired";
+                            flow?: string;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "feature.state_changed": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["WebhookEnvelope"] & {
+                        data?: {
+                            feature: components["schemas"]["Feature"];
+                            /** @enum {string} */
+                            state: "enabled" | "disabled";
+                            /** @enum {string} */
+                            reason: "cap_reached" | "studio" | "incident" | "period_reset";
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Received */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        Problem: {
+            /** Format: uri */
+            type: string;
+            title: string;
+            status: number;
+            /** @enum {string} */
+            code: "invalid_request" | "unauthenticated" | "forbidden" | "feature_unavailable" | "not_found" | "idempotency_conflict" | "session_closed" | "payload_too_large" | "unprocessable_media" | "rate_limited" | "internal" | "unavailable" | "conversation_mismatch" | "conversation_expired" | "conversation_completed";
+            detail?: string;
+            request_id: string;
+            retryable: boolean;
+            /** @description field-level problems for invalid_request */
+            errors?: {
+                /** @description JSON Pointer into the request */
+                pointer: string;
+                message: string;
+            }[];
+        };
+        Money: {
+            /** @description minor units */
+            amount: number;
+            currency: string;
+        };
+        MicroMoney: {
+            /** @description millionths of the currency unit */
+            amount_micros: number;
+            currency: string;
+        };
+        SubjectId: string;
+        /** @enum {string} */
+        SubjectType: "client" | "professional" | "host" | "guest" | "staff";
+        Subject: {
+            id: components["schemas"]["SubjectId"];
+            type: components["schemas"]["SubjectType"];
+            /**
+             * @example en-US
+             * @example es-US
+             * @example pt-BR
+             */
+            locale?: string;
+            /** @example America/New_York */
+            timezone?: string;
+            approximate_location?: {
+                lat: number;
+                lng: number;
+                /** @enum {string} */
+                precision: "city" | "neighborhood";
+            };
+        };
+        /** @enum {string} */
+        Feature: "assistant" | "moderation_image" | "moderation_video" | "moderation_text" | "screening" | "document_check" | "insights" | "suggestions";
+        /**
+         * @description `business_setup`: grants the business's own read tools and its `propose` tools (`tool-provider-v1.yaml`, `x-effect: propose`), for the `business_setup` agent; never a write tool. Only a subject of type `professional`, `host` or `staff` may be granted it. `booking_proposals`: grants the tenant's `propose` tools for a client's bookings (a booking, a reschedule, a cancellation the client confirms in the tenant's app), for the customer agent; never a write tool. Only a subject of type `client` may be granted it (`docs/agents-guardrails-suggestions-writes.md` §3.4). These two are the only capabilities that carry `propose` tools: `create_proposal` and every tenant `propose` tool require one of them. `flows`: grants the guided-flow endpoints (`tool-provider-v1.yaml`, `/flows/*`). It names no flow and no record: the tenant limits the `tool_access` token itself to one flow and one record. `my_orders`: grants reading the customer's own kits and orders from a styling-kit retailer (`tool-provider-v1.yaml`, `list_my_kits`, `get_my_kit`, `list_my_orders`, `get_my_order`), read only. Like `my_bookings`, it is meant for a signed-in `client`, and the tenant answers for the token's customer only.
+         * @enum {string}
+         */
+        Capability: "search" | "availability" | "quotes" | "my_bookings" | "policies" | "handoff" | "flows" | "business_setup" | "booking_proposals" | "my_orders";
+        ToolAccess: {
+            token: string;
+            /** Format: date-time */
+            expires_at: string;
+            capabilities: components["schemas"]["Capability"][];
+        };
+        /** @description `candidates`, or `tool_access` alone (tool mode). With `candidates`, the tools are not read. */
+        SuggestionsRequest: {
+            /** @enum {string} */
+            surface: "explore";
+            /** @description a `client` or a `guest`; a guest has no history */
+            subject: components["schemas"]["Subject"] & {
+                /** @enum {unknown} */
+                type?: "client" | "guest";
+            };
+            /**
+             * @description whose guardrails apply
+             * @default customer_assistant
+             * @example customer_assistant
+             */
+            agent: string;
+            context?: {
+                place?: {
+                    /** @example Midtown, Atlanta */
+                    label?: string;
+                    lat: number;
+                    lng: number;
+                };
+                /**
+                 * Format: date-time
+                 * @description the person's local time, with its offset
+                 */
+                local_time?: string;
+                /** @description the filters the person has on, by name */
+                filters?: {
+                    [key: string]: string;
+                };
+            };
+            candidates?: components["schemas"]["SuggestionCandidate"][];
+            /**
+             * @description fewer good suggestions than this is an empty list
+             * @default 3
+             */
+            min: number;
+            /**
+             * @description at least `min`
+             * @default 5
+             */
+            max: number;
+            /** @description Optional. Without `candidates`, the agent reads the tenant's `read` tools with it (tool mode). */
+            tool_access?: components["schemas"]["ToolAccess"];
+        } | unknown | unknown;
+        SuggestionCandidate: {
+            /**
+             * @example pro:66f1a2
+             * @example search:service:silk press
+             */
+            ref: string;
+            /**
+             * @description what `ref` names
+             * @enum {string}
+             */
+            kind: "professional" | "space" | "class" | "service" | "search";
+            title: string;
+            /** @description Open: what the tenant knows about the candidate (price, rating, distance, next open time, whether the subject booked it before…). A key the agent does not know is ignored. `why` uses only these facts. */
+            facts?: {
+                [key: string]: unknown;
+            };
+        };
+        SuggestionsResponse: {
+            decision_id: string;
+            /** @description between `min` and `max`, or empty */
+            suggestions: components["schemas"]["Suggestion"][];
+            /** @description true when any suggestion used the subject's own history; such a response is cached only per tenant, environment and `subject.id`. Always false for a guest. */
+            personalized: boolean;
+            usage: components["schemas"]["SuggestionsUsage"];
+        };
+        Suggestion: {
+            /** @description one of the request's candidates (in tool mode, `<kind>:<id>` from a tool result); `null` only for `ask` */
+            ref: string | null;
+            /**
+             * @description `open`: open the candidate. `search`: run its search. `ask`: open the agent with `question` in the composer, unsent.
+             * @enum {string}
+             */
+            action: "open" | "search" | "ask";
+            /** @description in Unicode code points */
+            title: string;
+            /** @description a plain reason taken from the facts sent; in Unicode code points */
+            why: string;
+            /** @description `ask` only; in Unicode code points */
+            question?: string;
+        } & unknown;
+        SuggestionsUsage: {
+            /** @constant */
+            unit: "request";
+            quantity: number;
+            cost: components["schemas"]["MicroMoney"];
+        };
+        SessionCreate: {
+            /** @example customer_assistant */
+            agent: string;
+            subject: components["schemas"]["Subject"];
+            tool_access: components["schemas"]["ToolAccess"];
+            limits?: {
+                max_turns?: number;
+                max_duration_seconds?: number;
+            };
+            context?: {
+                [key: string]: string;
+            };
+            /**
+             * @description Optional. An opaque key the tenant chooses: printable ASCII, no spaces, at most 128 characters. It names a conversation within the tenant, the environment, the `subject.id` and the `agent`. A new session with the same key resumes that conversation; `createSession` describes resuming and its checks, the same whether a conversation is named by key or by `conversation_id`.
+             *     One session per conversation is open at a time. Creating a new one closes the older open session: its socket gets `session.closed` with reason `replaced` and close code `4409`, and the session ends as `revoked` (so in `SessionStatus` a replacement looks like a revoke). When two creations for the same conversation race, the later one wins. Conversation state lasts as long as the tenant's `transcript_retention`, counted from the conversation's creation, and never beyond the tenant's `conversation_max_days` (at most 30) from it, however often it is resumed. The key never reaches a model prompt, and logs keep only a hash of it.
+             */
+            conversation_key?: string;
+            /** @description Optional. Resumes the conversation with this id (`Session.conversation_id`, `ConversationState`), as an alternative to `conversation_key` or together with it; `createSession` describes resuming and the order of its checks. */
+            conversation_id?: components["schemas"]["ConversationId"];
+        };
+        ClientSecret: {
+            /** @description `vv_cs_` and base64url characters, so the secret is a valid WebSocket subprotocol token in `bearer.<secret>`. */
+            value: string;
+            /**
+             * Format: date-time
+             * @description The end of the connect window (120 s after issue): the secret must open a connection (over SSE: run its first turn) by then. Once used, it is bound to the session until the session ends or a new secret is issued (`refreshClientSecret`), so the app reconnects with the same secret (and sends it on every SSE turn) without asking for a new one.
+             */
+            expires_at: string;
+        };
+        Session: {
+            id: string;
+            /** @enum {string} */
+            status: "open";
+            agent: {
+                id: string;
+                version: string;
+                display_name: string;
+            };
+            client_secret: components["schemas"]["ClientSecret"];
+            /** Format: uri */
+            realtime_url: string;
+            /** Format: uri */
+            turns_url: string;
+            /**
+             * Format: date-time
+             * @description When the session ends: the earliest of the session's own `limits.max_duration_seconds` (when `createSession` sets it), the agent's and the environment's longest session, and `tool_access.expires_at`. A short-lived tool token shortens the session. On the WebSocket, `session.expiring` comes 60 s before, then `session.closed` with `expired`.
+             */
+            expires_at: string;
+            disclosure: string;
+            /** @description The conversation this session belongs to, the same for every session of it, however it was resumed (by `conversation_key` or `conversation_id`). Present whenever the session belongs to a conversation: when the request named one, and for every guided-flow session. It is absent only for a session with no conversation, and optional in the schema so clients built on earlier drafts keep working. */
+            conversation_id?: components["schemas"]["ConversationId"];
+        };
+        SessionStatus: {
+            id: string;
+            /** @enum {string} */
+            status: "open" | "closed" | "revoked" | "expired";
+            subject_id: components["schemas"]["SubjectId"];
+            agent_version?: string;
+            turns: number;
+            handoff_ticket_ids?: string[];
+            /**
+             * @description Why the session ended. `server_restart` is reserved and never appears here: it never ends a session (`docs/realtime-protocol.md` §2).
+             * @enum {string}
+             */
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left";
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            closed_at?: string;
+            usage?: components["schemas"]["Usage"];
+        };
+        TurnInput: {
+            client_event_id?: string;
+            text: string;
+        };
+        Usage: {
+            /** @enum {string} */
+            unit: "turn" | "image" | "video_second" | "text_item" | "screening_call" | "document_page";
+            quantity: number;
+            input_tokens?: number;
+            output_tokens?: number;
+            cost: components["schemas"]["MicroMoney"];
+        };
+        UsageReport: {
+            period: string;
+            features: {
+                feature: components["schemas"]["Feature"];
+                quantity: number;
+                cost: components["schemas"]["MicroMoney"];
+                /** @description null when the feature has no monthly cap */
+                cap: components["schemas"]["MicroMoney"] | null;
+                /** @enum {string} */
+                state: "enabled" | "disabled";
+            }[];
+        };
+        CardRef: {
+            /** @enum {string} */
+            type: "professional" | "workspace" | "service" | "booking" | "quote" | "policy" | "slot_list" | "ticket" | "metric_series" | "metric_table" | "gap_list" | "intent_cluster" | "memory_claim" | "knowledge_snippet";
+            id: string;
+        };
+        CardAction: {
+            /**
+             * @description `confirmed`, `declined`, `failed` and `expired` are reserved for proposal outcomes, never a card action
+             * @example open
+             * @example show_times
+             * @example show_more
+             * @example get_quote
+             * @example contact_support
+             */
+            action: string;
+            label: string;
+            deep_link?: string;
+        };
+        /**
+         * @description `ref` is present on every customer-agent card (professional … handoff); copilot cards (metric_chart … document) may omit it, since a metric, cluster or claim is not a tenant object. A `question` card (guided flows) carries `question`, has no `actions` (the person answers with `ui.answer`), uses `title` as a short label for the question, and its `source` names the tool call that fetched the flow's definition.
+         *     A `next_step` card is a step the person finishes on the tenant's own screen (payouts, a plan purchase, photos). It has a `title` (at most 80 code points), a `body` (at most 300) and exactly one action: `action: open`, with a `label` (at most 40) and a `deep_link`. It may omit `ref`, and its `source` names the tool call the step came from. - **Nothing is written.** Tapping the action opens `deep_link` in the tenant's app. The app sends no
+         *       `ui.action`, nor `createCardActionSse`, for it.
+         *     - **The link passes the deep-link rule** (`admin-v1.yaml`, `Connector.deep_link_prefixes`). It must be a
+         *       whole string value in the result of the tenant tool call that `source` names (`source.call_id`, the
+         *       tenant's `get_setup_state` for example), in the same session. A substring, or any other tool's result,
+         *       does not count, and the model never composes a link. It must start with a prefix the tenant registered
+         *       for the session's environment, compared code point for code point. And what follows the prefix must be
+         *       on an allowlist: path segments of `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `~` and `-`, each with a character
+         *       that is not `.`, then optionally a query of those characters, `=`, `&` and `%20`–`%7E` escapes other
+         *       than `%25`, `%2F`, `%3A` and `%5C`. No `%` in the path, no fragment, nothing else. Query values are
+         *       data: the app never navigates to one.
+         *     - **A card whose link fails is dropped.** The model is told the step could not be shown, so the agent
+         *       does not point to a card, and the connector is flagged in Studio (`Connector.health`).
+         *     - **The app also checks** the page the link names on its own side, and drops a link to a page it does not
+         *       know.
+         *     - **It is not restored.** A `next_step` card is in neither `pending_cards` nor `transcript`; after a
+         *       reconnect the agent shows the step again once it reads the tenant's state.
+         */
+        Card: {
+            id: string;
+            /**
+             * @description customer-agent kinds, then business-copilot kinds (Studio), then `question` (guided flows), then `proposal` (a change the person confirms or declines in the tenant's app), then `next_step` (a step the person finishes on the tenant's own screen)
+             * @enum {string}
+             */
+            kind: "professional" | "workspace" | "service" | "time_slots" | "booking" | "quote" | "policy" | "handoff" | "metric_chart" | "metric_table" | "gap_list" | "cluster" | "claim" | "document" | "question" | "proposal" | "next_step";
+            question?: components["schemas"]["Question"];
+            proposal?: components["schemas"]["Proposal"];
+            ref?: components["schemas"]["CardRef"];
+            title: string;
+            subtitle?: string;
+            /** Format: uri */
+            image_url?: string;
+            rating?: {
+                value_ppm: number;
+                count: number;
+            };
+            price_from?: components["schemas"]["Money"];
+            price?: components["schemas"]["Money"];
+            /** Format: date-time */
+            starts_at?: string;
+            /** @description A `time_slots` card's open times, as the tenant's tool returned them: each with its `start` and `end` (its length), and the card's `subtitle` names the professional or space when the tool result does. Each has an `id` (v1-draft.17): the app may draw the slots as choices, and a tap sends `ui.action` `select_slot` with that `id` and the card's `source.call_id` (`SlotSelection`), over SSE through `createCardActionSse`. A slot without an `id` (an earlier runtime) is drawn read-only. */
+            slots?: {
+                /** @description Opaque, unique within the card, the same for the same slot of the same tool result. Never parse it. */
+                id?: string;
+                /** Format: date-time */
+                start: string;
+                /** Format: date-time */
+                end: string;
+            }[];
+            status?: string;
+            /** @description policy excerpt, handoff text, or what a `next_step` is for */
+            body?: string;
+            badges?: string[];
+            actions: components["schemas"]["CardAction"][];
+            source: {
+                tool: string;
+                call_id: string;
+                /** @description optional; the tool arguments that produced this card (shown by Studio as the source query) */
+                arguments?: Record<string, unknown>;
+            };
+            metric?: components["schemas"]["MetricRef"];
+            /** @enum {string} */
+            grain?: "day" | "week";
+            period?: {
+                /** Format: date */
+                from: string;
+                /** Format: date */
+                to: string;
+            };
+            series?: {
+                key: string;
+                label: string;
+                points: {
+                    /** Format: date */
+                    t: string;
+                    /** @description null when suppressed by the k-anonymity floor */
+                    value: number | null;
+                    suppressed?: boolean;
+                }[];
+            }[];
+            dimensions?: {
+                key: string;
+                label: string;
+            }[];
+            columns?: {
+                key: string;
+                label: string;
+                unit: components["schemas"]["ValueUnit"];
+            }[];
+            rows?: {
+                dims: {
+                    [key: string]: string;
+                };
+                values: {
+                    [key: string]: number | null;
+                };
+            }[];
+            /** @description gap_list entries */
+            items?: {
+                service: string;
+                area: string;
+                demand: number;
+                supply: number;
+                zero_result_share_ppm: number;
+                trend_ppm?: number | null;
+            }[];
+            label?: string;
+            count?: number;
+            share_ppm?: number;
+            /** @enum {string} */
+            outcome?: "zero_results" | "withheld" | "handoff" | "mixed";
+            /** @description redacted */
+            examples?: string[];
+            claim?: {
+                id: string;
+                statement: string;
+                /** @enum {string} */
+                status: "candidate" | "confirmed" | "rejected";
+                evidence: {
+                    label: string;
+                    call_id: string;
+                }[];
+                /** Format: date-time */
+                proposed_at: string;
+                decided_by?: string | null;
+                /** Format: date-time */
+                decided_at?: string | null;
+            };
+            document?: {
+                title: string;
+                section?: string;
+                url?: string;
+                version?: string;
+            };
+            snippet?: string;
+            /** Format: date-time */
+            updated_at?: string;
+        } & (unknown & unknown & unknown);
+        /** @enum {string} */
+        ValueUnit: "count" | "ppm" | "micros_usd" | "ms";
+        MetricRef: {
+            name: string;
+            label: string;
+            unit: components["schemas"]["ValueUnit"];
+            definition: string;
+            k_floor?: number;
+        };
+        /** @description Links a span of the reply text to the card or tool call it came from. Offsets are in Unicode code points (not bytes, not UTF-16 units), start inclusive, end exclusive. */
+        Citation: {
+            start: number;
+            end: number;
+            card_id?: string;
+            call_id?: string;
+        };
+        /** @description The tenant's stable ref for a question (or a `rate_each` row), echoed in answers. */
+        QuestionId: string;
+        /** @enum {string} */
+        QuestionKind: "single_choice" | "multi_choice" | "image_choice" | "yes_no" | "list_choice" | "rate_each" | "short_text" | "long_text" | "date" | "number" | "scale" | "photo";
+        QuestionOption: {
+            /** @description The tenant's stable ref for this choice. Answers carry it, never the label. */
+            value: string;
+            label: string;
+            /**
+             * Format: uri
+             * @description on the tenant's CDN; required for `image_choice`
+             */
+            image_url?: string;
+            description?: string;
+        };
+        /**
+         * @description One question of a guided flow, as the app renders it natively. The tenant's definition supplies every field except `prompt` (the agent's phrasing), `progress`, `state`, `answer` and `row_answers`. Option `value`s are the tenant's refs: the server rejects any value that is not on the card. For `rate_each`, each row is its own question with its own `question_id`, and `options` are the columns. The newest `open` question card is the one to answer. An `answered` card is drawn locked with its `answer`. A `superseded` card was replaced by a newer one and takes no answer.
+         *     A `rate_each` card has no single `answer`. Its answered rows are in `row_answers`, on any card where at least one row is answered, in `pending_cards` too. Each answered row is drawn locked, and the others stay open. The card is `answered` only when every row has an answer. A row of a question that is not `required` may be answered `skipped`.
+         */
+        Question: {
+            question_id: components["schemas"]["QuestionId"];
+            kind: components["schemas"]["QuestionKind"];
+            /** @description the question as the agent phrased it */
+            prompt: string;
+            /** @description optional, from the definition */
+            help?: string;
+            /** @description when false the person may skip it (`answer.skipped`) */
+            required: boolean;
+            /** @description The choices, and for `rate_each` the columns. Choice kinds and `rate_each` need at least 2 and at most 12; `yes_no` needs exactly 2; `list_choice` allows up to 500. */
+            options?: components["schemas"]["QuestionOption"][];
+            /** @description fewest selections (`multi_choice`, `image_choice`) */
+            min?: number;
+            /** @description most selections (`multi_choice`, `image_choice`) */
+            max?: number;
+            /**
+             * @description offers a free-text "Other", answered with `other_text`
+             * @default false
+             */
+            allows_other: boolean;
+            /**
+             * @description With `allows_other` only: the longest "Other" text (`other_text`), in Unicode code points; 500 when absent. A longer `ui.answer` is rejected with `invalid_value` at any length, past 500 too (`AnswerInput`), and its `message` names the limit, so an app that predates this field can say why. Other text the agent takes from a typed message is held to it too: the runtime asks for a shorter one and never submits a longer one. The app enforces it as the person types.
+             * @default 500
+             */
+            other_max_length: number;
+            /** @description an exclusive choice, answered as `values` with its `value` alone */
+            none_of_the_above?: {
+                value: string;
+                label: string;
+            };
+            /** @description `rate_each` only: each row is rated on the `options` scale and answered on its own `question_id` */
+            rows?: {
+                question_id: components["schemas"]["QuestionId"];
+                label: string;
+                /** Format: uri */
+                image_url?: string;
+            }[];
+            /** @description `short_text` (max_length at most 200) and `long_text` (at most 2000) */
+            text?: {
+                max_length: number;
+            };
+            number?: {
+                min: number;
+                max: number;
+                step: number;
+                /**
+                 * @example cm
+                 * @example kg
+                 * @example years
+                 */
+                unit?: string;
+            };
+            /** @description optional bounds, inclusive */
+            date?: {
+                /** Format: date */
+                min?: string;
+                /** Format: date */
+                max?: string;
+            };
+            scale?: {
+                min: number;
+                max: number;
+                step: number;
+                min_label: string;
+                max_label: string;
+            };
+            /** @description The app uploads the photo to the tenant (never through Vinaverse) and answers with the `upload_ref` the tenant issued. */
+            photo?: {
+                max_bytes: number;
+                mime_types: string[];
+            };
+            /** @description `total` is an estimate when the flow branches */
+            progress?: {
+                step: number;
+                total: number;
+            };
+            /** @enum {string} */
+            state: "open" | "answered" | "superseded";
+            /** @description the recorded answer, when `state` is `answered`; never on `rate_each` (see `row_answers`) */
+            answer?: components["schemas"]["QuestionAnswer"];
+            /** @description `rate_each` only: the rows answered so far, each on its row's `question_id`, and each row at most once. A row is answered with one column (`values` holding one value, never `other_text`) or, when the question is not `required`, `skipped`. */
+            row_answers?: components["schemas"]["RowAnswer"][];
+        } & (unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown);
+        /** @description A `rate_each` row's answer: one column (`values` holding one value, never `other_text`) or `skipped`. */
+        RowAnswer: {
+            question_id: components["schemas"]["QuestionId"];
+            answer: components["schemas"]["QuestionAnswer"] & ({
+                values: unknown;
+            } | unknown) & unknown;
+        };
+        ConversationId: string;
+        /**
+         * @description Where one conversation stands, for the tenant backend that created its sessions. It is the `data` of the conversation webhooks and the response of `getConversation`. The backend keeps a durable copy, so it still has the answers after Vinaverse's state ends.
+         *     **Personal data.** It never carries the transcript or the `conversation_key`, and nothing about the person beyond the opaque `subject_id` except what the person gave the flow. The answers and remarks (`text`, `other_text`, `upload_ref`, the verbatim remarks) are personal data the person gave the tenant's flow; handle them as such. The object is closed: no other field is ever added to it without a contract change.
+         *     **`sequence`** is one counter per conversation, shared by the webhooks and `getConversation`. It goes up by one on every change to any field, `session_id` included, and on nothing else; `last_activity_at` is the time of that change. Each step produces exactly one webhook, so a gap means a delivery still to come. Two states with the same `sequence` are identical. A terminal event (`completed`, `expired`) always takes a new, higher `sequence`.
+         *     **Receiving.** Delivery is at least once and in no guaranteed order. Keep, per `conversation_id`, the state with the highest `sequence`, and ignore an equal or lower one. A state with `answers_omitted: true` updates every other field, and never replaces `answers` and `remarks` already held. Merge it, then read the full state with `getConversation`.
+         *     **Size.** A webhook body is at most 64 KB: 65,536 bytes of the UTF-8 request body, envelope included. When the state would make it larger, the webhook leaves out `answers` and `remarks` and sets `answers_omitted: true`.
+         */
+        ConversationState: {
+            conversation_id: components["schemas"]["ConversationId"];
+            subject_id: components["schemas"]["SubjectId"];
+            /** @description the agent profile the conversation runs under */
+            agent: string;
+            /** @description the guided flow's name; null outside a guided flow */
+            flow: string | null;
+            /** @description the flow definition version the answers follow; null outside a guided flow */
+            version: number | null;
+            /**
+             * @description `completed`: submitted and accepted. `failed`: the last submission is not known to be accepted (`flow.completed failed`); a later retry, in this session or a later one, can still complete it. `expired`: retention or `conversation_max_days` ended it.
+             * @enum {string}
+             */
+            status: "in_progress" | "completed" | "failed" | "expired";
+            sequence: number;
+            progress: {
+                /** @description questions answered, a `rate_each` row counting as one */
+                answered: number;
+                /** @description an estimate when the flow branches; null outside a guided flow */
+                total_estimate: number | null;
+            };
+            /** @description the open question, or null when none is open (finished, between questions, or no flow) */
+            pending_question_id: components["schemas"]["QuestionId"] | null;
+            /** @description The answers recorded so far, in the order they were given. */
+            answers?: components["schemas"]["ConversationAnswer"][];
+            /** @description By `question_id`, extra things the person volunteered; never answers. */
+            remarks?: {
+                [key: string]: string;
+            };
+            /** @description true when a webhook left out `answers` and `remarks` to stay within 64 KB; never in `getConversation` */
+            answers_omitted?: boolean;
+            /**
+             * Format: date-time
+             * @description the time of the change that produced this `sequence`
+             */
+            last_activity_at: string;
+            /** @description the latest session of the conversation */
+            session_id: string;
+        } & unknown;
+        /** @description One recorded answer: `{ question_id, answer }`, or for `rate_each` `{ question_id, row_answers }`. */
+        ConversationAnswer: {
+            question_id: components["schemas"]["QuestionId"];
+            answer: components["schemas"]["QuestionAnswer"];
+        } | {
+            question_id: components["schemas"]["QuestionId"];
+            row_answers: components["schemas"]["RowAnswer"][];
+        };
+        /** @description Exactly one of: `values` (option values, validated against the card; one for single-choice kinds), `other_text` (the free-text "Other", when `allows_other`), `text`, `number`, `date` (YYYY-MM-DD), `upload_ref` (`photo`) or `skipped` (only when the question is not `required`). The one combination is `values` with `other_text`, for a `single_choice` or `multi_choice` question that `allows_other`: the person picked options and also typed an "Other". On any other question it is refused (`not_allowed`). */
+        QuestionAnswer: {
+            values: string[];
+        } | {
+            other_text: string;
+        } | {
+            values: string[];
+            other_text: string;
+        } | {
+            text: string;
+        } | {
+            number: number;
+        } | {
+            /** Format: date */
+            date: string;
+        } | {
+            upload_ref: string;
+        } | {
+            /** @constant */
+            skipped: true;
+        };
+        /** @description What `ui.answer` carries: a `QuestionAnswer`, or the same with an "Other" longer than 500. An `other_text` longer than the question's `other_max_length` is answered `ui.answer.rejected` with `invalid_value`, at any length, and its `message` names the limit, so a person always learns it. It is never recorded, so recorded and submitted answers keep the `QuestionAnswer` bound. */
+        AnswerInput: components["schemas"]["QuestionAnswer"] | {
+            other_text: string;
+        } | {
+            values: string[];
+            other_text: string;
+        };
+        /**
+         * @description A message, oldest first: `{ role: assistant | person | staff, text, at }` (`staff`: a reply from a person from the business during a takeover, text only, never a name; v1-draft.15 widened the enum, so a client must tolerate a role it does not know), or an answered question card as `{ role: card, card, at }` (its `question.state` is `answered`, with its `answer`, or for `rate_each` its `row_answers`).
+         *     A `person` message is the person's own text as the runtime recorded it, card-like digits masked; a card tap, an answer or a proposal's outcome is not a message, and neither is an input the runtime never recorded (one refused with `input.rejected`, held at the turn limit, or a guardrail's refusal and its reply): the app keeps its own copy of those. An `assistant` message with `interrupted: true` (v1-draft.17) is a reply that stopped before it finished: its turn ended with `turn.failed` after it had streamed (a takeover, `input.cancel`, `output_blocked`, an outage), and the text is what was streamed. Draw it as cut off. A client that does not know the field draws it as any reply.
+         *     **Identity (v1-draft.17).** A message carries `id`, the identifier the live events gave it, so an app reconciles the transcript with what it drew instead of drawing it again: an `assistant` message's `turn_id` (`message.delta`, `message.completed`), a `person` message's `client_event_id` (`input.text`; absent when the app sent none), a `staff` message's `message_id` (`message.staff`). Unique per role within a conversation. A message of a turn also carries `turn_id`, the person's text and the agent's reply alike, so the cards the turn drew stay anchored after its text; a message sent during a takeover has none.
+         */
+        TranscriptItem: {
+            /** @enum {string} */
+            role: "assistant" | "person" | "staff";
+            text: string;
+            /** Format: date-time */
+            at: string;
+            /** @description `assistant` only, present only when true: the reply stopped before it finished */
+            interrupted?: boolean;
+            /** @description v1-draft.17: the live event's identifier for this message (`turn_id`, `client_event_id` or `message_id`, by role); absent on a `person` message sent without a `client_event_id` */
+            id?: string;
+            /** @description v1-draft.17; the turn the message belongs to, when it belongs to one */
+            turn_id?: string;
+        } | {
+            /** @constant */
+            role: "card";
+            card: components["schemas"]["Card"] & {
+                /** @constant */
+                kind: "question";
+                question: {
+                    /** @constant */
+                    state: "answered";
+                };
+            };
+            /** Format: date-time */
+            at: string;
+        };
+        /** @description A time slot the person picked on a `time_slots` card (v1-draft.17, `docs/realtime-protocol.md` §6): the slot's `id`, and the `call_id` of the tool call the card came from (the card's `source.call_id`), so the runtime checks the pick against the evidence it holds for that call. Both are copied from the card; never built by the app. */
+        SlotSelection: {
+            id: string;
+            call_id: string;
+        };
+        /**
+         * @description A change the agent proposed through a `propose` tool. The tenant holds it as pending; nothing has changed yet, and Vinaverse never applies it. The app shows `title`, `summary` and each field's `before` and `after`, with its own Confirm and Decline buttons (`confirm_mode: tenant_app`; the card has no `actions`). - **Confirm or decline** happens in the tenant's app, against the tenant's backend, with the person's own
+         *       token, before `expires_at`. The tenant applies the change on confirm.
+         *     - **Then** the app sends `ui.action` with the card's `turn_id` and `card_id`, a `client_event_id`, and the
+         *       outcome as `action`. The runtime gives that to the model as an event, never as a message from the person,
+         *       and the agent carries on from it.
+         *       - `confirmed`: the tenant's backend applied the change;
+         *       - `declined`: the person declined it;
+         *       - `failed`: the person confirmed but the tenant did not apply it (it refused the change, or the proposal
+         *         had expired);
+         *       - `expired`: the tenant says `expires_at` passed with no answer.
+         *     - **The tenant is the source of truth, and only an outcome the app reports is final.** At `expires_at` the
+         *       runtime tells the model, provisionally, that the proposal was not confirmed, so the model never waits on it.
+         *       This counts for nothing. A `confirmed`, `declined` or `failed` the app reports later is accepted, wins,
+         *       and is fed to the model as a correction.
+         *     - **The first app-reported outcome per card is final.** A repeat of that same outcome changes nothing. A
+         *       second, conflicting outcome, or an outcome on a card that is not a `proposal`, is answered with `error`
+         *       (`code: proposal_outcome_rejected`, with the `card_id` and `client_event_id`), and nothing reaches the
+         *       model.
+         *     - **`status`** is the tenant's state when the card was drawn. A card restored after a reconnect
+         *       (`session.ready.pending_cards`) still waits for its outcome.
+         *     - **Only a `pending` proposal is actionable.** The app draws Confirm and Decline only for
+         *       `proposal.status: pending`. A `propose` result that is not `pending` (a reused key that met an expired,
+         *       declined, confirmed or superseded proposal) is never drawn as an actionable card. The runtime advances the
+         *       key's attempt counter and calls once more with the new key, or, if that one is not `pending` either, gives
+         *       the `status` to the model as the outcome.
+         *     - **`edit_deep_link`** opens the tenant's own screen for the change, to edit it there. It is held to the
+         *       deep-link rule (`admin-v1.yaml`, `Connector.deep_link_prefixes`), the same check as a `next_step` link.
+         *       The runtime removes an `edit_deep_link` that fails, and the card is still sent. With no prefix registered,
+         *       nothing passes.
+         *
+         *     - **A booking proposal** (topic `booking`, `booking_reschedule` or `booking_cancellation`) carries the fields a
+         *       client must see under fixed keys (`BookingFields`): what is booked and with whom, when, and the price; for a
+         *       reschedule, the booking (unchanged) and its time before and after; for a cancellation, the booking and its
+         *       time (both unchanged), and any fee or refund. It expires no later than the booking starts, and a
+         *       reschedule no later than the earlier of its current and its new start
+         *       (`docs/agents-guardrails-suggestions-writes.md` §3.4).
+         *
+         *     Each field `key` appears once. `expires_at` is at most 7 days after the proposal was created. A field whose `before` equals its `after` does not change: show its value once.
+         */
+        Proposal: {
+            /** @description the tenant's proposal id */
+            id: string;
+            /**
+             * @description The tenant's current state of the proposal. Only `pending` can still be confirmed. The tenant is the source of truth, and `confirmed` means the change was applied.
+             * @enum {string}
+             */
+            status: "pending" | "confirmed" | "declined" | "expired" | "superseded";
+            /**
+             * @example business_address
+             * @example opening_hours
+             * @example services
+             * @example booking
+             * @example booking_reschedule
+             * @example booking_cancellation
+             */
+            topic: string;
+            title: string;
+            summary: string;
+            fields: components["schemas"]["ProposalField"][];
+            /**
+             * Format: date-time
+             * @description after it the tenant declines the proposal on its own
+             */
+            expires_at: string;
+            /** @description a link into the tenant's app; removed by the runtime when it fails the deep-link rule (see `edit_deep_link` above) */
+            edit_deep_link?: string;
+            /** @enum {string} */
+            confirm_mode: "tenant_app";
+        } & (unknown & unknown & unknown & unknown);
+        /** @description The fields of a booking proposal (topic `booking`, `booking_reschedule` or `booking_cancellation`), whose keys are fixed so every app draws a booking card the same way (`docs/agents-guardrails-suggestions-writes.md` §3.4): `service`, `professional`, `space`, `booking`, `location`, `note` and `reason` are `text`, `services` is a `list`, `time` is a `time_range`, `place` an `address`, and `price`, `deposit`, `fee`, `cancellation_fee` and `refund` are `money_cents`. */
+        BookingFields: (unknown & unknown & unknown & unknown & unknown)[];
+        /** @description `before` is the current value, absent or null when the proposal creates it, and equal to `after` when the field does not change but says what the change is about (the booking a reschedule moves); `before` and `after` take the shape `type` names. */
+        ProposalField: {
+            key: string;
+            label: string;
+            /**
+             * @description `money_cents` is an amount in the currency's minor units (ISO 4217: cents for USD, yen for JPY, fils for BHD), never negative. `time_range` is one dated range whose `end` is after its `start`. `weekly_hours` is recurring opening hours, by weekday, in the business's time zone.
+             * @enum {string}
+             */
+            type: "text" | "money_cents" | "time_range" | "address" | "list" | "weekly_hours";
+            before?: unknown;
+            after: unknown;
+        } & (unknown & unknown & unknown & unknown & unknown & unknown);
+        ProposalMoney: {
+            /** @description in the currency's minor units (ISO 4217) */
+            amount: number;
+            currency: string;
+        };
+        /** @description Recurring opening hours. A day absent from `entries` is closed; a day may have several entries (a lunch break), which never overlap. `end` may be `24:00` (closing at midnight), and `00:00`–`24:00` is open all day. An `end` earlier than `start` runs past midnight into the next day (a bar's `22:00`–`02:00`), and that spill counts against the next day's entries: `fri 22:00`–`02:00` and `sat 01:00`–`09:00` overlap. `end` never equals `start`. */
+        WeeklyHours: {
+            /**
+             * @description an IANA time zone name
+             * @example America/New_York
+             */
+            time_zone: string;
+            entries: {
+                /** @enum {string} */
+                day: "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+                start: string;
+                end: string;
+            }[];
+        };
+        TimeRange: {
+            /** Format: date-time */
+            start: string;
+            /** Format: date-time */
+            end: string;
+        };
+        PostalAddress: {
+            line1: string;
+            line2?: string;
+            city: string;
+            region?: string;
+            postal_code?: string;
+            /** @description ISO 3166-1 alpha-2 */
+            country: string;
+        };
+        TextList: string[];
+        /** @description What the app sends. **The turn limit narrows the typed message's deduplication rule below**, which lists `limit_reached` among the refusals a resend gets again: that holds in the same session only. A text or an answer refused with `input.rejected` `limit_reached` is not recorded. On a new session of the conversation it is checked as new: it runs, as a turn of that session, or, if its turn had already run, gets `duplicate` (`input.rejected` for a text, `ui.answer.recorded` with `duplicate: true` for an answer) (`docs/realtime-protocol.md` §2, a session out of turns). */
+        ClientEvent: {
+            /** @constant */
+            type: "session.auth";
+            client_secret: string;
+        } | {
+            /** @constant */
+            type: "input.text";
+            client_event_id?: string;
+            text: string;
+        } | {
+            /** @constant */
+            type: "input.cancel";
+            turn_id: string;
+        } | {
+            /** @constant */
+            type: "playback.fenced";
+            turn_id: string;
+            heard_chars: number;
+        } | ({
+            /** @constant */
+            type: "ui.action";
+            client_event_id?: string;
+            turn_id: string;
+            card_id: string;
+            /**
+             * @description On a `proposal` card: `confirmed`, `declined`, `failed` or `expired` (`Proposal`), sent after the outcome in the tenant's app. It tells the session; it changes nothing.
+             *     On a `time_slots` card: `select_slot` (v1-draft.17), with `slot`, the person's pick. It is checked against this session's evidence: the card must be one this session drew from the tool call `slot.call_id` names, and the slot one that call returned; anything else gets `error` (`invalid_action`) and reaches nothing. An accepted pick starts a turn: `turn.started` echoes the `client_event_id`, and it is deduplicated as `input.text` is (a resend whose turn ran gets `input.rejected` `duplicate`). It is a tap on a card: refused with `input.rejected` `turn_in_progress` during a turn or a takeover, never held at the turn limit, and never sent on another session.
+             */
+            action: string;
+            slot?: components["schemas"]["SlotSelection"];
+        } & (unknown & unknown)) | {
+            /** @constant */
+            type: "ui.answer";
+            /** @description the action id, unique per answer */
+            client_event_id: string;
+            card_id: string;
+            question_id: components["schemas"]["QuestionId"];
+            answer: components["schemas"]["AnswerInput"];
+        } | {
+            /** @constant */
+            type: "ping";
+        };
+        /** @description What the server sends on the WebSocket, and as SSE events of a turn. `session.expiring` is WebSocket only: sent once per connection, 60 s before `Session.expires_at`, never for the client secret; `session.closed` with `expired` follows at the end (`docs/realtime-protocol.md` §1). What the app does after each `session.closed` reason is in §2 of the same document; `server_restart` is reserved, nothing sends it today, and it never ends a session. */
+        ServerEvent: {
+            /** @constant */
+            type: "session.ready";
+            session: components["schemas"]["SessionStatus"];
+            limits: {
+                max_turns?: number;
+                turns_left?: number;
+                /** Format: date-time */
+                expires_at?: string;
+            };
+            disclosure: string;
+            resumed: boolean;
+            /**
+             * @description Optional. The last messages of the conversation, oldest first, text only, so the app can redraw it after a kill or a reconnect. Older context is not sent.
+             *     A guided flow's resumed `session.ready` always carries it. Any other session's (a chat; v1-draft.17) carries it when `resumed` is true and there is something to restore, whether the app reconnects to the same session or the backend created a new session of the conversation: - the conversation's messages across its sessions (the session's own when it has no conversation):
+             *       the person's texts, the agent's replies (`interrupted` when cut off) and the staff replies of a
+             *       takeover; the last 20, and none older than 7 days;
+             *     - only what the tenant's `transcript_retention` still keeps: under `none`, only the open session's
+             *       own messages; never anything of a subject erased since (`eraseSubject`).
+             *
+             *     When present, it is the server's view: redraw the messages from it, including any the app missed while disconnected. When absent, the server holds nothing to restore: keep what the app holds. It is sent only on the connection the client secret opened, so it reaches no one the session does not.
+             */
+            transcript?: components["schemas"]["TranscriptItem"][];
+            /**
+             * @description Optional. The open question card, if there is one (at most one); render it unlocked. For `rate_each`, its `row_answers` say which rows are already answered: draw those locked. Also the `proposal` cards still awaiting an outcome from the app, so the app can report `confirmed`, `declined`, `failed` or `expired` with its `turn_id` and `card_id` after a reconnect. A proposal card awaits until the app reports an outcome, or until 7 days after its `expires_at`. When more than 10 await, the 10 newest are restored. An older one still takes an outcome if the app has its ids.
+             *     Every item carries `turn_id`, the turn that drew the card. `ui.action` needs it with the card's `id`, so a proposal card restored after a reconnect or an app kill can still be reported.
+             */
+            pending_cards?: (components["schemas"]["Card"] & {
+                /** @description the turn that drew the card; `ui.action` names it with the card's `id` */
+                turn_id: string;
+            } & ({
+                /** @constant */
+                kind: "question";
+                question: {
+                    /** @constant */
+                    state: "open";
+                };
+            } | {
+                /** @constant */
+                kind: "proposal";
+                proposal: {
+                    /** @constant */
+                    status: "pending";
+                };
+            }))[];
+        } | {
+            /** @constant */
+            type: "turn.started";
+            turn_id: string;
+            client_event_id?: string;
+        } | {
+            /** @constant */
+            type: "tool.status";
+            turn_id: string;
+            label: string;
+            /** @enum {string} */
+            state: "running" | "done" | "failed";
+        } | {
+            /** @constant */
+            type: "message.delta";
+            turn_id: string;
+            /** @description One or more whole sentences. Each sentence passes the leak check, and the tenant's blocked-topic filter, before it is sent. */
+            text: string;
+        } | {
+            /** @constant */
+            type: "ui.cards";
+            turn_id: string;
+            cards: components["schemas"]["Card"][];
+        } | {
+            /** @constant */
+            type: "message.completed";
+            turn_id: string;
+            text: string;
+            /** @description optional; spans of `text` with their source card or tool call */
+            citations?: components["schemas"]["Citation"][];
+        } | {
+            /** @constant */
+            type: "handoff.created";
+            turn_id: string;
+            ticket: {
+                id: string;
+                /** @description the tenant's phrase completing "they'll reply {expected_response}" (`within one business day by email`), never a sentence of its own */
+                expected_response: string;
+            };
+        } | {
+            /** @constant */
+            type: "turn.completed";
+            turn_id: string;
+            usage: components["schemas"]["Usage"];
+        } | {
+            /** @constant */
+            type: "turn.failed";
+            turn_id: string;
+            /**
+             * @description Whatever the code, the sentences the turn already streamed (`message.delta`) stand: they are the reply recorded, marked interrupted (`TranscriptItem.interrupted`, v1-draft.17), so the app keeps them, drawn as cut off, and adds `message` after them. Includes: - `output_blocked`: a sentence of the reply would have leaked (the prompt, keys, other subjects' data),
+             *       so it was never sent, and the turn ended (`retryable: false`). A sentence that only touches a
+             *       blocked topic is dropped instead, and the turn goes on.
+             *     - `cancelled`: the turn was stopped: by `input.cancel`, because the person left, or because a person
+             *       from the business took the conversation over (`takeover.started` follows, and nothing of the turn
+             *       comes after it).
+             *     - `tool_result_invalid`: a `propose` tool returned something that is not a `Proposal`. No card is
+             *       shown, and the connector is flagged.
+             */
+            code: string;
+            message: string;
+            retryable: boolean;
+        } | {
+            /** @constant */
+            type: "input.rejected";
+            client_event_id?: string;
+            /**
+             * @description `duplicate`: the same `client_event_id` was already handled in this conversation, and its turn ran; do not resend it. `turn_in_progress`: send the input again, with the same `client_event_id`, after `turn.completed`. `screen_unavailable`: the chat-safety screen could not check the input, so nothing ran and the model never saw it, and nothing was recorded or remembered. Resend the same input with the same `client_event_id` after a short backoff (for example 2 s, doubling, three or four tries); if it is still refused, show it as not sent, with `message`, and let the person send it again. It replaces, for this case, the retryable `error` with `code: screen_unavailable` that earlier runtimes sent; an older server still sends that `error`. An app that does not know the code treats it as any unknown `input.rejected` code: it does not resend, and shows `message`. `guardrail`: the message was refused before the model saw it, by one of the agent's guardrails (a blocked topic, or outside its scope under `strict`) or by the platform floor (an instruction override or persona hijack); `message` is the tenant's `refusal_message` (or a platform default in the subject's locale): show it as the agent's reply, and do not resend.
+             * @enum {string}
+             */
+            code: "screened" | "too_long" | "turn_in_progress" | "limit_reached" | "duplicate" | "guardrail" | "screen_unavailable";
+            message: string;
+        } | {
+            /** @constant */
+            type: "session.expiring";
+            seconds_left: number;
+        } | {
+            /** @constant */
+            type: "session.closed";
+            /**
+             * @description `replaced`: a newer session of the same conversation was created (close code `4409`)
+             * @enum {string}
+             */
+            reason: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "replaced";
+        } | {
+            /** @constant */
+            type: "ui.answer.recorded";
+            card_id: string;
+            question_id: components["schemas"]["QuestionId"];
+            client_event_id: string;
+            duplicate: boolean;
+        } | {
+            /** @constant */
+            type: "ui.answer.rejected";
+            card_id: string;
+            question_id: components["schemas"]["QuestionId"];
+            client_event_id: string;
+            /** @enum {string} */
+            code: "invalid_value" | "too_many" | "too_few" | "card_superseded" | "not_allowed" | "client_event_id_reused";
+            message?: string;
+        } | ({
+            /** @constant */
+            type: "flow.completed";
+            /** @example intake-survey */
+            flow: string;
+            /** @enum {string} */
+            result: "ok" | "refused" | "failed";
+            /**
+             * @description For `refused`, the tenant's refusal code, as it sent it: `REQUIRED_MISSING`, `UNKNOWN_VALUE`, `TOO_LONG`, `VERSION_NOT_ACCEPTED`, `TOO_MANY`, `TOO_FEW`, `BAD_DATE`, `UPLOAD_NOT_FOUND`, `OUT_OF_RANGE`, or a newer one. Show it as it is; the agent has already asked again.
+             * @example REQUIRED_MISSING
+             * @example unavailable
+             */
+            code?: string;
+            /** @description `failed` only */
+            retryable?: boolean;
+        } & (unknown & unknown & unknown)) | {
+            /** @constant */
+            type: "error";
+            code: string;
+            message: string;
+            retryable: boolean;
+            /** @description the card the refused event named (`proposal_outcome_rejected`) */
+            card_id?: string;
+            /** @description the refused event's `client_event_id` */
+            client_event_id?: string;
+        } | {
+            /** @constant */
+            type: "pong";
+        } | {
+            /** @constant */
+            type: "takeover.started";
+            /** Format: date-time */
+            at: string;
+            /** @description the replier's role as the person sees it, never a name (e.g. "the team") */
+            by?: string;
+        } | {
+            /** @constant */
+            type: "takeover.ended";
+            /** Format: date-time */
+            at: string;
+        } | {
+            /** @constant */
+            type: "message.staff";
+            message_id: string;
+            text: string;
+            /** Format: date-time */
+            at: string;
+        } | {
+            /** @constant */
+            type: "input.received";
+            client_event_id: string;
+        };
+        /**
+         * @description The tenant's binding lists its surfaces; unknown surfaces are rejected.
+         * @example listing_photo
+         * @example gallery_photo
+         * @example profile_photo
+         * @example service_photo
+         * @example class_photo
+         * @example listing_video
+         * @example bio
+         * @example listing_text
+         * @example business_name
+         * @example service_name
+         * @example chat_message
+         * @example review
+         */
+        Surface: string;
+        Media: {
+            /** Format: uri */
+            url: string;
+            /** Format: date-time */
+            url_expires_at?: string;
+            /** @enum {string} */
+            content_type: "image/jpeg" | "image/png" | "image/webp" | "image/heic" | "video/mp4" | "video/quicktime" | "video/webm";
+            bytes?: number;
+            sha256?: string;
+        };
+        ModerationItemInput: {
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            /** @enum {string} */
+            kind: "image" | "video" | "text";
+            subject: components["schemas"]["Subject"];
+            media?: components["schemas"]["Media"];
+            text?: string;
+            context?: {
+                [key: string]: string;
+            };
+            options?: {
+                /** @default false */
+                assess_quality: boolean;
+            };
+        } & ({
+            /** @enum {unknown} */
+            kind?: "image" | "video";
+        } | {
+            /** @constant */
+            kind?: "text";
+        });
+        ModerationJobCreate: {
+            /** @default default */
+            policy: string;
+            items: components["schemas"]["ModerationItemInput"][];
+        };
+        Reason: {
+            /**
+             * @example contact.off_platform
+             * @example sexual.nudity
+             * @example quality.not_a_space
+             */
+            code: string;
+            /** @enum {string} */
+            severity: "info" | "review" | "hold" | "never";
+            evidence?: {
+                /** @enum {string} */
+                kind?: "visual" | "text_in_image" | "text" | "speech" | "metadata";
+                /** @description redacted excerpt, at most 120 chars */
+                excerpt?: string;
+                /** @description normalized box, integers in ppm of width/height */
+                region?: {
+                    x?: number;
+                    y?: number;
+                    w?: number;
+                    h?: number;
+                } | null;
+                timestamp_ms?: number | null;
+            };
+            explanation?: string;
+        };
+        /** @description A vv-decision/0 decision record as exposed to tenants. */
+        Decision: {
+            id: string;
+            /** @enum {string} */
+            domain: "image_safety" | "video_safety" | "text_safety" | "chat_safety" | "document_check";
+            domain_version: string;
+            domain_hash?: string;
+            /** @enum {string} */
+            class: "clean" | "review" | "hold" | "never";
+            abstained: boolean;
+            reasons: components["schemas"]["Reason"][];
+            distribution_ppm?: {
+                [key: string]: number;
+            } | null;
+            /** @enum {string} */
+            calibration: "absent" | "calibrated";
+            threshold_policy?: string;
+            policy_version: string;
+            model: {
+                id: string;
+                provider: string;
+                revision?: string;
+            };
+            prompt_version?: string;
+            audit: {
+                sampled: boolean;
+                probability_ppm: number;
+            };
+        };
+        Quality: {
+            /** @enum {string} */
+            rating: "good" | "fair" | "poor";
+            issues: ("dark" | "blurry" | "low_resolution" | "tilted" | "cluttered" | "watermark" | "heavy_filter" | "not_a_space" | "duplicate_in_listing")[];
+            is_space: boolean;
+            note?: string;
+        };
+        VideoFindings: {
+            duration_ms: number;
+            frames_analyzed: number;
+            transcript_language?: string | null;
+            segments: {
+                start_ms: number;
+                end_ms: number;
+                reasons: components["schemas"]["Reason"][];
+                /** @description timestamps of the frames supporting visual reasons; the tenant seeks its own video */
+                frame_timestamps_ms: number[];
+                note?: string;
+            }[];
+            summary_for_reviewer: string;
+        };
+        ModerationItem: {
+            id: string;
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            /** @enum {string} */
+            kind: "image" | "video" | "text";
+            /** @enum {string} */
+            status: "queued" | "processing" | "completed" | "failed";
+            decision?: components["schemas"]["Decision"];
+            quality?: components["schemas"]["Quality"];
+            video?: components["schemas"]["VideoFindings"];
+            error?: components["schemas"]["Problem"];
+            /** Format: date-time */
+            completed_at?: string;
+            processing_ms?: number;
+            usage?: components["schemas"]["Usage"];
+        };
+        ModerationJob: {
+            id: string;
+            /** @enum {string} */
+            status: "queued" | "processing" | "completed" | "partially_failed";
+            items: components["schemas"]["ModerationItem"][];
+            estimated_completion_seconds?: {
+                [key: string]: number;
+            };
+        };
+        ModerationJobSummary: {
+            id: string;
+            /** @enum {string} */
+            status: "completed" | "partially_failed";
+            counts: {
+                clean?: number;
+                review?: number;
+                hold?: number;
+                never?: number;
+                failed?: number;
+            };
+        };
+        /** @description A destination configured in Studio (an S3-compatible bucket and a write-only key). */
+        DestinationId: string;
+        /** @description `poster` and `captions` write where `transcode` writes unless they name a destination. Outside the mock environment a step that writes needs a destination. An image takes only `moderate`. */
+        MediaSteps: {
+            moderate: {
+                /** @default default */
+                policy: string;
+            };
+            transcode?: {
+                /** @enum {string} */
+                profile: "tour_hls_v1";
+                destination?: components["schemas"]["DestinationId"];
+            };
+            /** @description One JPEG plus a 6-second silent preview MP4. `auto` picks a sharp, well-lit frame. */
+            poster?: {
+                /** @default auto */
+                at: "auto" | number;
+                destination?: components["schemas"]["DestinationId"];
+            };
+            /** @description WebVTT from the transcript the moderation step makes. */
+            captions?: {
+                languages: string[];
+                destination?: components["schemas"]["DestinationId"];
+            };
+        };
+        MediaJobCreate: {
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            subject: components["schemas"]["Subject"];
+            media: components["schemas"]["Media"];
+            steps: components["schemas"]["MediaSteps"];
+            /**
+             * @description Orders work inside the tenant's own turn; never ahead of another tenant's fair share.
+             * @default normal
+             * @enum {string}
+             */
+            priority: "high" | "normal" | "low";
+            context?: {
+                [key: string]: string;
+            };
+            /**
+             * @description Reprocess even when a dedupe match exists.
+             * @default false
+             */
+            force: boolean;
+        };
+        /**
+         * @description `waiting`: for another step; `skipped`: not run because a step it needs failed or the verdict was `never`.
+         * @enum {string}
+         */
+        MediaStepStatus: "waiting" | "queued" | "processing" | "completed" | "failed" | "skipped" | "cancelled";
+        MediaJobStep: {
+            status: components["schemas"]["MediaStepStatus"];
+            progress_percent: number;
+            /** @enum {string} */
+            stage?: "fetching" | "analyzing" | "transcoding" | "uploading";
+            /** @description `moderate`, when completed */
+            decision?: components["schemas"]["Decision"];
+            video?: components["schemas"]["VideoFindings"];
+            error?: components["schemas"]["Problem"];
+            /** Format: date-time */
+            completed_at?: string;
+        };
+        MediaOutput: {
+            /** @enum {string} */
+            step: "transcode" | "poster" | "captions";
+            /**
+             * @example hls_master
+             * @example hls_720p
+             * @example mp4_fallback
+             * @example poster
+             * @example preview
+             * @example captions
+             */
+            role?: string;
+            /** @description Object key in the tenant's bucket, under `<prefix>/<job id>/` */
+            key: string;
+            destination_id?: components["schemas"]["DestinationId"];
+            content_type: string;
+            bytes: number;
+            sha256: string;
+            duration_ms?: number;
+            width?: number;
+            height?: number;
+            language?: string;
+        };
+        MediaJob: {
+            id: string;
+            ref: string;
+            surface: components["schemas"]["Surface"];
+            /** @enum {string} */
+            kind: "image" | "video";
+            subject: {
+                id: components["schemas"]["SubjectId"];
+                type: components["schemas"]["SubjectType"];
+            };
+            /** @enum {string} */
+            status: "queued" | "processing" | "completed" | "failed" | "cancelled";
+            /** @enum {string} */
+            stage: "waiting" | "fetching" | "analyzing" | "transcoding" | "uploading" | "done";
+            progress_percent: number;
+            /** @enum {string} */
+            priority: "high" | "normal" | "low";
+            /** @description While queued, the job's place among this tenant's waiting work in its first lane. */
+            queue_position: number | null;
+            /**
+             * Format: date-time
+             * @description From the current queue and measured step durations; null once the job has ended.
+             */
+            estimated_completion_at: string | null;
+            /** @description One entry per requested step. */
+            steps: {
+                moderate?: components["schemas"]["MediaJobStep"];
+                transcode?: components["schemas"]["MediaJobStep"];
+                poster?: components["schemas"]["MediaJobStep"];
+                captions?: components["schemas"]["MediaJobStep"];
+            };
+            /** @description Set when the job completes (empty after a `never` verdict); null before. */
+            outputs: components["schemas"]["MediaOutput"][] | null;
+            error?: components["schemas"]["Problem"];
+            /** @description 1, plus one per retry from Studio's dead letters */
+            attempts: number;
+            context: {
+                [key: string]: string;
+            };
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            completed_at?: string;
+        };
+        MediaJobCreated: components["schemas"]["MediaJob"] & {
+            /** @description `202` only: the expected wait is past the tenant's soft limit. */
+            delayed?: boolean;
+            /** @description `200` only: the earlier job with the same content, steps and policy version. */
+            deduplicated?: boolean;
+        };
+        MediaJobProgress: {
+            id: string;
+            ref: string;
+            /** @enum {string} */
+            status: "processing";
+            /** @enum {string} */
+            stage: "fetching" | "analyzing" | "transcoding" | "uploading";
+            progress_percent: number;
+            /** Format: date-time */
+            estimated_completion_at: string | null;
+        };
+        MediaJobStepCompleted: components["schemas"]["MediaJob"] & {
+            /** @enum {string} */
+            completed_step: "moderate" | "transcode" | "poster" | "captions";
+        };
+        MediaProfile: {
+            /** @example tour_hls_v1 */
+            id: string;
+            description: string;
+            /** @enum {string} */
+            container: "hls";
+            segment_seconds?: number;
+            video_codec?: string;
+            audio_codec?: string;
+            renditions: {
+                name: string;
+                height: number;
+                video_kbps?: number;
+                audio_kbps?: number;
+            }[];
+            fallback?: {
+                container?: string;
+                height?: number;
+                faststart?: boolean;
+            };
+        };
+        ScreeningRequest: {
+            /** @default default */
+            policy: string;
+            surface: components["schemas"]["Surface"];
+            subject: components["schemas"]["Subject"];
+            text: string;
+            context?: {
+                conversation_ref?: string;
+                booking_exists?: boolean;
+                previous_messages?: {
+                    /** @enum {string} */
+                    author: "self" | "other";
+                    text: string;
+                }[];
+            };
+        };
+        ScreeningResponse: {
+            decision: components["schemas"]["Decision"];
+            /** @enum {string} */
+            action: "allow" | "nudge" | "hold" | "block";
+            nudge?: {
+                /** @enum {string} */
+                audience: "author" | "recipient" | "both";
+                text: string;
+            };
+        };
+        FeedbackRecord: {
+            decision_id?: string;
+            turn_id?: string;
+            /** @enum {string} */
+            outcome: "approved" | "rejected" | "edited" | "escalated" | "user_appealed" | "appeal_upheld" | "appeal_denied" | "thumbs_up" | "thumbs_down";
+            /** @enum {string} */
+            final_class?: "clean" | "review" | "hold" | "never";
+            reason_codes?: string[];
+            reviewer?: {
+                /** @enum {string} */
+                role?: "admin" | "moderator" | "support" | "end_user";
+                ref?: string;
+            };
+            /** Format: date-time */
+            decided_at: string;
+            note?: string;
+        } & (unknown | unknown);
+        FeedbackBatch: {
+            records: components["schemas"]["FeedbackRecord"][];
+        };
+        WebhookEnvelope: {
+            /** @description evt_…; deduplicate on it */
+            id: string;
+            /** @enum {string} */
+            type: "moderation.item.completed" | "moderation.job.completed" | "document_check.completed" | "session.completed" | "subject.erased" | "usage.threshold_reached" | "feature.state_changed" | "media.job.queued" | "media.job.progress" | "media.job.step.completed" | "media.job.completed" | "media.job.failed" | "media.job.cancelled" | "conversation.updated" | "conversation.completed" | "conversation.failed" | "conversation.expired";
+            /** Format: date-time */
+            created_at: string;
+            /** @enum {string} */
+            environment: "mock" | "development" | "production";
+            data: Record<string, unknown>;
+        };
+        /** @enum {string} */
+        DocumentType: "driver_license" | "state_id" | "business_license" | "cosmetology_license" | "insurance_card" | "insurance_certificate";
+        DocumentCheckCreate: {
+            ref: string;
+            document_type: components["schemas"]["DocumentType"];
+            subject: components["schemas"]["Subject"];
+            pages: {
+                /** @enum {string} */
+                side: "front" | "back" | "page";
+                media: {
+                    /** Format: uri */
+                    url: string;
+                    /** Format: date-time */
+                    url_expires_at?: string;
+                    /** @enum {string} */
+                    content_type: "image/jpeg" | "image/png" | "image/webp" | "image/heic" | "application/pdf";
+                    bytes?: number;
+                    sha256?: string;
+                };
+            }[];
+            expected?: {
+                full_name?: string | null;
+                business_name?: string | null;
+                region?: string | null;
+            };
+        };
+        DocumentFlag: {
+            /** @enum {string} */
+            code: "expired" | "expires_soon" | "name_mismatch" | "business_name_mismatch" | "region_mismatch" | "wrong_document_type" | "unreadable" | "incomplete" | "photo_of_screen" | "possible_edit" | "barcode_text_mismatch";
+            /** @enum {string} */
+            severity: "info" | "review";
+            detail?: string;
+            /** @description for *_mismatch: true when normalisation found them equivalent */
+            matched?: boolean;
+            /** @enum {string} */
+            signal_strength?: "weak" | "moderate" | "strong";
+        };
+        DocumentCheck: {
+            id: string;
+            ref: string;
+            /** @enum {string} */
+            status: "queued" | "processing" | "completed" | "failed";
+            document_type_detected?: string | null;
+            /** @description null after 24 hours; the date of birth is never returned */
+            fields?: {
+                full_name?: string | null;
+                document_number?: string | null;
+                issuer?: string | null;
+                region?: string | null;
+                license_class?: string | null;
+                /** Format: date */
+                issued_on?: string | null;
+                /** Format: date */
+                expires_on?: string | null;
+                date_of_birth_present?: boolean | null;
+                business_name?: string | null;
+                insured_name?: string | null;
+                policy_number?: string | null;
+                carrier?: string | null;
+                /** Format: date */
+                coverage_end?: string | null;
+            } | null;
+            field_sources?: {
+                [key: string]: "barcode" | "text_recognition" | "visual";
+            } | null;
+            flags?: components["schemas"]["DocumentFlag"][];
+            decision?: components["schemas"]["Decision"];
+            model?: {
+                id?: string;
+                provider?: string;
+            };
+            error?: components["schemas"]["Problem"];
+            /** Format: date-time */
+            completed_at?: string;
+            /** Format: date-time */
+            fields_expire_at?: string;
+            processing_ms?: number;
+        };
+        /** @description Common fields; the per-type fields and their strictness come from the event catalogue's JSON Schemas (contract §13.2). */
+        Event: {
+            event_id: string;
+            /** @enum {string} */
+            type: "search.performed" | "listing.viewed" | "booking.requested" | "booking.confirmed" | "booking.completed" | "booking.no_show" | "booking.cancelled" | "signup.completed" | "listing.submitted" | "listing.approved" | "listing.rejected" | "lead.created" | "lead.contacted" | "lead.converted" | "review.posted";
+            /** Format: date-time */
+            occurred_at: string;
+            subject_id: components["schemas"]["SubjectId"];
+            subject_type: components["schemas"]["SubjectType"];
+        } & {
+            [key: string]: unknown;
+        };
+    };
+    responses: {
+        /** @description Problem details (RFC 9457) */
+        Problem: {
+            headers: {
+                "Vinaverse-Request-Id": components["headers"]["RequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/problem+json": components["schemas"]["Problem"];
+            };
+        };
+        /** @description Too many requests */
+        RateLimited: {
+            headers: {
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                "application/problem+json": components["schemas"]["Problem"];
+            };
+        };
+    };
+    parameters: {
+        IdempotencyKey: string;
+        MediaJobId: string;
+        ConversationId: components["schemas"]["ConversationId"];
+        SessionId: string;
+    };
+    requestBodies: never;
+    headers: {
+        /** @description Vinaverse-Request-Id */
+        RequestId: string;
+    };
+    pathItems: never;
+}
+interface operations {
+    createSession: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SessionCreate"];
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Session"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    createSuggestions: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SuggestionsRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestionsResponse"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    getConversation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationState"] & unknown;
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+        };
+    };
+    getSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionStatus"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    revokeSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Revoked (idempotent) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionStatus"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    refreshClientSecret: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ClientSecret"];
+                };
+            };
+            409: components["responses"]["Problem"];
+        };
+    };
+    createTurnSse: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TurnInput"];
+            };
+        };
+        responses: {
+            /** @description `text/event-stream`. Each event's `event:` is a ServerEvent `type`; `data:` is the ServerEvent JSON. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": string;
+                };
+            };
+            401: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    createCardActionSse: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+                turn_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    card_id: string;
+                    action: string;
+                    /** @description as on the WebSocket `ui.action`; required for a proposal outcome and for `select_slot` (the server refuses either without it) */
+                    client_event_id?: string;
+                    /** @description `select_slot` only (v1-draft.17): the slot picked, as on the WebSocket `ui.action` */
+                    slot?: components["schemas"]["SlotSelection"];
+                };
+            };
+        };
+        responses: {
+            /** @description `text/event-stream` as for createTurnSse */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": string;
+                };
+            };
+        };
+    };
+    createModerationJob: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ModerationJobCreate"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ModerationJob"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            413: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getModerationJob: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                job_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ModerationJob"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    getModerationItem: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                item_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ModerationItem"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    listMediaJobs: {
+        parameters: {
+            query?: {
+                ref?: string;
+                status?: "queued" | "processing" | "completed" | "failed" | "cancelled";
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Newest first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["MediaJob"][];
+                        next_cursor: string | null;
+                    };
+                };
+            };
+        };
+    };
+    createMediaJob: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MediaJobCreate"];
+            };
+        };
+        responses: {
+            /** @description The same content was processed with the same steps and policy in the last 30 days. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJobCreated"];
+                };
+            };
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJobCreated"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+            413: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getMediaJob: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                job_id: components["parameters"]["MediaJobId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJob"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    cancelMediaJob: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                job_id: components["parameters"]["MediaJobId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The job, `cancelled` (or as it ended). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJob"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    listMediaProfiles: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The transcoding profiles, named and versioned. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["MediaProfile"][];
+                    };
+                };
+            };
+        };
+    };
+    screenText: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ScreeningRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ScreeningResponse"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    createDocumentCheck: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DocumentCheckCreate"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        id: string;
+                        /** @enum {string} */
+                        status: "queued";
+                        estimated_completion_seconds?: number;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getDocumentCheck: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                check_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DocumentCheck"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    sendFeedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedbackBatch"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        accepted: number;
+                        rejected: {
+                            index: number;
+                            code: string;
+                            detail?: string;
+                        }[];
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+        };
+    };
+    eraseSubject: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path: {
+                subject_id: components["schemas"]["SubjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Accepted; `subject.erased` follows */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        subject_id: components["schemas"]["SubjectId"];
+                        /** @enum {string} */
+                        status: "accepted" | "completed";
+                        sessions_revoked: number;
+                        /** Format: date-time */
+                        deadline: string;
+                    };
+                };
+            };
+            /** @description Nothing held for the subject (never seen, or already erased); the problem's `type` ends in `/problems/subject-not-found` */
+            404: {
+                headers: {
+                    "Vinaverse-Request-Id": components["headers"]["RequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["Problem"] & {
+                        /** @constant */
+                        code?: "not_found";
+                        type?: unknown;
+                    };
+                };
+            };
+        };
+    };
+    sendEvents: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    events: components["schemas"]["Event"][];
+                };
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        accepted: number;
+                        duplicates: number;
+                        batch_id: string;
+                        batch_cid: string;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    sendKnowledgeDocument: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    doc_id: string;
+                    version: string;
+                    title: string;
+                    /** @description Markdown */
+                    body: string;
+                    /** @enum {string} */
+                    audience: "public" | "staff";
+                    /** @default en */
+                    language?: string;
+                    /** Format: uri */
+                    url?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Same version and body already stored (no change) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Stored */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        doc_id: string;
+                        version: string;
+                        audience: string;
+                        artifact_cid: string;
+                        chunks: number;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+        };
+    };
+    putCatalogEntity: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                type: "professional" | "workspace" | "service_type" | "area";
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    name?: string;
+                    display_name?: string;
+                    title?: string;
+                    service_type_ids?: string[];
+                    area?: {
+                        city?: string;
+                        neighborhood?: string;
+                    };
+                    /** @default true */
+                    active?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Stored or unchanged */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        type: string;
+                        id: string;
+                        changed: boolean;
+                        snapshot_cid: string | null;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+        };
+    };
+    getUsage: {
+        parameters: {
+            query?: {
+                period?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UsageReport"];
+                };
+            };
+        };
+    };
+}
+
+export type { components as c, operations as o, paths as p, webhooks as w };