@vinaverse/client 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/{session-C3qZwGPG.d.ts → session-8W3fRNeb.d.ts}

@@ -1,248 +1,493 @@
-declare const CONTRACT: {
-    readonly api: "v1-draft.20";
-    readonly commit: "5f6f41bdbfbdd6eadf21180eed1ffddfa5310355";
-};
-
-/** 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()`.
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
  */
-type Reconnect = 'allowed' | 'user_action_only' | 'new_session_on_next_action';
-/** The engine's whole state, for an app to draw. */
-interface ConversationState {
-    readonly sessionId: string | null;
-    readonly conversationId: string | null;
-    readonly connection: Connection | null;
-    /** How the conversation goes on after the connection ends (`Reconnect`). */
-    readonly reconnect: Reconnect;
-    readonly messages: readonly Message[];
-    /** Every card held, oldest first. */
-    readonly cards: readonly HeldCard[];
-    /** The newest question card still open: the one to answer. */
-    readonly openQuestion: string | null;
-    /** Events sent and neither acknowledged nor refused, by `client_event_id`: resend them, same id, after a reconnect. */
-    readonly unacknowledged: readonly Frame[];
-    /** Ids refused for now (`turn_in_progress`, `screen_unavailable`): send again with the same id. */
-    readonly resend: readonly string[];
-    /**
-     * Texts and answers refused with `limit_reached`: never resent in this session (it would get the same refusal);
-     * resent, same id, on the next session's `session.ready`. Kept apart from `resend` (conformance README, `held`). A
-     * refused action is dropped: a new session cannot act on an earlier session's card.
-     */
-    readonly held: readonly string[];
-    /** Typed messages whose refusal stands, by `client_event_id`: shown as not sent, never resent. */
-    readonly refused: Readonly<Record<string, string>>;
-    /** The last `flow.completed`: `ok`, `refused` or `failed` (an unknown result reads as `failed`). */
-    readonly flow: {
-        readonly flow: unknown;
-        readonly result: 'ok' | 'refused' | 'failed';
-    } | null;
-    /** The turn in progress. */
-    readonly turn: string | null;
-    /** The last state of each tool line (the last 100). */
-    readonly tools: readonly ToolLine[];
-    readonly handoffs: readonly unknown[];
-    /** The codes of `error` and `turn.failed` events (the last 100). */
-    readonly errors: readonly string[];
-    /**
-     * While `reconnect` is `new_session_on_next_action`: the `client_event_id`s held for the next session (unacknowledged,
-     * or refused for this session's turn limit). Draw them as "sends when you continue", not as failed. Empty otherwise.
-     */
-    readonly heldForNextSession: readonly string[];
-    /** Seconds left when `session.expiring` arrived (WebSocket only, about a minute before the end); null otherwise. */
-    readonly expiring: number | null;
-    /** The turn's text streamed so far, until its `message.completed` (or its end, which keeps it as a message). */
-    readonly streaming: Streaming | null;
-    /** While a person from the business replies (§8): from `takeover.started` to `takeover.ended`. */
-    readonly takeover: Takeover | null;
-    /** Every refusal's code and `message` (`input.rejected`), by `client_event_id`; `refused` lists those that stand. */
-    readonly rejections: Readonly<Record<string, {
-        code: string;
-        message: string;
-    }>>;
-    /** The AI disclosure `session.ready` carries: always shown, never removed. Null until the first one. */
-    readonly disclosure: string | null;
-    /** `session.ready`'s `limits.turns_left`, when given. */
-    readonly turnsLeft: number | null;
-}
-declare class ConversationEngine {
-    private sessionId;
-    private conversationId;
-    private connection;
-    private reconnect;
-    private messages;
-    private cards;
-    private unacknowledged;
-    private resend;
-    private held;
-    private refused;
-    private flow;
-    private turn;
-    private tools;
-    private handoffs;
-    private errors;
-    private expiring;
-    private streaming;
-    private takeover;
-    private rejections;
-    private disclosure;
-    private turnsLeft;
-    /** The next arrival number for a message or a card. */
-    private seq;
-    /** The cards drawn before a resumed flow's transcript replaced them: proposal outcomes carry over. */
-    private replaced;
-    /** client_event_id → the first event the app sent under it, until it is settled. */
-    private readonly inputs;
-    /** The tenant's backend created a session (and named its conversation). */
-    sessionCreated(sessionId: string, conversationId?: string | null): void;
-    /** A connection opened: the user's own action, or an allowed reconnect, so it lifts a hold on reconnecting. */
-    connected(name: string): void;
-    /** A connection closed with its code. `4403` (revoked) and `4409` (replaced) hold reconnecting for a user action. */
-    closed(name: string, code: number): void;
-    /** The app was killed: what it drew is gone; what it sent and never saw acknowledged it kept, to resend. */
-    killed(): void;
-    sent(event: Frame): void;
-    received(event: Frame): void;
-    private ready;
-    /**
-     * A transcript merged by key: an item the app holds keeps its place, with the text the server recorded; one it does
-     * not hold goes just after the nearest earlier item it does (just before the first later one when none came before,
-     * at the end when it holds none of them). Nothing the app holds is dropped.
-     */
-    private mergeTranscript;
-    private hold;
-    private recorded;
-    private rejected;
-    private inputRejected;
-    /** No longer to resend, nor held for the next session (sent again, or settled). */
-    private unqueue;
-    /** An input acknowledged or refused for good: nothing more is resent under its id. */
-    private settle;
-    /** Adds a message once: a key already held (a frame seen twice) changes nothing. */
-    private say;
-    /** The turn's streamed text, kept as the agent's message when the turn ends without its `message.completed`. */
-    private cutOff;
-    private error;
-    /**
-     * An input that could not be delivered, or whose retries are spent (`screen_unavailable` after the last try): it is
-     * no longer resent. A typed message is shown as not sent, with `code`; an answer's question unlocks so the person
-     * can answer again; a proposal outcome it reported is taken back, so it can be reported again.
-     */
-    giveUp(clientEventId: string, code: string): void;
-    /** A turn the app stopped where no event will say so (an SSE turn cancelled): none is in progress. */
-    turnEnded(): void;
-    /** The event first sent under a `client_event_id`, to resend it unchanged. */
-    input(clientEventId: string): Frame | undefined;
-    state(): ConversationState;
-}
 
