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

package/dist/session--W6JXfwo.d.ts

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