@vinaverse/client 0.0.0-stage → 0.1.0-alpha.10

package/dist/session-CPz4pcPu.d.cts

@@ -0,0 +1,3651 @@
+/**
+ * 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`, and (v1-draft.20) the mode and business scope it started with; `subject.type` itself 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`.
+         *     **Audience** (v1-draft.20). An agent talks only to the subject types of its template (admin-v1 `AgentProfile.audience`): the customer agent to a `client` or `guest`, a business agent to a `professional`, `host` or `staff`, a guided flow to anyone its tenant names. Any other `subject.type` is `400 invalid_request` with the pointer `/subject/type`. The tenant's backend sets the type by the side of its app the person is on, never by the account's roles: a professional booking for themselves is a `client`.
+         *     **Mode and business scope** (v1-draft.20). `experience_mode` is the agent's side: `customer` for the customer agent, `business` for a business agent. Left out, it follows the agent's template; given, it must match it (`400 invalid_request`, `/experience_mode`). `business_scope_id` names the business the person acts for (a professional's business, a host's place): only with `business` (`400`, `/business_scope_id`), and the tenant's backend derives it from its own records, never from the app. A conversation is bound, when it starts, to the subject, the agent, the mode and the business scope. The mode stands for the side of the app, so a guest who signs in as a client keeps their conversation, while a professional never resumes a customer conversation (the audience rule keeps each side's types apart). Resuming with any of them different is `404 not_found` (step 1 below), never a switch: a person acting for business A never resumes business B's conversation.
+         *     **The checks, in this order:** 1. `conversation_id` is given, and is unknown, erased, or belongs to another tenant, environment, `agent` or
+         *        `subject.id`, or (v1-draft.20) was started with another `experience_mode` or `business_scope_id`: `404
+         *        not_found`. A `conversation_key` names a conversation within the same binding,
+         *        so the same key under another binding names another conversation.
+         *     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": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * A person's past conversations with one agent, newest activity first
+         * @description v1-draft.21 (VIN-246): the conversations a history screen lists, for one subject and one agent, on one side of the app (`experience_mode`, and for a business `business_scope_id`, as the conversation was bound when it started). Newest activity first; ties by `id`.
+         *     **Access.** A service key only, never a client secret: the app asks the tenant's backend, which checks the person and calls this. The key needs `conversations:read` (a key without scopes has every scope) and sees its own tenant and environment only.
+         *     **What is listed.** Only what the tenant's `transcript_retention` still keeps: a conversation past it, a deleted one (`deleteConversation`) or an erased subject's is never listed, nor one where nothing was said (a session opened and left). A subject Vinaverse holds nothing for gets an empty page, the same as one with no conversations, so the answer never says whether a subject exists.
+         *     **The title** is deterministic and never the person's words: from the conversation's last search intent (`title_source: intent`, for example "Haircut · Los Angeles", in the subject's locale), else the date it started (`title_source: date`). There is no preview of the messages.
+         *     **Paging.** `next_cursor` is opaque and signed. It is bound to the filters, the key's tenant and environment, and expires after 24 hours: a cursor changed, used with other filters or expired is `400 invalid_request` at `/cursor`, and the caller starts again without it. An outage is `503 unavailable` (retryable), never an empty page: the app does not take it as "no conversations".
+         */
+        get: operations["listConversations"];
+        put?: never;
+        post?: never;
+        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 one of a person's conversations, everywhere
+         * @description v1-draft.21 (VIN-246): the person deletes a conversation from their history, through the tenant's backend. A service key with `conversations:write`, for its own tenant and environment; `subject_id` must be the conversation's subject.
+         *     **What it does, before it answers.** - Ends the conversation's open sessions: their sockets get `session.closed` with `reason: deleted` and
+         *       close with `4403` (a client that does not know `deleted` reads it as `revoked`). Their status ends as
+         *       `deleted`.
+         *     - Blanks every copy of the conversation's messages, cards, screening texts and state (and the guided flow's
+         *       answers), across both sides of the app, and leaves no title or count behind.
+         *     - Fences late writes: a turn still running, a webhook retry or a worker job that finishes after the delete
+         *       records nothing for it (a deletion barrier, kept as long as the longest session could run).
+         *     - Frees its `conversation_key`: a session with the same key afterwards starts a new conversation.
+         *     **Answers.** `200` with the number of sessions revoked. An unknown id, another tenant's, environment's or subject's, or one already deleted or erased: `404 not_found`, the same answer for each, so it never says whether the conversation exists. Deleting is not erasing the subject (`eraseSubject`): the person's other conversations and memory stay.
+         */
+        delete: operations["deleteConversation"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/conversations/{conversation_id}/messages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * One past conversation, as one ordered timeline of messages and cards
+         * @description v1-draft.21 (VIN-246): what a history screen draws when the person opens a past conversation. A service key with `conversations:read`, for its own tenant and environment; `subject_id` must be the conversation's subject.
+         *     **The timeline.** One list of messages and the cards their turns drew, in the order they happened, each with an `id` that is stable and unique within the conversation. The first page is the newest; within a page, oldest first; `next_cursor` pages toward older items. A message carries `event_id`, the identifier its live event gave it (as `TranscriptItem.id`: an `assistant` message's `turn_id`, a `person` message's `client_event_id`, a `staff` message's `message_id`), so an app merges what it drew live, or a resumed `session.ready.transcript`, into the fetched history by `role` and `event_id` instead of replacing either. An input the runtime never recorded is not in it, as in the transcript.
+         *     **Cards from history are read-only.** An app draws their actions disabled: a past slot, price or availability is not checked again, so a tap would act on stale data. The person asks again in the conversation, and a fresh turn draws fresh cards.
+         *     **What is kept.** Only what the tenant's `transcript_retention` still keeps; a conversation past it is `410 conversation_expired`. An unknown id, another tenant's, environment's or subject's, or a deleted or erased one: `404 not_found`, the same answer for each. A cursor changed, used for another conversation or expired (24 hours) is `400 invalid_request` at `/cursor`. An outage is `503 unavailable`, never an empty timeline.
+         */
+        get: operations["listConversationMessages"];
+        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`. With an optional `Idempotency-Key` (declared in v1-draft.22), a retry within 24 hours answers the secret first issued for that key instead of a newer one.
+         */
+        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)
+         * @description Browsers and WebViews (v1-draft.18): the preflight (`OPTIONS`) is answered for the tenant's client origins of the session's environment only (admin-v1 `ClientOrigins.effective`), with `Access-Control-Allow-Origin` the request's origin (never `*`), `Vary: Origin`, `Access-Control-Allow-Methods: POST`, `Access-Control-Allow-Headers: Authorization, Content-Type` and `Access-Control-Max-Age: 600`; no credentials mode is needed (the client secret is a header). Any other origin, or a session that does not exist, gets no CORS headers. A request whose `Origin` is not one of them is refused with `403` `forbidden` and runs nothing; a request with no `Origin` (a native app, a server) is not checked.
+         */
+        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
+         * @description Browsers and WebViews (v1-draft.18), as for `createTurnSse`: the preflight (`OPTIONS`) is answered for the tenant's client origins of the session's environment only (admin-v1 `ClientOrigins.effective`), with `Access-Control-Allow-Origin` the request's origin (never `*`), `Vary: Origin`, `Access-Control-Allow-Methods: POST`, `Access-Control-Allow-Headers: Authorization, Content-Type` and `Access-Control-Max-Age: 600`; no credentials mode is needed (the client secret is a header). Any other origin, or a session that does not exist, gets no CORS headers. A request whose `Origin` is not one of them is refused with `403` `forbidden` and runs nothing; a request with no `Origin` (a native app, a server) is not checked.
+         */
+        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/avatars/{avatar_file}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * An agent's avatar image (v1-draft.19), as `Session.agent.avatar_url` names it
+         * @description Public: no credential, since an app draws it in an image view. Only an avatar that passed the screen is served, and only while it is an agent's current or previous avatar of the last 30 days; anything else is `404`. The bytes never change under a name (`Cache-Control: public, max-age=31536000, immutable`), and the response is `image/webp` with `X-Content-Type-Options: nosniff` and a sandboxing `Content-Security-Policy`.
+         */
+        get: operations["getAgentAvatarImage"];
+        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 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"];
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            screen_context?: components["schemas"]["ScreenContext"];
+        };
+        /**
+         * @description v1-draft.20, optional on `createSession`: the side of the tenant's app the person is on. `customer` for the customer agent (a `client` or `guest`), `business` for a business agent (a `professional`, `host` or `staff`). Left out, it follows the agent's template; `createSession` describes the binding.
+         * @enum {string}
+         */
+        ExperienceMode: "customer" | "business";
+        /** @description v1-draft.20, optional, with `experience_mode: business` only: the business the person acts for, as the tenant's backend knows it (a professional's business, a host's place). Opaque to Vinaverse; it binds the conversation, so a person acting for two businesses keeps two conversations. It never reaches a model prompt. */
+        BusinessScopeId: string;
+        /** @description v1-draft.20, optional on `createSession`: where the person is in the tenant's app when the session opens, as the tenant's backend vouches for it (it checked that the person may see the entity). It grants nothing: no tool, capability or record. The agent reads it as data in its working notes (never in the cached system prompt, never as something the person said), as a hint: before it states anything about the entity it reads it with a tool, and a tool that refuses means the agent says it cannot see it. A screen change while the chat is open does not open a new session; live updates are a later addition. Never arbitrary page text, URLs, names, amounts or instructions: only these fields, from this vocabulary. */
+        ScreenContext: {
+            /**
+             * @description A coarse screen from a fixed vocabulary; the tenant maps its own screens onto it. `other` when none fits. Customer side: `home`, `explore`, `search_results`, `professional`, `workspace`, `service`, `class`, `checkout`, `booking`, `bookings`, `inbox`, `profile`. Business side: `business_hub`, `setup`, `services`, `hours`, `location`, `gallery`, `spaces`, `space_manage`, `renters`, `payouts`, `plans`, `team`.
+             * @enum {string}
+             */
+            screen: "home" | "explore" | "search_results" | "professional" | "workspace" | "service" | "class" | "checkout" | "booking" | "bookings" | "inbox" | "profile" | "business_hub" | "setup" | "services" | "hours" | "location" | "gallery" | "spaces" | "space_manage" | "renters" | "payouts" | "plans" | "team" | "other";
+            /** @description the object on the screen, as the tenant's read tools name it; `id` is a tool id (letters, digits and `_`, `.`, `:`, `-`), since it reaches the agent's working notes */
+            entity?: {
+                /** @enum {string} */
+                type: "professional" | "workspace" | "service" | "class" | "booking" | "location";
+                id: string;
+            };
+            /** @description the filters the screen shows, typed; free text never */
+            filters?: {
+                service_ids?: string[];
+                category_ids?: string[];
+                area_id?: string;
+                /** Format: date */
+                date_from?: string;
+                /** Format: date */
+                date_to?: string;
+                price_max?: components["schemas"]["Money"];
+            };
+            /** @description the tenant's counter for this person's screen state; a later update never goes back to a lower one */
+            revision: number;
+        };
+        /** @description v1-draft.20: a tap target the app draws under the welcome. Tapping it sends `message` as the person's own text (an `input.text`, or `createTurnSse`), exactly as if they typed it; it starts nothing else. */
+        Chip: {
+            /** @description in Unicode code points */
+            label: string;
+            /** @description in Unicode code points */
+            message: string;
+        };
+        /** @description v1-draft.20: the tenant's greeting for the session's mode, with the chips of the session's screen when its manifest has some for it (else the mode's own), from the connector manifest (admin-v1 `Connector.welcome`), checked when the manifest loads. The app shows it the moment the session is ready: it costs no model call and is not a turn. The agent knows it was shown and does not greet again. */
+        Welcome: {
+            /** @description in Unicode code points */
+            text: string;
+            chips: components["schemas"]["Chip"][];
+        };
+        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;
+                /**
+                 * Format: uri
+                 * @description v1-draft.19, optional: the agent's avatar (`getAgentAvatarImage`), a square 512 px WebP with no metadata, re-encoded by Vinaverse from the tenant's upload and passed by its image screen. The URL is immutable (it changes when the image does), so an app may cache the image for as long as it likes; it needs no credential. Absent: no avatar yet, so draw the name's monogram.
+                 */
+                avatar_url?: 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"];
+            /** @description v1-draft.20, the session's mode, as given or as the agent's template sets it */
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            /** @description v1-draft.20, present when the session acts for a business */
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            /** @description v1-draft.20, the screen context the session accepted, when `createSession` gave one */
+            screen_context?: components["schemas"]["ScreenContext"];
+            /** @description v1-draft.20, absent when the tenant's manifest has no welcome for the session's mode */
+            welcome?: components["schemas"]["Welcome"];
+        };
+        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). `deleted` (v1-draft.21): its conversation was deleted from history.
+             * @enum {string}
+             */
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left" | "deleted";
+            /** 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 v1-draft.20: one photo of a `professional` or `workspace` card. Https only, from a prefix the tenant registered (admin-v1 `Connector.image_url_prefixes`), compared after the URL is parsed and normalized (no user info, backslash, fragment or dot segment): an image that fails is dropped, never the card. The tenant serves only photos its own moderation approved, at URLs that stay valid as long as the transcript (a card in history draws them again). An image that fails to load draws the name's monogram; the card stays. */
+        CardImage: {
+            /** Format: uri */
+            url: string;
+            width?: number;
+            height?: number;
+        };
+        /** @description v1-draft.20: the cards one turn draws together carry the same `id`. `layout` is a hint: `carousel` draws them in one horizontal row, `list` one under another. A client that does not know `group`, or a `layout` value, draws a list, as before. */
+        CardGroup: {
+            id: string;
+            /** @enum {string} */
+            layout: "list" | "carousel";
+        };
+        /** @description v1-draft.20, one link of a `links` card: one of the tenant's own destinations from its connector manifest (admin-v1 `Connector.help_links`), never a link the model wrote. */
+        CardLink: {
+            /** @description in Unicode code points */
+            label: string;
+            /** @description an https page of the tenant's, or a deep link that passes the deep-link rule (`next_step`) */
+            url: string;
+            /** @enum {string} */
+            purpose: "help" | "support" | "policy" | "contact" | "feedback";
+        };
+        /** @description v1-draft.20, on a `links` card: the tenant's scope policy, at the version in force, that kept the agent from answering, and why. */
+        ScopeProvenance: {
+            policy_id: string;
+            version: string;
+            /** @enum {string} */
+            reason: "off_scope" | "competitor" | "blocked_topic";
+        };
+        /**
+         * @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.
+         *
+         *     **Listing cards** (v1-draft.20). A `professional` or `workspace` card may carry `images` (up to five, the first the hero; `image_url`, when present, is the first one's URL, for clients that predate `images`), `next_available` (the earliest open time the tenant's tool returned; a hint, so a tap on its time reads availability again), `price_from` and a `group`. An app draws one hero image first and the rest on a swipe.
+         *     **A `links` card** (v1-draft.20) answers what the tenant's scope keeps the agent from answering: a question off its scope, a comparison with a competitor, a blocked topic. Its `links` are the tenant's own help, support, policy, contact or feedback destinations (`CardLink`), its `provenance` names the scope policy and the reason, and it has no `actions`: each link opens the tenant's page. It belongs to a recorded turn, with the agent's one line around it, never to `input.rejected`. Its `source.tool` is `scope` and its `source.call_id` the turn's id: no tool call made it. An earlier client skips the unknown kind, as it skips any.
+         */
+        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), then `links` (v1-draft.20: the tenant's own pages, when its scope keeps the agent from answering)
+             * @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" | "links";
+            question?: components["schemas"]["Question"];
+            proposal?: components["schemas"]["Proposal"];
+            ref?: components["schemas"]["CardRef"];
+            title: string;
+            subtitle?: string;
+            /** Format: uri */
+            image_url?: string;
+            /** @description v1-draft.20, a `professional` or `workspace` card's photos, the first the hero */
+            images?: components["schemas"]["CardImage"][];
+            /**
+             * Format: date-time
+             * @description v1-draft.20, a `professional` or `workspace` card's earliest open time, as the tenant's tool returned it
+             */
+            next_available?: string;
+            group?: components["schemas"]["CardGroup"];
+            /** @description v1-draft.20, a `links` card's links */
+            links?: components["schemas"]["CardLink"][];
+            provenance?: components["schemas"]["ScopeProvenance"];
+            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; on a metric without k_floor, nothing to measure */
+                    value: number | null;
+                    suppressed?: boolean;
+                }[];
+            }[];
+            dimensions?: {
+                key: string;
+                label: string;
+            }[];
+            columns?: {
+                key: string;
+                label: string;
+                unit: components["schemas"]["ValueUnit"];
+            }[];
+            rows?: {
+                dims: {
+                    [key: string]: string;
+                };
+                /** @description null when suppressed by the metric's k_floor; on a metric without k_floor, nothing to measure */
+                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 & unknown);
+        /** @enum {string} */
+        ValueUnit: "count" | "ppm" | "micros_usd" | "ms";
+        MetricRef: {
+            name: string;
+            label: string;
+            unit: components["schemas"]["ValueUnit"];
+            definition: string;
+            /** @description The privacy floor: a value built from fewer than this many distinct people is suppressed (`null`). Absent when no floor applies, as on a business's own operational data (Studio's pages, read by the business copilot); a `null` value there means there was nothing to measure, never a hidden count. */
+            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;
+        };
+        ConversationPage: {
+            data: components["schemas"]["ConversationSummary"][];
+            next_cursor: string | null;
+        };
+        /** @description v1-draft.21: one past conversation as a history screen lists it. No message text: the title is from the conversation's last search intent or its date, never the person's words. */
+        ConversationSummary: {
+            id: components["schemas"]["ConversationId"];
+            agent: string;
+            experience_mode: components["schemas"]["ExperienceMode"];
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            title: string;
+            /**
+             * @description `intent`: the last search intent (service and place); `date`: the day it started
+             * @enum {string}
+             */
+            title_source: "intent" | "date";
+            /** Format: date-time */
+            started_at: string;
+            /** Format: date-time */
+            last_activity_at: string;
+            /** @description the messages its timeline holds (cards not counted) */
+            message_count: number;
+            /**
+             * @description `open`: a session can resume it; `ended`: it can only be read
+             * @enum {string}
+             */
+            state: "open" | "ended";
+        };
+        TimelinePage: {
+            data: components["schemas"]["TimelineItem"][];
+            /** @description the next older page; null at the conversation's start */
+            next_cursor: string | null;
+        };
+        /**
+         * @description v1-draft.21: one item of a past conversation, a message or a card its turn drew. `id` is stable and unique within the conversation; a message's `event_id` is its live event's identifier (`TranscriptItem.id`), the key an app merges live and resumed messages by, with `role`. A card is read-only in history.
+         *     Unlike `session.ready.transcript`, the history holds a guardrail's refusals: the person's message a guardrail refused and the fixed line said instead of an answer both carry `refusal: true`, so the app draws them as it drew them live (muted, never offered again). A `proposal` card carries `proposal_outcome`, what became of it.
+         */
+        TimelineItem: {
+            /** @constant */
+            type: "message";
+            id: string;
+            /**
+             * @description a client tolerates a role it does not know, as in `TranscriptItem`
+             * @enum {string}
+             */
+            role: "person" | "assistant" | "staff";
+            text: string;
+            /** Format: date-time */
+            at: string;
+            /** @description absent on a `person` message sent without a `client_event_id` */
+            event_id?: string;
+            turn_id?: string;
+            /** @description `assistant` only, present only when true: the reply stopped before it finished */
+            interrupted?: boolean;
+            /**
+             * @description Present only when true: a guardrail refused this turn. On a `person` message, the text it refused (as recorded, card-like digits masked); on an `assistant` message, the fixed line said instead of an answer.
+             * @constant
+             */
+            refusal?: true;
+        } | {
+            /** @constant */
+            type: "card";
+            id: string;
+            turn_id: string;
+            /** Format: date-time */
+            at: string;
+            card: components["schemas"]["Card"];
+            /**
+             * @description A `proposal` card only, always present on one: the outcome the app reported for it (`ui.action` `confirmed`, `declined`, `failed` or `expired`), or `pending` while none was reported. Draw it as settled; a past proposal is never confirmed from history.
+             * @enum {string}
+             */
+            proposal_outcome?: "pending" | "confirmed" | "declined" | "failed" | "expired";
+        };
+        ConversationDeleted: {
+            conversation_id: components["schemas"]["ConversationId"];
+            sessions_revoked: number;
+        };
+        /** @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 v1-draft.20, the session's mode (`Session.experience_mode`), so the app keeps one store per mode */
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            /** @description v1-draft.20, present when the session acts for a business */
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            /**
+             * @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`). `deleted` (v1-draft.21): the person deleted the conversation from their history (`deleteConversation`, close code `4403`); drop it from the app's store and never resume it. A client that does not know `deleted` reads it as `revoked`, as any unknown reason.
+             * @enum {string}
+             */
+            reason: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "replaced" | "deleted";
+        } | {
+            /** @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;
+        /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+        OptionalIdempotencyKey: 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"];
+        };
+    };
+    listConversations: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                agent: string;
+                /** @description the side of the app; left out, the agent's template's */
+                experience_mode?: components["schemas"]["ExperienceMode"];
+                /** @description the business the person acts for; only with `experience_mode=business` */
+                business_scope_id?: components["schemas"]["BusinessScopeId"];
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Newest activity first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationPage"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            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"];
+        };
+    };
+    deleteConversation: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+            };
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationDeleted"];
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    listConversationMessages: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The newest page first; oldest first within a page. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TimelinePage"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+            503: 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?: {
+                /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+                "Idempotency-Key"?: components["parameters"]["OptionalIdempotencyKey"];
+            };
+            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"];
+            409: components["responses"]["Problem"];
+        };
+    };
+    refreshClientSecret: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+                "Idempotency-Key"?: components["parameters"]["OptionalIdempotencyKey"];
+            };
+            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"];
+            403: 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;
+                };
+            };
+            403: components["responses"]["Problem"];
+        };
+    };
+    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"];
+        };
+    };
+    getAgentAvatarImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description the SHA-256 of the image's bytes, its first 32 hex digits, then `.webp` */
+                avatar_file: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description the image */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "image/webp": string;
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+}
+
+/** Every schema of the pinned public contract (vinaverse-v1), by name: `Schemas['Session']`, `Schemas['Card']`, … */
+type Schemas = components['schemas'];
+type ClientEvent = Schemas['ClientEvent'];
+type ServerEvent = Schemas['ServerEvent'];
+type ServerEventType = ServerEvent['type'];
+type ServerEventOf<T extends ServerEventType> = Extract<ServerEvent, {
+    type: T;
+}>;
+type Card = Schemas['Card'];
+type CardKind = Card['kind'];
+type Question = Schemas['Question'];
+type AnswerInput = Schemas['AnswerInput'];
+type Proposal = Schemas['Proposal'];
+type TranscriptItem = Schemas['TranscriptItem'];
+type ClientSecret = Schemas['ClientSecret'];
+type TurnInput = Schemas['TurnInput'];
+/** v1-draft.20: the tenant's greeting for the session's mode, and the chips that send a message as the person's own. */
+type Welcome = Schemas['Welcome'];
+type CardImage = Schemas['CardImage'];
+type CardGroup = Schemas['CardGroup'];
+type CardLink = Schemas['CardLink'];
+/** The session as createSession returns it to the tenant's backend, which passes this part to the app. */
+type SessionInfo = Pick<Schemas['Session'], 'id' | 'realtime_url' | 'turns_url' | 'conversation_id'> & {
+    client_secret: ClientSecret | string;
+};
+/** The outcomes an app reports on a proposal card with `ui.action`. */
+type ProposalOutcome = 'confirmed' | 'declined' | 'failed' | 'expired';
+/** Whether this client knows how to read a card of this kind; skip any other card (§5). */
+declare function isKnownCard(card: {
+    kind: string;
+}): card is Card;
+
+/** A frame as received or sent: its `type`, and whatever else the contract gives it. */
+interface Frame {
+    readonly type: string;
+    readonly [field: string]: unknown;
+}
+/** A card as the app holds it. `locked` lists the question ids (the card's, or a `rate_each` row's) drawn locked. */
+interface HeldCard {
+    readonly id: string;
+    readonly kind: string;
+    readonly card: Readonly<Record<string, unknown>>;
+    readonly question?: HeldQuestion;
+    readonly locked: readonly string[];
+    /** The turn that drew the card, when known: `ui.action` names it with the card's `id`. */
+    readonly turnId?: string;
+    /** A proposal's first reported outcome (`confirmed`, `declined`, `failed`, `expired`); later ones change nothing. */
+    readonly outcome?: string | null;
+    /** Arrival order, shared with messages: a timeline sorts both by it. Moves when the card is drawn again. */
+    readonly seq: number;
+}
+interface HeldQuestion {
+    readonly question_id: string;
+    readonly kind: string;
+    readonly state: string;
+    readonly answer?: unknown;
+    readonly row_answers?: readonly {
+        question_id: string;
+        answer: unknown;
+    }[];
+    readonly rows?: readonly {
+        question_id: string;
+    }[];
+    readonly [field: string]: unknown;
+}
+interface Message {
+    readonly role: 'assistant' | 'person' | 'staff' | (string & {});
+    readonly text: string;
+    /**
+     * Stable for the message's life, to key it in a list: a person's text by its `client_event_id`, an agent's reply by
+     * its turn (`a:<turn_id>`), a staff reply by its `message_id` (`s:<id>`), a guardrail refusal by the input it answers
+     * (`r:<client_event_id>`), a transcript item by its server `id` as the live key it matches, or by its time and role
+     * (`t:<at>:<role>`) from a server that sends no `id`.
+     */
+    readonly key: string;
+    /** Arrival order, shared with cards: a timeline sorts both by it. */
+    readonly seq: number;
+    /**
+     * A reply cut off after some of it streamed; what streamed stands (§6): `blocked` (`output_blocked`), `interrupted`
+     * (`cancelled`, as when a person from the business takes over, or the connection dropped), `failed` (any other code).
+     */
+    readonly partial?: 'blocked' | 'interrupted' | 'failed';
+    /** A person's text recorded during a takeover (`input.received`): the business reads it; no agent turn runs. */
+    readonly received?: true;
+    /** The agent's reply is a guardrail refusal (`input.rejected` `guardrail`, its `message`). */
+    readonly refusal?: true;
+}
+/** A person from the business is replying (`takeover.started`); `by` is their role as the person sees it. */
+interface Takeover {
+    readonly by: string | null;
+    readonly at: string;
+}
+/** The turn's text streamed so far (`message.delta`), until its `message.completed`. */
+interface Streaming {
+    readonly turnId: string;
+    readonly text: string;
+    /** Taken at the turn's first delta, and kept by its message: a reply sorts before the cards its turn drew after it. */
+    readonly seq: number;
+}
+interface Connection {
+    readonly name: string;
+    readonly state: 'open' | 'closed';
+    readonly code?: number;
+    readonly reason?: string;
+}
+interface ToolLine {
+    readonly turn_id: string;
+    readonly label: string;
+    readonly state: string;
+}
+/**
+ * Whether and how the conversation goes on after a connection ends:
+ * - `allowed`: reconnect to the same session;
+ * - `user_action_only`: the session was revoked or replaced (the conversation continued elsewhere): resume only when
+ *   the person asks;
+ * - `new_session_on_next_action`: the session ended (idle, expired, limit_reached) but the conversation did not; its
+ *   secret is spent. On the person's next action, the app has its backend create a new session for the same
+ *   conversation and calls `resume()`.
+ */
+type Reconnect = 'allowed' | 'user_action_only' | 'new_session_on_next_action';
+/** The engine's whole state, for an app to draw. */
+interface ConversationState {
+    readonly sessionId: string | null;
+    readonly conversationId: string | null;
+    readonly connection: Connection | null;
+    /** How the conversation goes on after the connection ends (`Reconnect`). */
+    readonly reconnect: Reconnect;
+    readonly messages: readonly Message[];
+    /** Every card held, oldest first. */
+    readonly cards: readonly HeldCard[];
+    /** The newest question card still open: the one to answer. */
+    readonly openQuestion: string | null;
+    /** Events sent and neither acknowledged nor refused, by `client_event_id`: resend them, same id, after a reconnect. */
+    readonly unacknowledged: readonly Frame[];
+    /** Ids refused for now (`turn_in_progress`, `screen_unavailable`): send again with the same id. */
+    readonly resend: readonly string[];
+    /**
+     * Texts and answers refused with `limit_reached`: never resent in this session (it would get the same refusal);
+     * resent, same id, on the next session's `session.ready`. Kept apart from `resend` (conformance README, `held`). A
+     * refused action is dropped: a new session cannot act on an earlier session's card.
+     */
+    readonly held: readonly string[];
+    /** Typed messages whose refusal stands, by `client_event_id`: shown as not sent, never resent. */
+    readonly refused: Readonly<Record<string, string>>;
+    /** The last `flow.completed`: `ok`, `refused` or `failed` (an unknown result reads as `failed`). */
+    readonly flow: {
+        readonly flow: unknown;
+        readonly result: 'ok' | 'refused' | 'failed';
+    } | null;
+    /** The turn in progress. */
+    readonly turn: string | null;
+    /** The last state of each tool line (the last 100). */
+    readonly tools: readonly ToolLine[];
+    readonly handoffs: readonly unknown[];
+    /** The codes of `error` and `turn.failed` events (the last 100). */
+    readonly errors: readonly string[];
+    /**
+     * While `reconnect` is `new_session_on_next_action`: the `client_event_id`s held for the next session (unacknowledged,
+     * or refused for this session's turn limit). Draw them as "sends when you continue", not as failed. Empty otherwise.
+     */
+    readonly heldForNextSession: readonly string[];
+    /** Seconds left when `session.expiring` arrived (WebSocket only, about a minute before the end); null otherwise. */
+    readonly expiring: number | null;
+    /** The turn's text streamed so far, until its `message.completed` (or its end, which keeps it as a message). */
+    readonly streaming: Streaming | null;
+    /** While a person from the business replies (§8): from `takeover.started` to `takeover.ended`. */
+    readonly takeover: Takeover | null;
+    /** Every refusal's code and `message` (`input.rejected`), by `client_event_id`; `refused` lists those that stand. */
+    readonly rejections: Readonly<Record<string, {
+        code: string;
+        message: string;
+    }>>;
+    /** The AI disclosure `session.ready` carries: always shown, never removed. Null until the first one. */
+    readonly disclosure: string | null;
+    /** `session.ready`'s `limits.turns_left`, when given. */
+    readonly turnsLeft: number | null;
+}
+declare class ConversationEngine {
+    private sessionId;
+    private conversationId;
+    private connection;
+    private reconnect;
+    private messages;
+    private cards;
+    private unacknowledged;
+    private resend;
+    private held;
+    private refused;
+    private flow;
+    private turn;
+    private tools;
+    private handoffs;
+    private errors;
+    private expiring;
+    private streaming;
+    private takeover;
+    private rejections;
+    private disclosure;
+    private turnsLeft;
+    /** The next arrival number for a message or a card. */
+    private seq;
+    /** The cards drawn before a resumed flow's transcript replaced them: proposal outcomes carry over. */
+    private replaced;
+    /** client_event_id → the first event the app sent under it, until it is settled. */
+    private readonly inputs;
+    /** The tenant's backend created a session (and named its conversation). */
+    sessionCreated(sessionId: string, conversationId?: string | null): void;
+    /** A connection opened: the user's own action, or an allowed reconnect, so it lifts a hold on reconnecting. */
+    connected(name: string): void;
+    /** A connection closed with its code. `4403` (revoked) and `4409` (replaced) hold reconnecting for a user action. */
+    closed(name: string, code: number): void;
+    /** The app was killed: what it drew is gone; what it sent and never saw acknowledged it kept, to resend. */
+    killed(): void;
+    sent(event: Frame): void;
+    received(event: Frame): void;
+    private ready;
+    /**
+     * A transcript merged by key: an item the app holds keeps its place, with the text the server recorded; one it does
+     * not hold goes just after the nearest earlier item it does (just before the first later one when none came before,
+     * at the end when it holds none of them). Nothing the app holds is dropped.
+     */
+    private mergeTranscript;
+    private hold;
+    private recorded;
+    private rejected;
+    private inputRejected;
+    /** No longer to resend, nor held for the next session (sent again, or settled). */
+    private unqueue;
+    /** An input acknowledged or refused for good: nothing more is resent under its id. */
+    private settle;
+    /** Adds a message once: a key already held (a frame seen twice) changes nothing. */
+    private say;
+    /** The turn's streamed text, kept as the agent's message when the turn ends without its `message.completed`. */
+    private cutOff;
+    private error;
+    /**
+     * An input that could not be delivered, or whose retries are spent (`screen_unavailable` after the last try): it is
+     * no longer resent. A typed message is shown as not sent, with `code`; an answer's question unlocks so the person
+     * can answer again; a proposal outcome it reported is taken back, so it can be reported again.
+     */
+    giveUp(clientEventId: string, code: string): void;
+    /** A turn the app stopped where no event will say so (an SSE turn cancelled): none is in progress. */
+    turnEnded(): void;
+    /** The event first sent under a `client_event_id`, to resend it unchanged. */
+    input(clientEventId: string): Frame | undefined;
+    state(): ConversationState;
+}
+
+/** Why the client refused to do something; `code` is stable, `message` is for people. */
+type ClientErrorCode = 
+/** A service key (`vv_sk_`) was given: it belongs on the tenant's backend, never in an app. */
+'service_key'
+/** The value is not a client secret (`vv_cs_` and at least 16 base64url characters). */
+ | 'invalid_secret'
+/** The action needs the WebSocket (answers to question cards); the session runs over SSE. */
+ | 'needs_websocket'
+/** The session was closed by the app, or ended for good (replaced, revoked, expired). */
+ | 'session_ended'
+/** An SSE request failed: `status` holds the HTTP status. */
+ | 'http_error'
+/**
+ * The session ended but the conversation did not (idle, expired, its turn limit): its secret is spent. Have your
+ * backend create a new session for the conversation and call `resume()` with it.
+ */
+ | 'needs_new_session';
+declare class VinaverseClientError extends Error {
+    readonly name = "VinaverseClientError";
+    readonly code: ClientErrorCode;
+    readonly status: number | undefined;
+    constructor(code: ClientErrorCode, message: string, status?: number);
+}
+
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** One SSE request: where and with which secret, and the `fetch` to use. */
+interface SseTarget {
+    /** The session's `turns_url` (`…/v1/sessions/{session_id}/turns`). */
+    readonly turnsUrl: string;
+    readonly secret: string;
+    readonly fetch?: FetchLike;
+    readonly signal?: AbortSignal;
+}
+/** Run one turn from a typed message (`createTurnSse`), yielding its events as they arrive. */
+declare function turnSse(target: SseTarget, input: {
+    text: string;
+    client_event_id?: string;
+}): AsyncGenerator<Frame>;
+/** Send a card action, such as a proposal outcome, and stream the resulting turn (`createCardActionSse`). */
+declare function cardActionSse(target: SseTarget, turnId: string, input: {
+    card_id: string;
+    action: string;
+    client_event_id?: string;
+}): AsyncGenerator<Frame>;
+/** Frames from an SSE text stream: blank-line separated events, `data:` lines joined; comments and non-JSON skipped. */
+declare function sseFrames(chunks: AsyncIterable<string>): AsyncGenerator<Frame>;
+
+/** The part of a WebSocket the session uses: the browser, React Native and Node 22+ ones all fit. */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Opens a WebSocket. `headers` is set only with `auth: 'header'`. The default factory passes them as React Native's
+ * WebSocket takes them (its third argument) or, on Node 22+, as its WebSocket does (`{ protocols, headers }`); a
+ * browser's WebSocket cannot send headers, so browsers use the subprotocol.
+ */
+type WebSocketFactory = (url: string, protocols: string[], headers?: Record<string, string>) => WebSocketLike;
+/** How the client secret reaches the server (§1); the secret never goes in the URL. */
+type AuthMode = 'header' | 'subprotocol' | 'first_frame';
+type SessionStatus = 
+/** Opening a connection, or waiting for `session.ready`. */
+'connecting'
+/** `session.ready` arrived: events flow. */
+ | 'ready'
+/** Waiting to reconnect after the connection dropped. */
+ | 'reconnecting'
+/** Disconnected; connects again on the next send or `connect()`. */
+ | 'idle'
+/** Running turns over SSE, because the WebSocket could not be opened (twice); `connect()` tries it again. */
+ | 'sse'
+/**
+ * The session ended. `state.reconnect` says what next: `new_session_on_next_action` after it ended idle, expired
+ * or at its limit (have your backend create a new session for the conversation on the person's next action, then
+ * `resume()` it; what they send meanwhile is held and resent there), or `user_action_only` (the conversation
+ * continued elsewhere, or the session was revoked: resume only when the person asks).
+ */
+ | 'ended'
+/** The client secret was refused (4401) and no fresh one could be had. */
+ | 'unauthorized'
+/** Closed by the app. */
+ | 'closed';
+interface SessionOptions {
+    /** The session the tenant's backend created: its `id`, `realtime_url`, `turns_url` and `client_secret`. */
+    readonly session: SessionInfo;
+    /**
+     * A fresh client secret for the session named, from the tenant's backend (refreshClientSecret is a service-key
+     * call), when the server refuses the current one (4401): for example after the first connection's window (two
+     * minutes from issue on the current gateway) passed. It is asked for the session in use; an answer that arrives
+     * after `resume()` moved to another session, or after `close()`, is dropped. Without it, a refused secret ends in
+     * `unauthorized`.
+     */
+    readonly refreshSecret?: (sessionId: string) => Promise<ClientSecret | string>;
+    /**
+     * Default `subprotocol` (`vinaverse.v1, bearer.<secret>`). `header` where the WebSocket takes headers: React
+     * Native and Node 22+ with the default factory, or your own `webSocket`.
+     */
+    readonly auth?: AuthMode;
+    /** Default: the global WebSocket. */
+    readonly webSocket?: WebSocketFactory;
+    /** Default: the global fetch. Used by the SSE fallback. */
+    readonly fetch?: FetchLike;
+    /** Fall back to SSE turns when the WebSocket cannot be opened. Default true. */
+    readonly sseFallback?: boolean;
+    /** Delays before reconnecting after a drop, in ms; the last one repeats. Default 1 s doubling to 30 s. */
+    readonly reconnectDelays?: readonly number[];
+    /** Attempts to reconnect before going `idle`; they count again once a connection stayed up 30 s. Default 8. */
+    readonly maxReconnects?: number;
+    /** Delays before resending an input refused with `screen_unavailable`, in ms. Default 2 s, 4 s, 8 s. */
+    readonly screenRetryDelays?: readonly number[];
+    /** The `ping` interval while in the foreground, in ms. Default 25 s. */
+    readonly pingInterval?: number;
+    /** New `client_event_id`s. Default: random, `ce_` and 22 characters. */
+    readonly createId?: () => string;
+    /** An engine to continue, for example one an app kept across a restart. */
+    readonly engine?: ConversationEngine;
+}
+interface SessionEvents {
+    /**
+     * Every event the server sends, `message.delta` included. A type this client does not know arrives too (§5), so a
+     * `switch` on `type` keeps a default branch.
+     */
+    event: ServerEvent;
+    /** The conversation's state changed. */
+    state: ConversationState;
+    status: SessionStatus;
+    /**
+     * Something failed that no call returned: an input that could not be delivered (it is also shown as not sent in
+     * the state), an SSE turn, or getting a fresh secret.
+     */
+    error: VinaverseClientError;
+}
+type Listener<T> = (value: T) => void;
+declare class VinaverseSession {
+    readonly engine: ConversationEngine;
+    private info;
+    private secret;
+    private readonly options;
+    private socket;
+    /** The engine's name for the connection in `socket`, once it opened. */
+    private opened;
+    private connection;
+    private ready;
+    private current;
+    private everOpened;
+    private firstFailures;
+    private attempts;
+    /** The reason of the `session.closed` that preceded the close, on the current connection. */
+    private closeReason;
+    private stableTimer;
+    /** SSE requests in flight. */
+    private readonly streams;
+    private reconnectTimer;
+    private pingTimer;
+    private foreground;
+    private refreshed;
+    /** client_event_id → why it waits: after the turn, or after a backoff. */
+    private readonly waiting;
+    /** client_event_id → the session that refused it for its turn limit: resent only on another session. */
+    private readonly heldForSession;
+    private readonly screenTries;
+    private readonly screenTimers;
+    private readonly listeners;
+    constructor(options: SessionOptions);
+    /** The engine names the session, and keeps the conversation it already knew when this one does not say. */
+    private named;
+    get status(): SessionStatus;
+    get state(): ConversationState;
+    on<K extends keyof SessionEvents>(name: K, listener: Listener<SessionEvents[K]>): () => void;
+    /**
+     * Connect, or reconnect: the user's own action, so it also resumes after the conversation continued elsewhere
+     * or the secret was refused.
+     */
+    connect(): void;
+    private start;
+    /**
+     * Continue the conversation on a new session the tenant's backend created for it (by `conversation_key` or
+     * `conversation_id`): its `session.ready` brings the transcript and pending cards, and what was never
+     * acknowledged is resent there. A user action, like `connect()`.
+     */
+    resume(session: SessionInfo): void;
+    /** Close for good: the connection, any SSE turn still streaming, and every timer. */
+    close(): void;
+    /** Ping only while the app is in the foreground (every 25 s); in the background the connection may idle out. */
+    setForeground(foreground: boolean): void;
+    private open;
+    private afterClose;
+    /** After a 4401: one fresh secret for the session in use, unless it moved on or was closed meanwhile. */
+    private refresh;
+    private scheduleReconnect;
+    private cancelReconnect;
+    private fallBack;
+    /** Close the current connection, if any, without reacting to its close event. */
+    private drop;
+    private forget;
+    private frame;
+    private receive;
+    private refusedForNow;
+    private resendUnacknowledged;
+    /** What a turn limit held, on a session other than the one that refused it. */
+    private resendHeldForSession;
+    private resendWaiting;
+    private resend;
+    /** Keep an input for a later session: unacknowledged, so the next `session.ready` (after resume()) sends it. */
+    private hold;
+    /** The session ended: retries waiting on a timer would go nowhere, so their inputs are held for the next session. */
+    private holdRetries;
+    /** Send a typed message; returns its `client_event_id`. Over SSE it runs the turn there. */
+    sendText(text: string): string;
+    /** Answer a question card (or a `rate_each` row, by the row's `question_id`); returns the `client_event_id`. */
+    answer(cardId: string, questionId: string, answer: AnswerInput): string;
+    /**
+     * Report a proposal's outcome after the tenant's backend answered (§6): `confirmed`, `declined`, `failed` or
+     * `expired`. The first outcome per card is final. Returns the `client_event_id`.
+     */
+    reportOutcome(cardId: string, outcome: ProposalOutcome): string;
+    /** A card action (`ui.action`), named by the card's `id`; the card's turn is taken from the state. */
+    action(cardId: string, action: string): string;
+    /** Stop the turn in progress: `input.cancel` on the WebSocket; over SSE, the turn's request is stopped. */
+    cancel(turnId: string): void;
+    /** Ended idle: inputs are held for the new session that `resume()` brings. */
+    private awaitingNewSession;
+    private live;
+    /**
+     * Every input goes through here: recorded as sent (unacknowledged until the server answers it), then over SSE,
+     * or on the WebSocket when the session is ready, or held and resent once `session.ready` arrives.
+     */
+    private deliver;
+    private transmit;
+    /** One input over SSE: a typed message or a card action; an answer cannot go, and is shown as not sent. */
+    private overSse;
+    private isUnacknowledged;
+    private inFlight;
+    private stopSse;
+    private sseTarget;
+    private newId;
+    private startPing;
+    private stopPing;
+    private setStatus;
+    private emitState;
+    private emit;
+}
+
+export { type AnswerInput as A, type WebSocketFactory as B, type CardLink as C, type WebSocketLike as D, cardActionSse as E, type FetchLike as F, type components as G, type HeldCard as H, type operations as I, type paths as J, sseFrames as K, turnSse as L, type Message as M, type Proposal as P, type Question as Q, type Reconnect as R, type Schemas as S, type ToolLine as T, VinaverseClientError as V, type Welcome as W, type Card as a, type CardGroup as b, type CardImage as c, type CardKind as d, type ClientErrorCode as e, type HeldQuestion as f, type ProposalOutcome as g, type AuthMode as h, isKnownCard as i, type ClientEvent as j, type ClientSecret as k, type Connection as l, ConversationEngine as m, type ConversationState as n, type Frame as o, type ServerEvent as p, type ServerEventOf as q, type ServerEventType as r, type SessionEvents as s, type SessionInfo as t, type SessionOptions as u, type SessionStatus as v, type SseTarget as w, type TranscriptItem as x, type TurnInput as y, VinaverseSession as z };