-/** Why the client refused to do something; `code` is stable, `message` is for people. */
-type ClientErrorCode = 
-/** A service key (`vv_sk_`) was given: it belongs on the tenant's backend, never in an app. */
-'service_key'
-/** The value is not a client secret (`vv_cs_` and at least 16 base64url characters). */
- | 'invalid_secret'
-/** The action needs the WebSocket (answers to question cards); the session runs over SSE. */
- | 'needs_websocket'
-/** The session was closed by the app, or ended for good (replaced, revoked, expired). */
- | 'session_ended'
-/** An SSE request failed: `status` holds the HTTP status. */
- | 'http_error'
-/**
- * The session ended but the conversation did not (idle, expired, its turn limit): its secret is spent. Have your
- * backend create a new session for the conversation and call `resume()` with it.
- */
- | 'needs_new_session';
-declare class VinaverseClientError extends Error {
-    readonly name = "VinaverseClientError";
-    readonly code: ClientErrorCode;
-    readonly status: number | undefined;
-    constructor(code: ClientErrorCode, message: string, status?: number);
+interface paths {
+    "/v1/sessions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create an agent session for one subject
+         * @description A session belongs to a conversation when it names one (`conversation_key`, `conversation_id`, or both) or when its agent runs a guided flow; a flow session that names none starts a new conversation. `Session` then returns its `conversation_id`, and a conversation started without a key can later be resumed by that id. A conversation is scoped to the tenant, the environment, the `subject.id` and the `agent`, and (v1-draft.20) the mode and business scope it started with; `subject.type` itself is not part of it, so a guest who signs in keeps the conversation.
+         *     **`business_setup`.** The `business_setup` capability is only for a business's own people: a `subject.type` of `professional`, `host` or `staff`. Asked for any other subject, it is `400 invalid_request` with the pointer `/tool_access/capabilities`.
+         *     **`booking_proposals`.** The `booking_proposals` capability is only for a `client`: not a guest, who has no account in the tenant's app to confirm with. Asked for any other subject, it is `400 invalid_request` with the pointer `/tool_access/capabilities`.
+         *     **Audience** (v1-draft.20). An agent talks only to the subject types of its template (admin-v1 `AgentProfile.audience`): the customer agent to a `client` or `guest`, a business agent to a `professional`, `host` or `staff`, a guided flow to anyone its tenant names. Any other `subject.type` is `400 invalid_request` with the pointer `/subject/type`. The tenant's backend sets the type by the side of its app the person is on, never by the account's roles: a professional booking for themselves is a `client`.
+         *     **Mode and business scope** (v1-draft.20). `experience_mode` is the agent's side: `customer` for the customer agent, `business` for a business agent. Left out, it follows the agent's template; given, it must match it (`400 invalid_request`, `/experience_mode`). `business_scope_id` names the business the person acts for (a professional's business, a host's place): only with `business` (`400`, `/business_scope_id`), and the tenant's backend derives it from its own records, never from the app. A conversation is bound, when it starts, to the subject, the agent, the mode and the business scope. The mode stands for the side of the app, so a guest who signs in as a client keeps their conversation, while a professional never resumes a customer conversation (the audience rule keeps each side's types apart). Resuming with any of them different is `404 not_found` (step 1 below), never a switch: a person acting for business A never resumes business B's conversation.
+         *     **The checks, in this order:** 1. `conversation_id` is given, and is unknown, erased, or belongs to another tenant, environment, `agent` or
+         *        `subject.id`, or (v1-draft.20) was started with another `experience_mode` or `business_scope_id`: `404
+         *        not_found`. A `conversation_key` names a conversation within the same binding,
+         *        so the same key under another binding names another conversation.
+         *     2. Both are given, and the key names a different conversation, or none: `409 conversation_mismatch`. 3. The conversation expired: `410 conversation_expired`. With `conversation_key` alone, an expired
+         *        conversation instead lets a new one start under the key; the id never starts one silently.
+         *     4. The conversation is completed (its flow was accepted): `409 conversation_completed`. This holds by key too,
+         *        so a finished survey is never started twice.
+         *
+         *     **Resuming** is the same however the conversation is named. The new session continues the conversation, and `conversation_id` stays the same. The agent gets the answers recorded so far and a short summary, and re-emits the pending question card under its original `id`. A question card keeps its `id` across the sessions of a conversation, so an answer resent on a later session still names it. `client_event_id`s are deduplicated across all the sessions of the conversation. The older open session of the conversation is replaced (`session.closed replaced`, close `4409`). Each session still has its own short-lived client secret.
+         */
+        post: operations["createSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/suggestions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pick, rank and word a few explore suggestions from the candidates the tenant sends
+         * @description Synchronous, with a service key that has `sessions:write` (a key without scopes has every scope). Feature `suggestions`, for caps and switches: when it is off or capped, the answer is `feature_unavailable`, as everywhere else.
+         *     **Time.** The tenant waits at most 1.5 seconds. The runtime answers within 1.2 seconds, with what it has by then, or an empty list. A request whose caller disconnected before the answer is not charged and does not count toward the `suggestions` cap, so the tenant's ledger, which records the `usage` it receives, stays exact.
+         *     **The split.** The tenant supplies the facts: `candidates` from its own live data, each with a `ref`, a `kind`, a `title` and open `facts`. The agent picks between `min` and `max` of them, ranks them, and writes a short `title` and `why` for each. It may also turn one into a question for the agent (`action: ask`). - **Never an invented target.** `ref` is always one of the request's candidates, and `null` only for `ask`. - **Never a claim beyond the facts.** `why` uses only the facts sent. An unknown `facts` key is ignored. - **No filler.** With fewer than `min` good suggestions, the list is empty. `min` greater than `max` is
+         *       `400 invalid_request` with the pointer `/max`.
+         *     - **Language and length.** `title`, `why` and `question` are in `subject.locale`, falling back to the
+         *       tenant's default locale and then English. Their lengths are counted in Unicode code points; a check in a
+         *       language whose strings are UTF-16 (.NET, JavaScript) must count code points, not UTF-16 units.
+         *
+         *     **Candidates are untrusted data.** Candidate `title`s and `facts` often come from other people (a host's listing title, a professional's name). They enter the model as quoted data in a delimited block, never as instructions, and the platform floor applies: every `title`, `why` and `question` passes the leak check and the blocked-topic filter before it is returned.
+         *     **Tool mode.** Only when `candidates` is omitted and `tool_access` is given does the agent read the tenant's `read` tools for candidates. With `candidates` present, the tools are not read, and every `ref` is a candidate's. In tool mode: - `why` uses only the tool results; - a `ref` is `<kind>:<id>`, with the `id` exactly as the tenant's read tool returned it: `professional` from
+         *       `get_professional` and the search tools, `space` from `get_workspace`, `service` from the catalogue's
+         *       `service_type`, `class` from a tool that returns classes;
+         *     - the tenant validates a `ref` by fetching that object again before it shows the suggestion.
+         *     **The agent's guardrails apply.** The suggestions follow the `scope` and `blocked_topics` of the request's `agent` (default `customer_assistant`). An `agent` the tenant does not have is `400 invalid_request` with the pointer `/agent`. `business_setup` or `booking_proposals` in `tool_access` is refused (`400 invalid_request`, `/tool_access/capabilities`): suggestions never propose, and the subject is a `client` or a `guest`.
+         *     **Privacy and caching.** `personalized` says whether any suggestion used the subject's own history, from a `facts` key such as `booked_by_subject` or from the tools. It is always `false` for a `guest`. A personalised answer never crosses subjects: its cache key includes the tenant, environment and `subject.id`, and the rest of the key (place, filters, a cell size) is the tenant's choice. A response with `personalized: false` may also be cached across subjects. The decision records are kept for the tenant's `transcript_retention` (at most 30 days; with `none`, not after the answer), and are erased with the subject (`eraseSubject`).
+         *     **An `ask` suggestion** opens the agent with `question` already typed in the composer. It becomes the person's message only when they send it, and they may edit it first. No session field carries the suggestion.
+         */
+        post: operations["createSuggestions"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/conversations/{conversation_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The state of one conversation, with all its answers
+         * @description The same `ConversationState` the conversation webhooks carry, always complete: `answers` and `remarks` are never omitted here, and `sequence` is the same counter the webhooks carry. Use it when a webhook arrives with `answers_omitted: true`, or to check where a person is.
+         *     **Access.** A service key only, never a client secret, and only for the key's own tenant and environment. The key needs the `conversations:read` scope (a key without scopes has every scope); otherwise `403 forbidden`.
+         *     **How long the state can be read.** - While the conversation lives. - **72 hours after it ends without acceptance** (`expired`, including one whose last submission
+         *       `failed`): the final state, answers included, stays readable, so a backend that missed an omitted
+         *       webhook can still fetch the answers.
+         *     - **Under `transcript_retention: none`,** the state is deleted on acceptance, and the tenant already holds
+         *       the accepted submission. The read then answers `410` at once.
+         *
+         *     After that window the read answers `410 conversation_expired`, from a tombstone that keeps no answers (see `docs/conversation-state.md`). An unknown or erased conversation, or one of another tenant or environment, is `404 not_found`.
+         */
+        get: operations["getConversation"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getSession"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/revoke": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["revokeSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/client_secret": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * A fresh client secret for an open session
+         * @description A service key with the `sessions:write` scope gets a new connect secret for an open session, for an app that missed the connect window or connects from another device (whose connection then replaces the open one, with close code 4409). The previous secret no longer authenticates a new connection or an SSE turn. A socket already open stays open and keeps its session: refreshing never drops the person's live connection. To cut it off, revoke the session (`revokeSession`). An ended session is `409 session_closed`.
+         */
+        post: operations["refreshClientSecret"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/turns": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run one turn and stream its events as SSE (alternative to the WebSocket)
+         * @description Browsers and WebViews (v1-draft.18): the preflight (`OPTIONS`) is answered for the tenant's client origins of the session's environment only (admin-v1 `ClientOrigins.effective`), with `Access-Control-Allow-Origin` the request's origin (never `*`), `Vary: Origin`, `Access-Control-Allow-Methods: POST`, `Access-Control-Allow-Headers: Authorization, Content-Type` and `Access-Control-Max-Age: 600`; no credentials mode is needed (the client secret is a header). Any other origin, or a session that does not exist, gets no CORS headers. A request whose `Origin` is not one of them is refused with `403` `forbidden` and runs nothing; a request with no `Origin` (a native app, a server) is not checked.
+         */
+        post: operations["createTurnSse"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/sessions/{session_id}/turns/{turn_id}/actions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Send a card action and stream the resulting turn as SSE
+         * @description Browsers and WebViews (v1-draft.18), as for `createTurnSse`: the preflight (`OPTIONS`) is answered for the tenant's client origins of the session's environment only (admin-v1 `ClientOrigins.effective`), with `Access-Control-Allow-Origin` the request's origin (never `*`), `Vary: Origin`, `Access-Control-Allow-Methods: POST`, `Access-Control-Allow-Headers: Authorization, Content-Type` and `Access-Control-Max-Age: 600`; no credentials mode is needed (the client secret is a header). Any other origin, or a session that does not exist, gets no CORS headers. A request whose `Origin` is not one of them is refused with `403` `forbidden` and runs nothing; a request with no `Origin` (a native app, a server) is not checked.
+         */
+        post: operations["createCardActionSse"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/moderation/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["createModerationJob"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/moderation/jobs/{job_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getModerationJob"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/moderation/items/{item_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getModerationItem"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/avatars/{avatar_file}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * An agent's avatar image (v1-draft.19), as `Session.agent.avatar_url` names it
+         * @description Public: no credential, since an app draws it in an image view. Only an avatar that passed the screen is served, and only while it is an agent's current or previous avatar of the last 30 days; anything else is `404`. The bytes never change under a name (`Cache-Control: public, max-age=31536000, immutable`), and the response is `image/webp` with `X-Content-Type-Options: nosniff` and a sandboxing `Content-Security-Policy`.
+         */
+        get: operations["getAgentAvatarImage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listMediaJobs"];
+        put?: never;
+        /**
+         * @description Queue a media job. `moderate` is required; `transcode`, `poster` and `captions` are optional (video only)
+         *     and write to the tenant's destination under `<prefix>/<job id>/`. Same tenant, same `media.sha256`, same
+         *     steps and same policy version within 30 days returns the earlier completed job with `200` and
+         *     `deduplicated: true`, not charged; `force: true` reprocesses. When the expected wait exceeds the tenant's
+         *     soft limit the job is accepted with `delayed: true` and a later `estimated_completion_at`; past the hard
+         *     limit the request is refused with `429` and `Retry-After`.
+         */
+        post: operations["createMediaJob"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/jobs/{job_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getMediaJob"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/jobs/{job_id}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Stops the job at the next step boundary (within seconds) and deletes outputs already written. Idempotent:
+         *     cancelling an ended job returns it unchanged.
+         */
+        post: operations["cancelMediaJob"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/media/profiles": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listMediaProfiles"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/screening/text": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["screenText"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/document-checks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["createDocumentCheck"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/document-checks/{check_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Fields are present only within 24 hours of completion; afterwards only flags remain. */
+        get: operations["getDocumentCheck"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["sendFeedback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/subjects/{subject_id}/erase": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Erases the subject's data: transcripts, screening texts, memory, indexes, the conversation state of its guided flows (recorded answers, remarks, transcript), and the explore suggestion decisions made for it, and revokes its open sessions. `subject.erased` follows.
+         *     **A subject Vinaverse holds nothing for** (never seen, or already erased) is `404` with `code: not_found` and `type: https://docs.vinaverse.com/problems/subject-not-found`; a client matches on the `type` ending in `/problems/subject-not-found`. Only that answer means nothing is held, and nothing needs erasing. Vinaverse keeps no record of erased subjects to tell the two apart. Any other `404` (a wrong base URL, say) is not that answer, and the caller retries.
+         */
+        post: operations["eraseSubject"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Contract §13.1. Each event must validate against its type's JSON Schema in the event catalogue (`contracts/events/beauty_marketplace@1/`); one invalid event rejects the call. */
+        post: operations["sendEvents"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/knowledge/documents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["sendKnowledgeDocument"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/catalog/{type}/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put: operations["putCatalogEntity"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["getUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
-
 interface components {
     schemas: {
         Problem: {
@@ -1874,20 +2119,796 @@ interface components {
             };
         };
     };
-    parameters: {
-        IdempotencyKey: string;
-        MediaJobId: string;
-        ConversationId: components["schemas"]["ConversationId"];
-        SessionId: string;
-    };
-    requestBodies: never;
-    headers: {
-        /** @description Vinaverse-Request-Id */
-        RequestId: string;
+    parameters: {
+        IdempotencyKey: string;
+        MediaJobId: string;
+        ConversationId: components["schemas"]["ConversationId"];
+        SessionId: string;
+    };
+    requestBodies: never;
+    headers: {
+        /** @description Vinaverse-Request-Id */
+        RequestId: string;
+    };
+    pathItems: never;
+}
+interface operations {
+    createSession: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SessionCreate"];
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Session"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    createSuggestions: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SuggestionsRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestionsResponse"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    getConversation: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationState"] & unknown;
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+        };
+    };
+    getSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionStatus"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    revokeSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Revoked (idempotent) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionStatus"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    refreshClientSecret: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ClientSecret"];
+                };
+            };
+            409: components["responses"]["Problem"];
+        };
+    };
+    createTurnSse: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TurnInput"];
+            };
+        };
+        responses: {
+            /** @description `text/event-stream`. Each event's `event:` is a ServerEvent `type`; `data:` is the ServerEvent JSON. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": string;
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    createCardActionSse: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+                turn_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    card_id: string;
+                    action: string;
+                    /** @description as on the WebSocket `ui.action`; required for a proposal outcome and for `select_slot` (the server refuses either without it) */
+                    client_event_id?: string;
+                    /** @description `select_slot` only (v1-draft.17): the slot picked, as on the WebSocket `ui.action` */
+                    slot?: components["schemas"]["SlotSelection"];
+                };
+            };
+        };
+        responses: {
+            /** @description `text/event-stream` as for createTurnSse */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": string;
+                };
+            };
+            403: components["responses"]["Problem"];
+        };
+    };
+    createModerationJob: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ModerationJobCreate"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ModerationJob"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            413: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getModerationJob: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                job_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ModerationJob"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    getModerationItem: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                item_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ModerationItem"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    getAgentAvatarImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description the SHA-256 of the image's bytes, its first 32 hex digits, then `.webp` */
+                avatar_file: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description the image */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "image/webp": string;
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    listMediaJobs: {
+        parameters: {
+            query?: {
+                ref?: string;
+                status?: "queued" | "processing" | "completed" | "failed" | "cancelled";
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Newest first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["MediaJob"][];
+                        next_cursor: string | null;
+                    };
+                };
+            };
+        };
+    };
+    createMediaJob: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MediaJobCreate"];
+            };
+        };
+        responses: {
+            /** @description The same content was processed with the same steps and policy in the last 30 days. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJobCreated"];
+                };
+            };
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJobCreated"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+            413: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getMediaJob: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                job_id: components["parameters"]["MediaJobId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJob"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    cancelMediaJob: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                job_id: components["parameters"]["MediaJobId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The job, `cancelled` (or as it ended). */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MediaJob"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    listMediaProfiles: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The transcoding profiles, named and versioned. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["MediaProfile"][];
+                    };
+                };
+            };
+        };
+    };
+    screenText: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ScreeningRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ScreeningResponse"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    createDocumentCheck: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DocumentCheckCreate"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        id: string;
+                        /** @enum {string} */
+                        status: "queued";
+                        estimated_completion_seconds?: number;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    getDocumentCheck: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                check_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DocumentCheck"];
+                };
+            };
+            404: components["responses"]["Problem"];
+        };
+    };
+    sendFeedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedbackBatch"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        accepted: number;
+                        rejected: {
+                            index: number;
+                            code: string;
+                            detail?: string;
+                        }[];
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+        };
+    };
+    eraseSubject: {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path: {
+                subject_id: components["schemas"]["SubjectId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Accepted; `subject.erased` follows */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        subject_id: components["schemas"]["SubjectId"];
+                        /** @enum {string} */
+                        status: "accepted" | "completed";
+                        sessions_revoked: number;
+                        /** Format: date-time */
+                        deadline: string;
+                    };
+                };
+            };
+            /** @description Nothing held for the subject (never seen, or already erased); the problem's `type` ends in `/problems/subject-not-found` */
+            404: {
+                headers: {
+                    "Vinaverse-Request-Id": components["headers"]["RequestId"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["Problem"] & {
+                        /** @constant */
+                        code?: "not_found";
+                        type?: unknown;
+                    };
+                };
+            };
+        };
+    };
+    sendEvents: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    events: components["schemas"]["Event"][];
+                };
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        accepted: number;
+                        duplicates: number;
+                        batch_id: string;
+                        batch_cid: string;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            429: components["responses"]["RateLimited"];
+        };
+    };
+    sendKnowledgeDocument: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    doc_id: string;
+                    version: string;
+                    title: string;
+                    /** @description Markdown */
+                    body: string;
+                    /** @enum {string} */
+                    audience: "public" | "staff";
+                    /** @default en */
+                    language?: string;
+                    /** Format: uri */
+                    url?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Same version and body already stored (no change) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Stored */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        doc_id: string;
+                        version: string;
+                        audience: string;
+                        artifact_cid: string;
+                        chunks: number;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+        };
+    };
+    putCatalogEntity: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                type: "professional" | "workspace" | "service_type" | "area";
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    name?: string;
+                    display_name?: string;
+                    title?: string;
+                    service_type_ids?: string[];
+                    area?: {
+                        city?: string;
+                        neighborhood?: string;
+                    };
+                    /** @default true */
+                    active?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Stored or unchanged */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        type: string;
+                        id: string;
+                        changed: boolean;
+                        snapshot_cid: string | null;
+                    };
+                };
+            };
+            400: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+        };
+    };
+    getUsage: {
+        parameters: {
+            query?: {
+                period?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UsageReport"];
+                };
+            };
+        };
     };
-    pathItems: never;
 }
 
+/** Every schema of the pinned public contract (vinaverse-v1), by name: `Schemas['Session']`, `Schemas['Card']`, … */
 type Schemas = components['schemas'];
 type ClientEvent = Schemas['ClientEvent'];
 type ServerEvent = Schemas['ServerEvent'];
@@ -1919,6 +2940,246 @@ declare function isKnownCard(card: {
     kind: string;
 }): card is Card;
 
+/** A frame as received or sent: its `type`, and whatever else the contract gives it. */
+interface Frame {
+    readonly type: string;
+    readonly [field: string]: unknown;
+}
+/** A card as the app holds it. `locked` lists the question ids (the card's, or a `rate_each` row's) drawn locked. */
+interface HeldCard {
+    readonly id: string;
+    readonly kind: string;
+    readonly card: Readonly<Record<string, unknown>>;
+    readonly question?: HeldQuestion;
+    readonly locked: readonly string[];
+    /** The turn that drew the card, when known: `ui.action` names it with the card's `id`. */
+    readonly turnId?: string;
+    /** A proposal's first reported outcome (`confirmed`, `declined`, `failed`, `expired`); later ones change nothing. */
+    readonly outcome?: string | null;
+    /** Arrival order, shared with messages: a timeline sorts both by it. Moves when the card is drawn again. */
+    readonly seq: number;
+}
+interface HeldQuestion {
+    readonly question_id: string;
+    readonly kind: string;
+    readonly state: string;
+    readonly answer?: unknown;
+    readonly row_answers?: readonly {
+        question_id: string;
+        answer: unknown;
+    }[];
+    readonly rows?: readonly {
+        question_id: string;
+    }[];
+    readonly [field: string]: unknown;
+}
+interface Message {
+    readonly role: 'assistant' | 'person' | 'staff' | (string & {});
+    readonly text: string;
+    /**
+     * Stable for the message's life, to key it in a list: a person's text by its `client_event_id`, an agent's reply by
+     * its turn (`a:<turn_id>`), a staff reply by its `message_id` (`s:<id>`), a guardrail refusal by the input it answers
+     * (`r:<client_event_id>`), a transcript item by its server `id` as the live key it matches, or by its time and role
+     * (`t:<at>:<role>`) from a server that sends no `id`.
+     */
+    readonly key: string;
+    /** Arrival order, shared with cards: a timeline sorts both by it. */
+    readonly seq: number;
+    /**
+     * A reply cut off after some of it streamed; what streamed stands (§6): `blocked` (`output_blocked`), `interrupted`
+     * (`cancelled`, as when a person from the business takes over, or the connection dropped), `failed` (any other code).
+     */
+    readonly partial?: 'blocked' | 'interrupted' | 'failed';
+    /** A person's text recorded during a takeover (`input.received`): the business reads it; no agent turn runs. */
+    readonly received?: true;
+    /** The agent's reply is a guardrail refusal (`input.rejected` `guardrail`, its `message`). */
+    readonly refusal?: true;
+}
+/** A person from the business is replying (`takeover.started`); `by` is their role as the person sees it. */
+interface Takeover {
+    readonly by: string | null;
+    readonly at: string;
+}
+/** The turn's text streamed so far (`message.delta`), until its `message.completed`. */
+interface Streaming {
+    readonly turnId: string;
+    readonly text: string;
+    /** Taken at the turn's first delta, and kept by its message: a reply sorts before the cards its turn drew after it. */
+    readonly seq: number;
+}
+interface Connection {
+    readonly name: string;
+    readonly state: 'open' | 'closed';
+    readonly code?: number;
+    readonly reason?: string;
+}
+interface ToolLine {
+    readonly turn_id: string;
+    readonly label: string;
+    readonly state: string;
+}
+/**
+ * Whether and how the conversation goes on after a connection ends:
+ * - `allowed`: reconnect to the same session;
+ * - `user_action_only`: the session was revoked or replaced (the conversation continued elsewhere): resume only when
+ *   the person asks;
+ * - `new_session_on_next_action`: the session ended (idle, expired, limit_reached) but the conversation did not; its
+ *   secret is spent. On the person's next action, the app has its backend create a new session for the same
+ *   conversation and calls `resume()`.
+ */
+type Reconnect = 'allowed' | 'user_action_only' | 'new_session_on_next_action';
+/** The engine's whole state, for an app to draw. */
+interface ConversationState {
+    readonly sessionId: string | null;
+    readonly conversationId: string | null;
+    readonly connection: Connection | null;
+    /** How the conversation goes on after the connection ends (`Reconnect`). */
+    readonly reconnect: Reconnect;
+    readonly messages: readonly Message[];
+    /** Every card held, oldest first. */
+    readonly cards: readonly HeldCard[];
+    /** The newest question card still open: the one to answer. */
+    readonly openQuestion: string | null;
+    /** Events sent and neither acknowledged nor refused, by `client_event_id`: resend them, same id, after a reconnect. */
+    readonly unacknowledged: readonly Frame[];
+    /** Ids refused for now (`turn_in_progress`, `screen_unavailable`): send again with the same id. */
+    readonly resend: readonly string[];
+    /**
+     * Texts and answers refused with `limit_reached`: never resent in this session (it would get the same refusal);
+     * resent, same id, on the next session's `session.ready`. Kept apart from `resend` (conformance README, `held`). A
+     * refused action is dropped: a new session cannot act on an earlier session's card.
+     */
+    readonly held: readonly string[];
+    /** Typed messages whose refusal stands, by `client_event_id`: shown as not sent, never resent. */
+    readonly refused: Readonly<Record<string, string>>;
+    /** The last `flow.completed`: `ok`, `refused` or `failed` (an unknown result reads as `failed`). */
+    readonly flow: {
+        readonly flow: unknown;
+        readonly result: 'ok' | 'refused' | 'failed';
+    } | null;
+    /** The turn in progress. */
+    readonly turn: string | null;
+    /** The last state of each tool line (the last 100). */
+    readonly tools: readonly ToolLine[];
+    readonly handoffs: readonly unknown[];
+    /** The codes of `error` and `turn.failed` events (the last 100). */
+    readonly errors: readonly string[];
+    /**
+     * While `reconnect` is `new_session_on_next_action`: the `client_event_id`s held for the next session (unacknowledged,
+     * or refused for this session's turn limit). Draw them as "sends when you continue", not as failed. Empty otherwise.
+     */
+    readonly heldForNextSession: readonly string[];
+    /** Seconds left when `session.expiring` arrived (WebSocket only, about a minute before the end); null otherwise. */
+    readonly expiring: number | null;
+    /** The turn's text streamed so far, until its `message.completed` (or its end, which keeps it as a message). */
+    readonly streaming: Streaming | null;
+    /** While a person from the business replies (§8): from `takeover.started` to `takeover.ended`. */
+    readonly takeover: Takeover | null;
+    /** Every refusal's code and `message` (`input.rejected`), by `client_event_id`; `refused` lists those that stand. */
+    readonly rejections: Readonly<Record<string, {
+        code: string;
+        message: string;
+    }>>;
+    /** The AI disclosure `session.ready` carries: always shown, never removed. Null until the first one. */
+    readonly disclosure: string | null;
+    /** `session.ready`'s `limits.turns_left`, when given. */
+    readonly turnsLeft: number | null;
+}
+declare class ConversationEngine {
+    private sessionId;
+    private conversationId;
+    private connection;
+    private reconnect;
+    private messages;
+    private cards;
+    private unacknowledged;
+    private resend;
+    private held;
+    private refused;
+    private flow;
+    private turn;
+    private tools;
+    private handoffs;
+    private errors;
+    private expiring;
+    private streaming;
+    private takeover;
+    private rejections;
+    private disclosure;
+    private turnsLeft;
+    /** The next arrival number for a message or a card. */
+    private seq;
+    /** The cards drawn before a resumed flow's transcript replaced them: proposal outcomes carry over. */
+    private replaced;
+    /** client_event_id → the first event the app sent under it, until it is settled. */
+    private readonly inputs;
+    /** The tenant's backend created a session (and named its conversation). */
+    sessionCreated(sessionId: string, conversationId?: string | null): void;
+    /** A connection opened: the user's own action, or an allowed reconnect, so it lifts a hold on reconnecting. */
+    connected(name: string): void;
+    /** A connection closed with its code. `4403` (revoked) and `4409` (replaced) hold reconnecting for a user action. */
+    closed(name: string, code: number): void;
+    /** The app was killed: what it drew is gone; what it sent and never saw acknowledged it kept, to resend. */
+    killed(): void;
+    sent(event: Frame): void;
+    received(event: Frame): void;
+    private ready;
+    /**
+     * A transcript merged by key: an item the app holds keeps its place, with the text the server recorded; one it does
+     * not hold goes just after the nearest earlier item it does (just before the first later one when none came before,
+     * at the end when it holds none of them). Nothing the app holds is dropped.
+     */
+    private mergeTranscript;
+    private hold;
+    private recorded;
+    private rejected;
+    private inputRejected;
+    /** No longer to resend, nor held for the next session (sent again, or settled). */
+    private unqueue;
+    /** An input acknowledged or refused for good: nothing more is resent under its id. */
+    private settle;
+    /** Adds a message once: a key already held (a frame seen twice) changes nothing. */
+    private say;
+    /** The turn's streamed text, kept as the agent's message when the turn ends without its `message.completed`. */
+    private cutOff;
+    private error;
+    /**
+     * An input that could not be delivered, or whose retries are spent (`screen_unavailable` after the last try): it is
+     * no longer resent. A typed message is shown as not sent, with `code`; an answer's question unlocks so the person
+     * can answer again; a proposal outcome it reported is taken back, so it can be reported again.
+     */
+    giveUp(clientEventId: string, code: string): void;
+    /** A turn the app stopped where no event will say so (an SSE turn cancelled): none is in progress. */
+    turnEnded(): void;
+    /** The event first sent under a `client_event_id`, to resend it unchanged. */
+    input(clientEventId: string): Frame | undefined;
+    state(): ConversationState;
+}
+
+/** Why the client refused to do something; `code` is stable, `message` is for people. */
+type ClientErrorCode = 
+/** A service key (`vv_sk_`) was given: it belongs on the tenant's backend, never in an app. */
+'service_key'
+/** The value is not a client secret (`vv_cs_` and at least 16 base64url characters). */
+ | 'invalid_secret'
+/** The action needs the WebSocket (answers to question cards); the session runs over SSE. */
+ | 'needs_websocket'
+/** The session was closed by the app, or ended for good (replaced, revoked, expired). */
+ | 'session_ended'
+/** An SSE request failed: `status` holds the HTTP status. */
+ | 'http_error'
+/**
+ * The session ended but the conversation did not (idle, expired, its turn limit): its secret is spent. Have your
+ * backend create a new session for the conversation and call `resume()` with it.
+ */
+ | 'needs_new_session';
+declare class VinaverseClientError extends Error {
+    readonly name = "VinaverseClientError";
+    readonly code: ClientErrorCode;
+    readonly status: number | undefined;
+    constructor(code: ClientErrorCode, message: string, status?: number);
+}
+
 type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
 /** One SSE request: where and with which secret, and the `fetch` to use. */
 interface SseTarget {
@@ -2148,4 +3409,4 @@ declare class VinaverseSession {
     private emit;
 }
 
-export { type AnswerInput as A, type WebSocketFactory as B, type ClientSecret as C, type WebSocketLike as D, cardActionSse as E, type FetchLike as F, sseFrames as G, type HeldCard as H, turnSse as I, 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 Welcome as W, type SessionOptions as a, CONTRACT as b, type Card as c, type CardGroup as d, type CardImage as e, type CardKind as f, type CardLink as g, type ClientErrorCode as h, type HeldQuestion as i, type Proposal as j, isKnownCard as k, type AuthMode as l, type ClientEvent as m, type Connection as n, ConversationEngine as o, type ConversationState as p, type Frame as q, type ServerEvent as r, type ServerEventOf as s, type ServerEventType as t, type SessionEvents as u, type SessionStatus as v, type SseTarget as w, type TranscriptItem as x, type TurnInput as y, VinaverseSession as z };
+export { type AnswerInput as A, type WebSocketFactory as B, type CardLink as C, type WebSocketLike as D, cardActionSse as E, type FetchLike as F, type components as G, type HeldCard as H, type operations as I, type paths as J, sseFrames as K, turnSse as L, type Message as M, type Proposal as P, type Question as Q, type Reconnect as R, type Schemas as S, type ToolLine as T, VinaverseClientError as V, type Welcome as W, type Card as a, type CardGroup as b, type CardImage as c, type CardKind as d, type ClientErrorCode as e, type HeldQuestion as f, type ProposalOutcome as g, type AuthMode as h, isKnownCard as i, type ClientEvent as j, type ClientSecret as k, type Connection as l, ConversationEngine as m, type ConversationState as n, type Frame as o, type ServerEvent as p, type ServerEventOf as q, type ServerEventType as r, type SessionEvents as s, type SessionInfo as t, type SessionOptions as u, type SessionStatus as v, type SseTarget as w, type TranscriptItem as x, type TurnInput as y, VinaverseSession as z };