@vinaverse/server 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/{vinaverse-v1.d-BVc4uyUd.d.cts → vinaverse-v1.d-D-NPpZqW.d.cts}

@@ -15,11 +15,17 @@ interface paths {
         put?: never;
         /**
          * Create an agent session for one subject
-         * @description A session belongs to a conversation when it names one (`conversation_key`, `conversation_id`, or both) or when its agent runs a guided flow; a flow session that names none starts a new conversation. `Session` then returns its `conversation_id`, and a conversation started without a key can later be resumed by that id. A conversation is scoped to the tenant, the environment, the `subject.id` and the `agent`; `subject.type` is not part of it, so a guest who signs in keeps the conversation.
+         * @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`.
+         *     **`business_bookings` and `payouts`.** Like `business_setup`, 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` (v1-draft.38).
+         *     **`quotes`** (v1-draft.31). The `quotes` capability is never for a `guest`: a cart is priced for a signed-in person. Asked for a guest, 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`: `404 not_found`.
+         *        `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,
@@ -69,6 +75,30 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/conversations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * A person's past conversations with one agent, newest activity first
+         * @description v1-draft.21 (VIN-246): the conversations a history screen lists, for one subject and one agent, on one side of the app (`experience_mode`, and for a business `business_scope_id`, as the conversation was bound when it started). Newest activity first; ties by `id`.
+         *     **Access.** A service key only, never a client secret: the app asks the tenant's backend, which checks the person and calls this. The key needs `conversations:read` (a key without scopes has every scope) and sees its own tenant and environment only.
+         *     **What is listed.** Only what the tenant's `transcript_retention` still keeps: a conversation past it, a deleted one (`deleteConversation`) or an erased subject's is never listed, nor one where nothing was said (a session opened and left). A subject Vinaverse holds nothing for gets an empty page, the same as one with no conversations, so the answer never says whether a subject exists.
+         *     **The title** is deterministic and never the person's words: from the conversation's last search intent (`title_source: intent`, for example "Haircut · Los Angeles", in the subject's locale), else the date it started (`title_source: date`). There is no preview of the messages.
+         *     **Paging.** `next_cursor` is opaque and signed. It is bound to the filters, the key's tenant and environment, and expires after 24 hours: a cursor changed, used with other filters or expired is `400 invalid_request` at `/cursor`, and the caller starts again without it. An outage is `503 unavailable` (retryable), never an empty page: the app does not take it as "no conversations".
+         */
+        get: operations["listConversations"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/conversations/{conversation_id}": {
         parameters: {
             query?: never;
@@ -91,6 +121,42 @@ interface paths {
         get: operations["getConversation"];
         put?: never;
         post?: never;
+        /**
+         * Delete one of a person's conversations, everywhere
+         * @description v1-draft.21 (VIN-246): the person deletes a conversation from their history, through the tenant's backend. A service key with `conversations:write`, for its own tenant and environment; `subject_id` must be the conversation's subject.
+         *     **What it does, before it answers.** - Ends the conversation's open sessions: their sockets get `session.closed` with `reason: deleted` and
+         *       close with `4403` (a client that does not know `deleted` reads it as `revoked`). Their status ends as
+         *       `deleted`.
+         *     - Blanks every copy of the conversation's messages, cards, screening texts and state (and the guided flow's
+         *       answers), across both sides of the app, and leaves no title or count behind.
+         *     - Fences late writes: a turn still running, a webhook retry or a worker job that finishes after the delete
+         *       records nothing for it (a deletion barrier, kept as long as the longest session could run).
+         *     - Frees its `conversation_key`: a session with the same key afterwards starts a new conversation.
+         *     **Answers.** `200` with the number of sessions revoked. An unknown id, another tenant's, environment's or subject's, one bound to another `agent`, side or business than the call names (v1-draft.24), or one already deleted or erased: `404 not_found`, the same answer for each, so it never says whether the conversation exists. Deleting is not erasing the subject (`eraseSubject`): the person's other conversations and memory stay.
+         */
+        delete: operations["deleteConversation"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/conversations/{conversation_id}/messages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * One past conversation, as one ordered timeline of messages and cards
+         * @description v1-draft.21 (VIN-246): what a history screen draws when the person opens a past conversation. A service key with `conversations:read`, for its own tenant and environment; `subject_id` must be the conversation's subject.
+         *     **The timeline.** One list of messages and the cards their turns drew, in the order they happened, each with an `id` that is stable and unique within the conversation. The first page is the newest; within a page, oldest first; `next_cursor` pages toward older items. A message carries `event_id`, the identifier its live event gave it (as `TranscriptItem.id`: an `assistant` message's `turn_id`, a `person` message's `client_event_id`, a `staff` message's `message_id`), so an app merges what it drew live, or a resumed `session.ready.transcript`, into the fetched history by `role` and `event_id` instead of replacing either. An input the runtime never recorded is not in it, as in the transcript.
+         *     **Cards from history are read-only.** An app draws their actions disabled: a past slot, price or availability is not checked again, so a tap would act on stale data. The person asks again in the conversation, and a fresh turn draws fresh cards.
+         *     **What is kept.** Only what the tenant's `transcript_retention` still keeps; a conversation past it is `410 conversation_expired`. An unknown id, another tenant's, environment's or subject's, or a deleted or erased one, or one bound to another `agent`, side or business than the call names (v1-draft.24): `404 not_found`, the same answer for each. A cursor changed, used for another conversation or expired (24 hours) is `400 invalid_request` at `/cursor`. An outage is `503 unavailable`, never an empty timeline.
+         */
+        get: operations["listConversationMessages"];
+        put?: never;
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
@@ -113,6 +179,28 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/sessions/{session_id}/context": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Tell an open session where the person is now
+         * @description v1-draft.23 (VIN-115): the person moved to another screen while the chat is open; the tenant's backend, which checked that they may see what is on it, says so, and the session keeps going (no new session per navigation). A service key with `sessions:write`, for the session's own tenant and environment: another tenant's or an unknown session is `404 not_found`, an ended one `409 session_closed`.
+         *     **The body** is a `ScreenContext` (the same type and rules as on `createSession`: a fixed vocabulary, typed filters, never page text, and it grants nothing), or `{clear: true, revision}` when the person left any screen that says something (the agent then has no screen context). Either way `revision` must be greater than the session's: the tenant's own counter for this person's screen, so a late update never overwrites a newer one. An older or equal revision is `409 context_stale` with `current_revision`, except the same revision with the same body, which is a retry and answered `200` as the first time.
+         *     **What follows.** The session's open socket gets `context.updated` (the revision, and `cleared: true` after a clear). A turn already running keeps the context it started with; the next turn reads the new one, as data in the turn's details, never in the cached prompt.
+         */
+        put: operations["updateSessionContext"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/sessions/{session_id}/revoke": {
         parameters: {
             query?: never;
@@ -140,7 +228,7 @@ interface paths {
         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`.
+         * @description A service key with the `sessions:write` scope gets a new connect secret for an open session, for an app that missed the connect window or connects from another device (whose connection then replaces the open one, with close code 4409). The previous secret no longer authenticates a new connection or an SSE turn. A socket already open stays open and keeps its session: refreshing never drops the person's live connection. To cut it off, revoke the session (`revokeSession`). An ended session is `409 session_closed`. With an optional `Idempotency-Key` (declared in v1-draft.22), a retry within 24 hours answers the secret first issued for that key instead of a newer one.
          */
         post: operations["refreshClientSecret"];
         delete?: never;
@@ -158,7 +246,10 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Run one turn and stream its events as SSE (alternative to the WebSocket) */
+        /**
+         * 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;
@@ -175,7 +266,10 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Send a card action and stream the resulting turn as SSE */
+        /**
+         * 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;
@@ -231,6 +325,26 @@ interface paths {
         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;
@@ -382,7 +496,8 @@ interface paths {
         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.
+         * @description Erases the subject's data: transcripts, screening texts, memory (v1-draft.27: the preferences and the last search; a choice not to be remembered is kept, as a keyed hash of the subject id only), 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.
+         *     Backups are not edited (v1-draft.39): the erasure is re-applied after every restore of Vinaverse's database, so a backup never brings it back, and backups expire within 35 days.
          *     **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"];
@@ -392,6 +507,79 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/subjects/{subject_id}/memory": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * What the agent remembers about a person, and whether it may
+         * @description v1-draft.27 (VIN-223): what Vinaverse keeps to remember a person across conversations, so the tenant's app can show it to them. A service key with `memory:read`, for its own tenant and environment; the app asks the tenant's backend, never with a client secret.
+         *     **What is kept, and nothing else.** - `remembered`: whether the person lets the agent remember them (on by default; `putSubjectMemory` turns it
+         *       off for both sides of the app).
+         *     - `notice_acknowledged`: the version of the memory notice the person acknowledged, if any. - `preferences`: what the person asked the agent to remember, in the words the agent said back to the
+         *       person, each with the conversation it came from. Never inferred from what they viewed or booked. Never a
+         *       health fact or a never-store detail (v1-draft.39); a fact about someone else is the person's own note.
+         *     - `last_search`: the last open search intent (a service and a place, as the search resolved them, never the
+         *       person's words), for at most 7 days, which the agent may offer as a question.
+         *
+         *     Preferences and the last search belong to one side of the app: `experience_mode` (left out, `customer`) and, for a business, `business_scope_id`. A subject Vinaverse holds nothing for reads as remembered, with nothing kept. Erasing the subject (`eraseSubject`) removes preferences and the last search; a choice not to be remembered outlives it, kept as a keyed hash of the subject id only.
+         */
+        get: operations["getSubjectMemory"];
+        /**
+         * Let the agent remember a person, or not
+         * @description v1-draft.27 (VIN-223): the person's choice, through the tenant's backend (a service key with `memory:write`). `remembered: false` is "don't remember me": on both sides of the app at once, it deletes the preferences and the last search, and from then on no session reads or writes memory for the person and no earlier conversation is mentioned to the agent. It outlives an erasure. `remembered: true` turns memory back on, with nothing restored. Idempotent: the same choice again changes nothing.
+         */
+        put: operations["putSubjectMemory"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/subjects/{subject_id}/memory/notice": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * The person saw the memory notice
+         * @description v1-draft.27 (VIN-223): the app showed `Session.memory.notice` and the person dismissed it; the tenant's backend records that (a service key with `memory:write`), so no later session carries that version. A newer version is shown again. `version` must be the current notice's (`400` at `/version` otherwise). Idempotent.
+         */
+        post: operations["acknowledgeMemoryNotice"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/subjects/{subject_id}/memory/preferences/{preference_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Forget one thing the person asked the agent to remember
+         * @description v1-draft.27 (VIN-223): a service key with `memory:write`. The preference is deleted everywhere; the agent no longer reads it from the next turn. Another subject's, an unknown or an already deleted preference is the same `404 not_found`.
+         */
+        delete: operations["deleteMemoryPreference"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/events": {
         parameters: {
             query?: never;
@@ -441,6 +629,46 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/agents/{agent}/experience": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The chat experience the tenant set for an agent, before any session
+         * @description v1-draft.40 (VIN-115, the chat spec's module G TC-02): what the app needs before a session opens (the launcher, the switcher, history, an Ask row), for the tenant's backend to copy into its agent status (agent-backend `status.features.chat`). A service key with `sessions:write`, for its own tenant and environment. The value is resolved as `Session.experience` is, except for a client's capabilities. Cacheable for 60 seconds: a change in Studio reaches new sessions at once and this read within a minute. An unknown or inactive agent is `404 not_found`.
+         */
+        get: operations["getAgentExperience"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/meta": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The contract version this gateway runs
+         * @description v1-draft.25 (VIN-115): what is deployed behind this base URL. No credential and no tenant: the same answer for everyone, cacheable for 60 seconds. `api_version` is this document's `info.version` as the gateway serves it (the `Vinaverse-Api-Version` response header carries the same); `contracts.commit` is the vinaverse-contracts commit the build pinned. A field the build did not record is absent, never guessed. The gateway's own commit is not served: it would fingerprint the exact deployment for a scanner, and an SDK needs only these two.
+         */
+        get: operations["getMeta"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/usage": {
         parameters: {
             query?: never;
@@ -1177,16 +1405,20 @@ interface webhooks {
 }
 interface components {
     schemas: {
+        /** @description A model as Vinaverse names it (v1-draft.34): a release `<family>@<date>.<n>` (immutable) or a family alias `<family>` or `<family>:<channel>` of a family tenants read (`vina-agent`, the language model; `vina-embed`, the embeddings), or, when no model made a decision, the producer's own id (`vv-detectors`, `mock`). Never a base model, a size, a host or a model server's id. Its display name is the object's `label` (v1-draft.35). */
+        ModelName: string;
         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";
+            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" | "context_stale";
             detail?: string;
             request_id: string;
             retryable: boolean;
+            /** @description v1-draft.23, with `context_stale` only, the session's screen-context revision now */
+            current_revision?: number;
             /** @description field-level problems for invalid_request */
             errors?: {
                 /** @description JSON Pointer into the request */
@@ -1218,6 +1450,7 @@ interface components {
             locale?: string;
             /** @example America/New_York */
             timezone?: string;
+            /** @description the person's coarse area (a profile area or a device's city), never a street; like `ScreenContext.filters.near`, the gateway rounds `lat` and `lng` to 2 decimals on receipt, before either is stored, logged or forwarded to a tool */
             approximate_location?: {
                 lat: number;
                 lng: number;
@@ -1228,10 +1461,10 @@ interface components {
         /** @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.
+         * @description `quotes`: grants pricing a cart before booking it (`tool-provider-v1.yaml` `get_quote`), read only; never granted to a `guest` (v1-draft.31). `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. `business_bookings`: grants reading the business's own bookings, those waiting for its answer and those coming up, read only. `payouts`: grants reading the state of the business's own payout account (not set up, under review, active), read only, never an amount or a bank detail. Only a subject of type `professional`, `host` or `staff` may be granted either (v1-draft.38).
          * @enum {string}
          */
-        Capability: "search" | "availability" | "quotes" | "my_bookings" | "policies" | "handoff" | "flows" | "business_setup" | "booking_proposals" | "my_orders";
+        Capability: "search" | "availability" | "quotes" | "my_bookings" | "policies" | "handoff" | "flows" | "business_setup" | "booking_proposals" | "my_orders" | "business_bookings" | "payouts";
         ToolAccess: {
             token: string;
             /** Format: date-time */
@@ -1349,87 +1582,541 @@ interface components {
             conversation_key?: string;
             /** @description Optional. Resumes the conversation with this id (`Session.conversation_id`, `ConversationState`), as an alternative to `conversation_key` or together with it; `createSession` describes resuming and the order of its checks. */
             conversation_id?: components["schemas"]["ConversationId"];
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            screen_context?: components["schemas"]["ScreenContext"];
+            anchor?: components["schemas"]["SessionAnchor"];
+            client?: components["schemas"]["SessionClient"];
+            entry?: components["schemas"]["SessionEntry"];
         };
-        ClientSecret: {
-            /** @description `vv_cs_` and base64url characters, so the secret is a valid WebSocket subprotocol token in `bearer.<secret>`. */
-            value: string;
+        /**
+         * @description v1-draft.20, optional on `createSession`: the side of the tenant's app the person is on. `customer` for the customer agent (a `client` or `guest`), `business` for a business agent (a `professional`, `host` or `staff`). Left out, it follows the agent's template; `createSession` describes the binding.
+         * @enum {string}
+         */
+        ExperienceMode: "customer" | "business";
+        /** @description v1-draft.20, optional, with `experience_mode: business` only: the business the person acts for, as the tenant's backend knows it (a professional's business, a host's place). Opaque to Vinaverse; it binds the conversation, so a person acting for two businesses keeps two conversations. It never reaches a model prompt. */
+        BusinessScopeId: string;
+        /** @description v1-draft.20, optional on `createSession`: where the person is in the tenant's app when the session opens, as the tenant's backend vouches for it (it checked that the person may see the entity). It grants nothing: no tool, capability or record. The agent reads it as data in its working notes (never in the cached system prompt, never as something the person said), as a hint: before it states anything about the entity it reads it with a tool, and a tool that refuses means the agent says it cannot see it. A screen change while the chat is open does not open a new session: the tenant's backend sends it with `updateSessionContext` (v1-draft.23). Never arbitrary page text, URLs, names, amounts or instructions: only these fields, from this vocabulary. */
+        ScreenContext: {
             /**
-             * 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.
+             * @description A coarse screen from a fixed vocabulary; the tenant maps its own screens onto it. `other` when none fits. Customer side: `home`, `explore`, `search_results`, `professional`, `workspace`, `service`, `class`, `checkout`, `booking`, `bookings`, `inbox`, `profile`. Business side: `business_hub`, `setup`, `services`, `hours`, `location`, `gallery`, `spaces`, `space_manage`, `renters`, `payouts`, `plans`, `team`.
+             * @enum {string}
              */
-            expires_at: string;
-        };
-        Session: {
-            id: string;
-            /** @enum {string} */
-            status: "open";
-            agent: {
+            screen: "home" | "explore" | "search_results" | "professional" | "workspace" | "service" | "class" | "checkout" | "booking" | "bookings" | "inbox" | "profile" | "business_hub" | "setup" | "services" | "hours" | "location" | "gallery" | "spaces" | "space_manage" | "renters" | "payouts" | "plans" | "team" | "other";
+            /** @description the object on the screen, as the tenant's read tools name it; `id` is a tool id (letters, digits and `_`, `.`, `:`, `-`), since it reaches the agent's working notes */
+            entity?: {
+                /** @enum {string} */
+                type: "professional" | "workspace" | "service" | "class" | "booking" | "location";
                 id: string;
-                version: string;
-                display_name: string;
             };
-            client_secret: components["schemas"]["ClientSecret"];
-            /** Format: uri */
-            realtime_url: string;
-            /** Format: uri */
-            turns_url: string;
+            /** @description the filters the screen shows, typed; free text never */
+            filters?: {
+                service_ids?: string[];
+                category_ids?: string[];
+                area_id?: string;
+                /** Format: date */
+                date_from?: string;
+                /** Format: date */
+                date_to?: string;
+                price_max?: components["schemas"]["Money"];
+                /** @description v1-draft.32, the place the person is searching now, as the app shows it ("Billings, MT"); for "near me" it comes after a place named in the message and before `subject.approximate_location`. `lat` and `lng` are rounded to 2 decimals (about a kilometre) or coarser; the gateway never asks for finer, and rounds anything finer it receives (a raw GPS fix, say) to 2 decimals on receipt, before it is stored, logged or forwarded to a tool. */
+                near?: {
+                    lat: number;
+                    lng: number;
+                    /** @description in Unicode code points; quoted to the agent as data */
+                    label: string;
+                    /** @enum {string} */
+                    precision?: "city" | "neighborhood";
+                };
+            };
+            /** @description the tenant's counter for this person's screen state; a later update never goes back to a lower one (v1-draft.23: `updateSessionContext` refuses one that is not greater) */
+            revision: number;
+        };
+        /** @description v1-draft.23: what `updateSessionContext` takes: the person's screen now (`ScreenContext`), or an explicit clear. Both carry the tenant's `revision`, which must be greater than the session's. */
+        SessionContextUpdate: components["schemas"]["ScreenContext"] | {
+            /** @constant */
+            clear: true;
+            revision: number;
+        };
+        /** @description v1-draft.23, the session's screen context after an update; no `screen_context` after a clear */
+        SessionContextState: {
+            revision: number;
+            screen_context?: components["schemas"]["ScreenContext"];
+        };
+        /**
+         * @description v1-draft.37, what a context-started chat is about (`docs/context-started-chats.md`). `booking`: a service booking, the customer's own. `rental`: a space rental, the renter's own. `professional`, `workspace`, `service` and `class`: a published profile, space, service or class. `policy`: a policy or legal page. A closed list: a new type is a contract change.
+         * @enum {string}
+         */
+        AnchorType: "booking" | "rental" | "professional" | "workspace" | "service" | "class" | "policy";
+        /**
+         * @description v1-draft.37, optional on `createSession`: the object a context-started chat is about, as the tenant's backend read it for this person, server to server, with the same authorization and rules as its screen, then reduced by its disclosure policy for agents. Never from client text. Absent: an unanchored session, as before.
+         *     **Evidence and quoted data, never instructions.** The gateway keeps `facts` as evidence entries keyed by the object, the field and `as_of`, so a reply's amounts, money verbs and deadlines are checked against them by meaning. The agent reads the typed facts in the turn's details as quoted data under a protected lead, never as instructions and never in the cached prompt. Free text a professional wrote (a service's `description`, a class's `rules` and `cancellation_terms`) is third-party text: it is instruction-checked before the agent reads it, like a tool result's third-party text, and never decides anything. Its identity (`type`, `id`) never changes for the conversation; its facts are refreshed with the connector's anchor read (admin-v1 `Connector.anchors`).
+         *     **Limits.** At most 4096 bytes as serialized UTF-8 JSON; text fields at most 80 code points, except a `service` or `class` description, rules and cancellation terms, at most 500. An anchor over a limit or malformed is `400 invalid_request` with a pointer under `/anchor`, and the session is not opened. To fit, the tenant trims and marks the anchor `partial`, in this order: lists are cut from their end (a professional's services keep the ones the person can book first; a space's taken days keep the soonest first; a class's sessions the soonest first), then optional fields are left out. It never sends an anchor over the limit.
+         *     **completeness.** `complete`: every field the type's projection allows is present. `partial`: some could not be read; absent fields mean "not known", never zero or "nothing". `unavailable`: the read failed; only `type`, `id`, `title` and `completeness` are present, and the agent names the object from `title`, says its details could not load, and still answers.
+         *     **display** is what the person sees on the anchor card, formatted by the tenant in the person's language as its own screen shows it: an optional `subtitle`, at most four `{label, value}` facts and an optional `deep_link` to the object's screen. It is for the person only and never reaches the model (the model reasons from the typed `facts`). The deep link must pass the deep-link rule (admin-v1 `Connector.deep_link_prefixes`), or it is dropped and the card keeps the rest.
+         *     A `policy` anchor carries its `id` (the page's slug) and `title` only: the text is read through the connector's `get_policy`, never carried in the anchor.
+         */
+        SessionAnchor: {
+            type: components["schemas"]["AnchorType"];
+            /** @description the tenant's object id, the same one its tools accept (a policy's slug for `policy`) */
+            id: string;
+            /** @description the anchor schema version for this `type`, the tenant's */
+            version?: number;
             /**
              * 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`.
+             * @description when the tenant read the object; the source revision of every fact
              */
-            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"];
+            as_of?: string;
+            /** @description the tenant's code for the object's state, from its closed list per `type`. Open in this draft: an unknown value is accepted and gets the generic anchored greeting. The lists are added here, additively, once the tenant's screen-parity check per value is done. */
+            situation?: string;
+            /** @enum {string} */
+            completeness: "complete" | "partial" | "unavailable";
+            /** @description in Unicode code points: "ABZ Fitness Center, Oct 16 to 24"; also the history group title */
+            title: string;
+            /** @description the object's facts, typed per `type` (`BookingFacts`, `RentalFacts`, `ProfessionalFacts`, `WorkspaceFacts`, `ServiceFacts`, `ClassFacts`); none for a `policy`. Only what the tenant's projection for agents allows: a field's presence is a promise, anything not listed is not sent. Absent means "can't be worked out", never zero. */
+            facts?: Record<string, unknown>;
+            /** @description what the person may do or ask about now, each eligible or not; the app draws chips only for ids it knows */
+            intents?: components["schemas"]["AnchorIntent"][];
+            deadlines?: components["schemas"]["AnchorDeadline"][];
+            display?: components["schemas"]["AnchorDisplay"];
+        } & (unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown);
+        /** @description v1-draft.37, the anchor card's display, formatted by the tenant in the person's language, for the person only: it never reaches the model. `deep_link` must pass the deep-link rule, or it is dropped. */
+        AnchorDisplay: {
+            /** @description in Unicode code points */
+            subtitle?: string;
+            facts?: {
+                /** @description in Unicode code points */
+                label: string;
+                /** @description in Unicode code points */
+                value: string;
+            }[];
+            deep_link?: string;
         };
-        SessionStatus: {
-            id: string;
+        /** @description v1-draft.37, one thing the person may do (`action`: a hand-off to the tenant's own screen, `open_action`) or ask (`explain`: answered from the manifest's template, filled from the anchor's facts). Eligibility comes only from here. An ineligible intent carries `reason`, a code; the words a person reads come from the templates. */
+        AnchorIntent: {
+            id: components["schemas"]["IntentId"];
             /** @enum {string} */
-            status: "open" | "closed" | "revoked" | "expired";
-            subject_id: components["schemas"]["SubjectId"];
-            agent_version?: string;
-            turns: number;
-            handoff_ticket_ids?: string[];
+            kind: "action" | "explain";
+            eligible: boolean;
+            /** @description why it is not eligible now, a code (`outside_window`, `not_for_customers`) */
+            reason?: string;
+            /** @description an `action` intent's route, one the connector manifest declares (admin-v1 `Connector.actions.routes`) */
+            route?: string;
+        };
+        /** @description v1-draft.37, a stable intent id (`cancel_rental`, `explain_hold`), the same across languages and builds */
+        IntentId: string;
+        /** @description v1-draft.37, a moment the person must act by, with the zone it is stated in. The sentence gate holds a reply to these: a deadline is said with its zone, in the person's zone too when it differs, and a passed one is never stated as future. */
+        AnchorDeadline: {
             /**
-             * @description Why the session ended. `server_restart` is reserved and never appears here: it never ends a session (`docs/realtime-protocol.md` §2).
+             * @description closed, since the gate's money and deadline rules key on it; this set is proposed (the joint spec names none) and may grow additively. `approval`: the host or professional must answer by then. `payment_due`: an amount is due. `cancel_refund_until`: cancelling before then gets the stated refund. `reschedule_until`: the booking may be moved until then. `deposit_dispute_until`: a deposit claim may be disputed until then. `deposit_return_by`: the deposit is returned by then.
              * @enum {string}
              */
-            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left";
-            /** Format: date-time */
-            created_at: string;
+            kind: "approval" | "payment_due" | "cancel_refund_until" | "reschedule_until" | "deposit_dispute_until" | "deposit_return_by";
             /** Format: date-time */
-            closed_at?: string;
-            usage?: components["schemas"]["Usage"];
-        };
-        TurnInput: {
-            client_event_id?: string;
-            text: string;
+            at: string;
+            /** @description `payment_due` only: what is due by `at` (a booking awaiting the person's payment, a rent due) */
+            amount?: components["schemas"]["Money"];
+            /** @description an IANA time zone: `America/New_York` */
+            zone: 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"];
+        /**
+         * @description v1-draft.37, where the money of a booking or rental is, mapped by the tenant from its own states at its boundary, with a test per value. The money verbs an agent may say follow it: "held, not charged" while `held`; "charged" only when `charged`; "released" only at `release_confirmed`; `due` and `paid_in_person` never said as a card charge.
+         * @enum {string}
+         */
+        PaymentState: "none" | "due" | "held" | "charged" | "paid_in_person" | "release_requested" | "release_confirmed" | "release_failed" | "refund_pending" | "refund_settled" | "partially_refunded" | "refund_failed" | "manual_review";
+        /** @description v1-draft.37, where, as an area only; never the street */
+        AnchorPlace: {
+            area: string;
         };
-        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;
+        AnchorParty: {
+            id?: string;
+            display_name: string;
+        };
+        /** @description v1-draft.37, a service's price per place it is offered at */
+        AnchorPrices: {
+            at_professional?: components["schemas"]["Money"];
+            at_customer?: components["schemas"]["Money"];
+            other?: components["schemas"]["Money"];
+        };
+        /** @description v1-draft.37, a `rental` anchor's facts (joint spec §2.1, with the tenant's review). `amount_held` only while `payment_state` is `held`, `amount_charged` only when it is `charged`; `cancel_now` absent when it cannot be worked out. An amount due is the `payment_due` deadline's `amount`. The renter's licence and insurance are standing codes only (never a scan), and documents and maintenance are counts per state (never contents). */
+        RentalFacts: {
+            /** @description the lease, kept distinct from the rental id */
+            lease_id?: string;
+            space?: {
+                id?: string;
+                name: string;
+                area?: string;
+            };
+            host?: components["schemas"]["AnchorParty"];
+            /** @description the rental's dates; no `end` for an open-ended rental */
+            dates?: {
+                /** Format: date */
+                start: string;
+                /** Format: date */
+                end?: string;
+                zone: string;
+            };
+            total?: components["schemas"]["Money"];
+            deposit?: components["schemas"]["Money"];
+            payment_state?: components["schemas"]["PaymentState"];
+            amount_held?: components["schemas"]["Money"];
+            amount_charged?: components["schemas"]["Money"];
+            /** @description after the rental ends, where its deposit is; the return and dispute rules are the tenant's policy pages */
+            deposit_return?: {
                 /** @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;
-        };
+                state: "being_returned" | "claimed" | "returned" | "disputed";
+                amount_returned?: components["schemas"]["Money"];
+                amount_claimed?: components["schemas"]["Money"];
+            };
+            cancellation?: {
+                /** @enum {string} */
+                by: "you" | "host" | "platform";
+                /** Format: date-time */
+                at: string;
+                reason_category?: string;
+            };
+            /** @description the renter's own, a code (`approved`, `sent`, `missing`) */
+            licence_standing?: string;
+            /** @description the renter's own, a code */
+            insurance_standing?: string;
+            /** @description the rental's documents, counted per state; never their contents */
+            documents?: components["schemas"]["AnchorCount"][];
+            /** @description the rental's maintenance requests, counted per state; never their contents */
+            maintenance?: components["schemas"]["AnchorCount"][];
+            /** @description what cancelling now would give back, and until when those terms hold */
+            cancel_now?: {
+                refund?: components["schemas"]["Money"];
+                deposit_refund?: components["schemas"]["Money"];
+                rent_kept?: components["schemas"]["Money"];
+                /** Format: date-time */
+                until: string;
+            };
+            lease?: {
+                /** @description the lease term, a code (`monthly`, `open_ended`) */
+                term?: string;
+                rate?: components["schemas"]["Money"];
+                /** Format: date */
+                paid_through?: string;
+                /**
+                 * Format: date
+                 * @description the next charge date the tenant shows; not automatic billing
+                 */
+                next_charge?: string;
+            };
+        } & (unknown & unknown);
+        AnchorCount: {
+            state: string;
+            count: number;
+        };
+        /** @description v1-draft.37, a `booking` anchor's facts (joint spec §3.1), named from the spec's prose for the tenant's projection to confirm. `amount_paid` (the money taken, before any refund) only when `payment_state` is `charged`, `paid_in_person` or `partially_refunded`, never for a hold; `amount_refunded` only when it is `partially_refunded`, `refund_pending` or `refund_settled`. An amount due is the `payment_due` deadline's `amount`. No street, support case or free-text note. */
+        BookingFacts: {
+            services?: {
+                name: string;
+                quantity?: number;
+                duration_minutes?: number;
+            }[];
+            professional?: components["schemas"]["AnchorParty"];
+            appointment?: {
+                /** Format: date-time */
+                at: string;
+                zone: string;
+            };
+            place?: components["schemas"]["AnchorPlace"];
+            subtotal?: components["schemas"]["Money"];
+            fees?: components["schemas"]["Money"];
+            total?: components["schemas"]["Money"];
+            payment_state?: components["schemas"]["PaymentState"];
+            amount_paid?: components["schemas"]["Money"];
+            amount_refunded?: components["schemas"]["Money"];
+            deposit_paid?: components["schemas"]["Money"];
+            cancel_now?: {
+                refund?: components["schemas"]["Money"];
+                /** @description cancelling now goes to manual review, so no refund is promised */
+                goes_to_review?: boolean;
+                /** Format: date-time */
+                until: string;
+            };
+            /** @enum {string} */
+            review_state?: "not_eligible" | "eligible" | "reviewed";
+            cancellation?: {
+                /** @enum {string} */
+                by: "you" | "professional" | "platform";
+                /** Format: date-time */
+                at: string;
+                reason_category?: string;
+            };
+        } & (unknown & unknown);
+        /** @description v1-draft.37, a `professional` anchor's facts (joint spec §3.3), named from the spec's prose for the tenant's projection to confirm. A delisted or blocked profile is `situation: unavailable`, never a stale profile. When `display_name` and the anchor's `title` differ, the `title` is what the person is shown. */
+        ProfessionalFacts: {
+            display_name?: string;
+            place?: components["schemas"]["AnchorPlace"];
+            rating?: {
+                value: number;
+                count: number;
+            };
+            services?: {
+                id: string;
+                name: string;
+                duration_minutes?: number;
+                prices?: components["schemas"]["AnchorPrices"];
+            }[];
+            /** @description the next open times for the service the person chose */
+            next_openings?: {
+                service_id: string;
+                /** Format: date-time */
+                at: string;
+                zone: string;
+            }[];
+        };
+        /** @description v1-draft.37, a `workspace` anchor's facts (joint spec §3.4), named from the spec's prose for the tenant's projection to confirm. */
+        WorkspaceFacts: {
+            place?: components["schemas"]["AnchorPlace"];
+            host?: components["schemas"]["AnchorParty"];
+            rates?: {
+                day?: components["schemas"]["Money"];
+                week?: components["schemas"]["Money"];
+                month?: components["schemas"]["Money"];
+            };
+            deposit?: components["schemas"]["Money"];
+            minimum_stay_days?: number;
+            units?: {
+                chairs?: number;
+                suites?: number;
+            };
+            amenities?: string[];
+            /** @description a code (`tour_first`, `no_tour`) */
+            tour_rule?: string;
+            /** @enum {string} */
+            licence_requirement?: "sent" | "approved";
+            insurance_rule?: string;
+            /** @description the days already taken in the next 90, as ranges of whole days (`to` included), soonest first */
+            taken_days?: {
+                /** Format: date */
+                from: string;
+                /** Format: date */
+                to: string;
+            }[];
+        };
+        /** @description v1-draft.37, a `service` anchor's facts (joint spec §3.5), named from the spec's prose for the tenant's projection to confirm. */
+        ServiceFacts: {
+            name?: string;
+            duration_minutes?: number;
+            professional?: {
+                id?: string;
+                display_name: string;
+                area?: string;
+            };
+            prices?: components["schemas"]["AnchorPrices"];
+            offered_at?: ("at_professional" | "at_customer" | "other")[];
+            /** @description written by the professional, so third-party text, instruction-checked before the agent reads it */
+            description?: string;
+        };
+        /** @description v1-draft.37, a `class` anchor's facts (joint spec §3.6), named from the spec's prose for the tenant's projection to confirm. */
+        ClassFacts: {
+            professional?: components["schemas"]["AnchorParty"];
+            place?: components["schemas"]["AnchorPlace"];
+            price_per_seat?: components["schemas"]["Money"];
+            /** @description written by the professional, so third-party text, instruction-checked before the agent reads it */
+            rules?: string;
+            /** @description written by the professional, so third-party text, instruction-checked before the agent reads it */
+            cancellation_terms?: string;
+            sessions?: {
+                /** Format: date-time */
+                at: string;
+                zone: string;
+                seats_left: number;
+                cancelled: boolean;
+            }[];
+        };
+        /** @description v1-draft.37, the anchor as the person and the app see it (`Session.anchor`, `session.ready.anchor`): its identity and state, and the verified `anchor` card the app swaps in for the provisional one it drew from its screen. If a fact the app showed differs, the verified card wins and the app redraws. The same card is the conversation's first timeline item. No `facts`: the card's display strings are what is shown. */
+        SessionAnchorView: {
+            type: components["schemas"]["AnchorType"];
+            id: string;
+            title: string;
+            /** Format: date-time */
+            as_of?: string;
+            situation?: string;
+            /** @enum {string} */
+            completeness: "complete" | "partial" | "unavailable";
+            /** @description the anchor's eligible intents, for the chips (only with the `intents` capability) */
+            intents?: components["schemas"]["AnchorIntent"][];
+            card: components["schemas"]["Card"];
+        };
+        /** @description v1-draft.37, an `anchor` card's body: display only. The object's type, when it was read (absent when the read failed), and the anchor's `display` as the tenant formatted it: at most four facts as display strings and the `deep_link` to the object's screen, which must pass the deep-link rule (admin-v1 `Connector.deep_link_prefixes`); a card whose link fails keeps the card and loses the link. The card's `subtitle` is `display.subtitle`. An anchor with no `display` gets a card with its title and no facts. */
+        AnchorCard: {
+            anchor_type: components["schemas"]["AnchorType"];
+            /** Format: date-time */
+            as_of?: string;
+            facts: {
+                /** @description in Unicode code points */
+                label: string;
+                /** @description in Unicode code points */
+                value: string;
+            }[];
+            deep_link?: string;
+        };
+        /** @description v1-draft.37, an `open_action` card's body: a hand-off to the tenant's own flow for an eligible `action` intent. The app opens `route` with `params`; **opening a screen is never doing the action**. The app reports what happened with `action.result`, echoing `action_id`, and the gateway re-reads the anchor before the agent states the outcome. `action_id` is minted by the gateway, one per hand-off across its retries: the tenant's write keys on it, so a double tap or a network retry is one action. `terms_digest` is the hash of the terms the person was shown; the tenant's write refuses changed terms. A build without the `open_action` capability gets `fallback_link` (the object's screen) as a plain link instead. */
+        OpenAction: {
+            action_id: string;
+            intent: components["schemas"]["IntentId"];
+            /** @description in Unicode code points */
+            label: string;
+            /** @description a route the connector manifest declares (admin-v1 `Connector.actions.routes`) */
+            route: string;
+            /** @description the route's typed params, as its manifest entry declares them: `string` and `id` as strings, `instant` as an RFC 3339 string, `integer` as an integer, `money` as `Money` */
+            params: {
+                [key: string]: string | number | components["schemas"]["Money"];
+            };
+            terms_digest?: string;
+            /** Format: date-time */
+            expires_at: string;
+            /** @description the object's screen; passes the deep-link rule */
+            fallback_link: string;
+        };
+        /** @description v1-draft.37, optional on `createSession`: what the person's app build supports, and the starter chips it showed, as its backend relays them. `shown_intents` are the intent ids of the chips on screen when the chat opened: with the `intent` a tap sends on `input.text`, they tell which chips a person saw and which they tapped. Only the ids are kept. Capabilities: `anchor_card`: it draws an `anchor` card. `intents`: it draws chips from anchor intent ids and sends `intent` on `input.text`. `open_action`: it draws an `open_action` card and opens its route. `action_result`: it sends `action.result` after a hand-off. Open: an unknown value is ignored, never refused. The gateway leaves out what the build lacks: no `open_action` means the action's `fallback_link` as a plain `links` card, no `intents` means the chips come as text, and a build with none still gets the anchored greeting and answers. */
+        SessionClient: {
+            /**
+             * @example [
+             *       "anchor_card",
+             *       "intents",
+             *       "open_action",
+             *       "action_result"
+             *     ]
+             */
+            capabilities?: string[];
+            /** @description the starter chips' intent ids, open like capabilities (an id the session's anchor does not list is kept as given) */
+            shown_intents?: components["schemas"]["IntentId"][];
+        };
+        /** @description v1-draft.37, optional on `createSession`: how the person opened the chat. `point` is an open code: `ask_about` for an explicit "ask about this" on a page (it starts a new conversation anchored to the page's object), and `help`, `launcher`, `inbox`, `history`, `explore` or `setup` for the others; an unknown one is treated as `help`. `label` keeps the app's own word for analytics only: it never reaches a model prompt. */
+        SessionEntry: {
+            /** @example ask_about */
+            point: string;
+            /** @description in Unicode code points */
+            label?: string;
+        };
+        /** @description v1-draft.25, what `getMeta` answers */
+        Meta: {
+            /** @example v1-draft.26 */
+            api_version: string;
+            contracts: {
+                /** @description the vinaverse-contracts commit pinned */
+                commit?: string;
+            };
+        };
+        /** @description v1-draft.20: a tap target the app draws under the welcome. Tapping it sends `message` as the person's own text (an `input.text`, or `createTurnSse`), exactly as if they typed it; it starts nothing else. */
+        Chip: {
+            /** @description in Unicode code points */
+            label: string;
+            /** @description in Unicode code points */
+            message: string;
+        };
+        /** @description v1-draft.20: the tenant's greeting for the session's mode, with the chips of the session's screen when its manifest has some for it (else the mode's own), from the connector manifest (admin-v1 `Connector.welcome`), checked when the manifest loads. The app shows it the moment the session is ready: it costs no model call and is not a turn. The agent knows it was shown and does not greet again. */
+        Welcome: {
+            /** @description in Unicode code points */
+            text: string;
+            chips: components["schemas"]["Chip"][];
+        };
+        ClientSecret: {
+            /** @description `vv_cs_` and base64url characters, so the secret is a valid WebSocket subprotocol token in `bearer.<secret>`. */
+            value: string;
+            /**
+             * Format: date-time
+             * @description The end of the connect window (120 s after issue): the secret must open a connection (over SSE: run its first turn) by then. Once used, it is bound to the session until the session ends or a new secret is issued (`refreshClientSecret`), so the app reconnects with the same secret (and sends it on every SSE turn) without asking for a new one.
+             */
+            expires_at: string;
+        };
+        Session: {
+            id: string;
+            /** @enum {string} */
+            status: "open";
+            agent: {
+                id: string;
+                version: string;
+                display_name: string;
+                /**
+                 * Format: uri
+                 * @description v1-draft.19, optional: the agent's avatar (`getAgentAvatarImage`), a square 512 px WebP with no metadata, re-encoded by Vinaverse from the tenant's upload and passed by its image screen. The URL is immutable (it changes when the image does), so an app may cache the image for as long as it likes; it needs no credential. Absent: no avatar yet, so draw the name's monogram.
+                 */
+                avatar_url?: string;
+            };
+            client_secret: components["schemas"]["ClientSecret"];
+            /** Format: uri */
+            realtime_url: string;
+            /** Format: uri */
+            turns_url: string;
+            /**
+             * Format: date-time
+             * @description When the session ends: the earliest of the session's own `limits.max_duration_seconds` (when `createSession` sets it), the agent's and the environment's longest session, and `tool_access.expires_at`. A short-lived tool token shortens the session. On the WebSocket, `session.expiring` comes 60 s before, then `session.closed` with `expired`.
+             */
+            expires_at: string;
+            disclosure: string;
+            /** @description The conversation this session belongs to, the same for every session of it, however it was resumed (by `conversation_key` or `conversation_id`). Present whenever the session belongs to a conversation: when the request named one, and for every guided-flow session. It is absent only for a session with no conversation, and optional in the schema so clients built on earlier drafts keep working. */
+            conversation_id?: components["schemas"]["ConversationId"];
+            /** @description v1-draft.20, the session's mode, as given or as the agent's template sets it */
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            /** @description v1-draft.20, present when the session acts for a business */
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            /** @description v1-draft.20, the screen context the session accepted, when `createSession` gave one */
+            screen_context?: components["schemas"]["ScreenContext"];
+            /** @description v1-draft.20, absent when the tenant's manifest has no welcome for the session's mode */
+            welcome?: components["schemas"]["Welcome"];
+            /** @description v1-draft.27, whether the agent remembers the person, and the notice to show once */
+            memory?: components["schemas"]["SessionMemory"];
+            /** @description v1-draft.37, what the chat is about, with its verified card, when `createSession` gave an anchor */
+            anchor?: components["schemas"]["SessionAnchorView"];
+            /** @description v1-draft.40, the chat experience at session start, resolved (`ChatExperience`) */
+            experience?: components["schemas"]["ChatExperience"];
+        };
+        SessionStatus: {
+            id: string;
+            /** @enum {string} */
+            status: "open" | "closed" | "revoked" | "expired";
+            subject_id: components["schemas"]["SubjectId"];
+            agent_version?: string;
+            turns: number;
+            handoff_ticket_ids?: string[];
+            /**
+             * @description Why the session ended. `server_restart` is reserved and never appears here: it never ends a session (`docs/realtime-protocol.md` §2). `deleted` (v1-draft.21): its conversation was deleted from history.
+             * @enum {string}
+             */
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left" | "deleted";
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            closed_at?: string;
+            usage?: components["schemas"]["Usage"];
+        };
+        TurnInput: {
+            client_event_id?: string;
+            text: string;
+            /** @description v1-draft.37, optional, as on `input.text` */
+            intent?: components["schemas"]["IntentId"];
+        };
+        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
@@ -1443,6 +2130,38 @@ interface components {
             label: string;
             deep_link?: string;
         };
+        /** @description v1-draft.20: one photo of a `professional` or `workspace` card. Https only, from a prefix the tenant registered (admin-v1 `Connector.image_url_prefixes`), compared after the URL is parsed and normalized (no user info, backslash, fragment or dot segment): an image that fails is dropped, never the card. The tenant serves only photos its own moderation approved, at URLs that stay valid as long as the transcript (a card in history draws them again). An image that fails to load draws the name's monogram; the card stays. */
+        CardImage: {
+            /** Format: uri */
+            url: string;
+            width?: number;
+            height?: number;
+        };
+        /** @description v1-draft.20: the cards one turn draws together carry the same `id`. `layout` is a hint: `carousel` draws them in one horizontal row, `list` one under another. A client that does not know `group`, or a `layout` value, draws a list, as before. */
+        CardGroup: {
+            id: string;
+            /** @enum {string} */
+            layout: "list" | "carousel";
+        };
+        /** @description v1-draft.20, one link of a `links` card: one of the tenant's own destinations from its connector manifest (admin-v1 `Connector.help_links`), never a link the model wrote. */
+        CardLink: {
+            /** @description in Unicode code points */
+            label: string;
+            /** @description an https page of the tenant's, or a deep link that passes the deep-link rule (`next_step`) */
+            url: string;
+            /** @enum {string} */
+            purpose: "help" | "support" | "policy" | "contact" | "feedback";
+        };
+        /** @description v1-draft.20, on a `links` card: the tenant's scope policy, at the version in force, that kept the agent from answering, and why. v1-draft.37: `policy_id` and `version` are required for the scope reasons and may be absent for `help`, which no scope policy decides. */
+        ScopeProvenance: {
+            policy_id?: string;
+            version?: string;
+            /**
+             * @description why the card is shown: the scope kept the agent from answering (`off_scope`, `competitor`, `blocked_topic`), or the person asked how to reach the business or how to do something no tool answers (`help`, v1-draft.36)
+             * @enum {string}
+             */
+            reason: "off_scope" | "competitor" | "blocked_topic" | "help";
+        };
         /**
          * @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
@@ -1462,21 +2181,41 @@ interface components {
          *       know.
          *     - **It is not restored.** A `next_step` card is in neither `pending_cards` nor `transcript`; after a
          *       reconnect the agent shows the step again once it reads the tenant's state.
+         *
+         *     **Listing cards** (v1-draft.20). A `professional` or `workspace` card may carry `images` (up to five, the first the hero; `image_url`, when present, is the first one's URL, for clients that predate `images`), `next_available` (the earliest open time the tenant's tool returned; a hint, so a tap on its time reads availability again), `price_from` and a `group`. An app draws one hero image first and the rest on a swipe.
+         *     **A `links` card** (v1-draft.20) answers what the tenant's scope keeps the agent from answering: a question off its scope, a comparison with a competitor, a blocked topic. Its `links` are the tenant's own help, support, policy, contact or feedback destinations (`CardLink`), its `provenance` names the scope policy and the reason, and it has no `actions`: each link opens the tenant's page. It belongs to a recorded turn, with the agent's one line around it, never to `input.rejected`. Its `source.tool` is `scope` and its `source.call_id` the turn's id: no tool call made it. An earlier client skips the unknown kind, as it skips any.
+         *     **An `anchor` card** (v1-draft.37) shows what a context-started chat is about: `title` (at most 80 code points) and its `anchor` body (`AnchorCard`): display only, no `actions`. Its `source.tool` is `anchor` and its `source.call_id` the anchor read that made it (`session` for the anchor `createSession` carried). It is `Session.anchor.card` and the conversation's first timeline item.
+         *     **An `open_action` card** (v1-draft.37) hands an eligible `action` intent to the tenant's own flow (`OpenAction`), with no `actions` of its own: the app opens its `route`. A build without the `open_action` capability never gets one; it gets the action's `fallback_link` as a `links` card.
          */
         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)
+             * @description customer-agent kinds, then business-copilot kinds (Studio), then `question` (guided flows), then `proposal` (a change the person confirms or declines in the tenant's app), then `next_step` (a step the person finishes on the tenant's own screen), then `links` (v1-draft.20: the tenant's own pages, when its scope keeps the agent from answering), then `anchor` and `open_action` (v1-draft.37: what a context-started chat is about, and a hand-off to the tenant's own flow)
              * @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";
+            kind: "professional" | "workspace" | "service" | "time_slots" | "booking" | "quote" | "policy" | "handoff" | "metric_chart" | "metric_table" | "gap_list" | "cluster" | "claim" | "document" | "question" | "proposal" | "next_step" | "links" | "anchor" | "open_action";
             question?: components["schemas"]["Question"];
             proposal?: components["schemas"]["Proposal"];
+            anchor?: components["schemas"]["AnchorCard"];
+            open_action?: components["schemas"]["OpenAction"];
             ref?: components["schemas"]["CardRef"];
             title: string;
             subtitle?: string;
             /** Format: uri */
             image_url?: string;
+            /** @description v1-draft.20, a `professional` or `workspace` card's photos, the first the hero */
+            images?: components["schemas"]["CardImage"][];
+            /** @description v1-draft.29, on a `time_slots` or `professional` card only: what the person asked to be passed to the professional, in their own words and language, carried with this card's hand-off (`select_slot`, or the `open` action) for the app to prefill its checkout note, which the person can still edit. An app whose checkout has no note ignores it. Plain text, never markup. */
+            booking_note?: string;
+            /**
+             * Format: date-time
+             * @description v1-draft.20, a `professional` or `workspace` card's earliest open time, as the tenant's tool returned it
+             */
+            next_available?: string;
+            group?: components["schemas"]["CardGroup"];
+            /** @description v1-draft.20, a `links` card's links */
+            links?: components["schemas"]["CardLink"][];
+            provenance?: components["schemas"]["ScopeProvenance"];
             rating?: {
                 value_ppm: number;
                 count: number;
@@ -1520,7 +2259,7 @@ interface components {
                 points: {
                     /** Format: date */
                     t: string;
-                    /** @description null when suppressed by the k-anonymity floor */
+                    /** @description null when suppressed by the k-anonymity floor; on a metric without k_floor, nothing to measure */
                     value: number | null;
                     suppressed?: boolean;
                 }[];
@@ -1538,6 +2277,7 @@ interface components {
                 dims: {
                     [key: string]: string;
                 };
+                /** @description null when suppressed by the metric's k_floor; on a metric without k_floor, nothing to measure */
                 values: {
                     [key: string]: number | null;
                 };
@@ -1548,7 +2288,8 @@ interface components {
                 area: string;
                 demand: number;
                 supply: number;
-                zero_result_share_ppm: number;
+                /** @description v1-draft.33: null when fewer than the metric's k_floor distinct people are behind the zero results, whatever the cell's demand (a subgroup is released only on its own people) */
+                zero_result_share_ppm: number | null;
                 trend_ppm?: number | null;
             }[];
             label?: string;
@@ -1556,7 +2297,7 @@ interface components {
             share_ppm?: number;
             /** @enum {string} */
             outcome?: "zero_results" | "withheld" | "handoff" | "mixed";
-            /** @description redacted */
+            /** @description Not sent since v1-draft.33: an `intent_cluster` card carries its label and counts only. Customer questions, even redacted, can name a person or a health matter. */
             examples?: string[];
             claim?: {
                 id: string;
@@ -1582,7 +2323,7 @@ interface components {
             snippet?: string;
             /** Format: date-time */
             updated_at?: string;
-        } & (unknown & unknown & unknown);
+        } & (unknown & unknown & unknown & unknown & unknown & unknown & unknown);
         /** @enum {string} */
         ValueUnit: "count" | "ppm" | "micros_usd" | "ms";
         MetricRef: {
@@ -1590,6 +2331,7 @@ interface components {
             label: string;
             unit: components["schemas"]["ValueUnit"];
             definition: string;
+            /** @description The privacy floor: a value built from fewer than this many distinct people is suppressed (`null`). Absent when no floor applies, as on a business's own operational data (Studio's pages, read by the business copilot); a `null` value there means there was nothing to measure, never a hidden count. */
             k_floor?: number;
         };
         /** @description Links a span of the reply text to the card or tool call it came from. Offsets are in Unicode code points (not bytes, not UTF-16 units), start inclusive, end exclusive. */
@@ -1822,6 +2564,139 @@ interface components {
             /** Format: date-time */
             at: string;
         };
+        ConversationPage: {
+            data: components["schemas"]["ConversationSummary"][];
+            next_cursor: string | null;
+        };
+        /** @description v1-draft.21: one past conversation as a history screen lists it. The title is from the conversation's last search intent or its date, never the person's words. v1-draft.37: an anchored conversation carries `anchor` (its type and title, so a history screen groups by it with no other call), and any conversation may carry `last_message`, a short preview of its last message. */
+        ConversationSummary: {
+            id: components["schemas"]["ConversationId"];
+            agent: string;
+            experience_mode: components["schemas"]["ExperienceMode"];
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            title: string;
+            /**
+             * @description `intent`: the last search intent (service and place); `date`: the day it started
+             * @enum {string}
+             */
+            title_source: "intent" | "date";
+            /** Format: date-time */
+            started_at: string;
+            /** Format: date-time */
+            last_activity_at: string;
+            /** @description the messages its timeline holds (cards not counted) */
+            message_count: number;
+            /**
+             * @description `open`: a session can resume it; `ended`: it can only be read
+             * @enum {string}
+             */
+            state: "open" | "ended";
+            /** @description v1-draft.37, what an anchored conversation is about: the anchor's type and its title as the person saw it (`SessionAnchor.title`), never message text. History groups conversations by it. */
+            anchor?: {
+                kind: components["schemas"]["AnchorType"];
+                title: string;
+            };
+            /** @description v1-draft.37, a preview of the conversation's last message, at most 120 code points, cut at a word with an ellipsis, made from the message as the timeline stores it: after digit masking and redaction, never from a withheld sentence. Never a refused message (`refusal: true`), and absent under the tenant's `transcript_retention` `none`. */
+            last_message?: {
+                /** @enum {string} */
+                role: "person" | "assistant" | "staff";
+                text: string;
+            };
+        };
+        TimelinePage: {
+            conversation: components["schemas"]["ConversationSummary"];
+            data: components["schemas"]["TimelineItem"][];
+            /** @description the next older page; null at the conversation's start */
+            next_cursor: string | null;
+        };
+        /**
+         * @description v1-draft.21: one item of a past conversation, a message or a card its turn drew. `id` is stable and unique within the conversation; a message's `event_id` is its live event's identifier (`TranscriptItem.id`), the key an app merges live and resumed messages by, with `role`. A card is read-only in history.
+         *     Unlike `session.ready.transcript`, the history holds the turns the tenant's scope refused (a competitor, a blocked topic, a strictly off-scope question): the person's message and the fixed line said instead of an answer both carry `refusal: true`, so the app draws them as it drew them live (muted, never offered again). An input a guardrail blocks (an instruction override, an attempt to extract the prompt or keys, a persona hijack) is never recorded and is in no history (v1-draft.26): attack text is not kept in a person's history. A `proposal` card carries `proposal_outcome`, what became of it.
+         */
+        TimelineItem: {
+            /** @constant */
+            type: "message";
+            id: string;
+            /**
+             * @description a client tolerates a role it does not know, as in `TranscriptItem`
+             * @enum {string}
+             */
+            role: "person" | "assistant" | "staff";
+            text: string;
+            /** Format: date-time */
+            at: string;
+            /** @description absent on a `person` message sent without a `client_event_id` */
+            event_id?: string;
+            turn_id?: string;
+            /** @description `assistant` only, present only when true: the reply stopped before it finished */
+            interrupted?: boolean;
+            /** @description v1-draft.40, `assistant` only: the person's current rating and reaction, absent when there is none */
+            feedback?: components["schemas"]["MessageFeedback"];
+            /**
+             * @description Present only when true: the tenant's scope refused this turn. On a `person` message, the text it refused (as recorded, card-like digits masked); on an `assistant` message, the fixed line said instead of an answer. An input a guardrail blocks is never recorded, so it never appears here.
+             * @constant
+             */
+            refusal?: true;
+        } | ({
+            /** @constant */
+            type: "card";
+            id: string;
+            turn_id?: string;
+            /** Format: date-time */
+            at: string;
+            card: components["schemas"]["Card"];
+            /**
+             * @description A `proposal` card only, always present on one: the outcome the app reported for it (`ui.action` `confirmed`, `declined`, `failed` or `expired`), or `pending` while none was reported. Draw it as settled; a past proposal is never confirmed from history.
+             * @enum {string}
+             */
+            proposal_outcome?: "pending" | "confirmed" | "declined" | "failed" | "expired";
+        } & unknown);
+        ConversationDeleted: {
+            conversation_id: components["schemas"]["ConversationId"];
+            sessions_revoked: number;
+        };
+        /** @example memory-2026-10 */
+        MemoryNoticeVersion: string;
+        /** @description v1-draft.27: the one-time notice that the agent remembers the person across conversations, in the subject's language, written by Vinaverse. Show it once with two choices: dismiss it (`acknowledgeMemoryNotice`) or turn memory off (`putSubjectMemory` with `remembered: false`), both through the tenant's backend. */
+        MemoryNotice: {
+            version: components["schemas"]["MemoryNoticeVersion"];
+            /** @description in Unicode code points */
+            text: string;
+        };
+        /** @description v1-draft.27: whether the agent remembers this person across conversations in this session, and the notice to show while they have not acknowledged its current version. `notice` is absent once acknowledged, when memory is off, and for a guest (a guest is never remembered). */
+        SessionMemory: {
+            remembered: boolean;
+            notice?: components["schemas"]["MemoryNotice"];
+        };
+        MemorySource: {
+            conversation_id: components["schemas"]["ConversationId"];
+            /** Format: date-time */
+            at: string;
+        };
+        /** @description v1-draft.27: one thing the person asked the agent to remember ("remember that I prefer mornings"), in the words the agent said back to the person, never inferred. Never a health fact or a never-store detail; a fact about someone else ("my daughter prefers short hair") is the person's own note (v1-draft.39). */
+        MemoryPreference: {
+            id: string;
+            text: string;
+            source: components["schemas"]["MemorySource"];
+        };
+        /** @description v1-draft.27: the last open search intent, as the search resolved it (a catalogue service's name, a place's name), never the person's words; kept 7 days from `at`. */
+        LastSearch: {
+            service?: string;
+            area?: string;
+            /** Format: date-time */
+            at: string;
+            source: components["schemas"]["MemorySource"];
+        };
+        SubjectMemoryChoice: {
+            /** @description `false`: "don't remember me", on both sides of the app */
+            remembered: boolean;
+        };
+        SubjectMemory: {
+            remembered: boolean;
+            notice_acknowledged?: components["schemas"]["MemoryNoticeVersion"];
+            preferences: components["schemas"]["MemoryPreference"][];
+            last_search?: components["schemas"]["LastSearch"];
+        };
         /** @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;
@@ -1956,6 +2831,8 @@ interface components {
             type: "input.text";
             client_event_id?: string;
             text: string;
+            /** @description v1-draft.37, optional: the anchor intent a chip carries, sent with the chip's text. Eligible now, an `action` intent gets its `open_action` card and an `explain` intent the manifest's template answer, with no model call; no longer eligible, the agent says what changed and offers the new intents; an intent the session's anchor does not list is treated as the text alone. */
+            intent?: components["schemas"]["IntentId"];
         } | {
             /** @constant */
             type: "input.cancel";
@@ -1985,6 +2862,14 @@ interface components {
             card_id: string;
             question_id: components["schemas"]["QuestionId"];
             answer: components["schemas"]["AnswerInput"];
+        } | {
+            /** @constant */
+            type: "action.result";
+            client_event_id?: string;
+            card_id: string;
+            action_id: string;
+            /** @enum {string} */
+            outcome: "completed" | "cancelled" | "failed" | "unknown";
         } | {
             /** @constant */
             type: "ping";
@@ -2002,6 +2887,16 @@ interface components {
             };
             disclosure: string;
             resumed: boolean;
+            /** @description v1-draft.20, the session's mode (`Session.experience_mode`), so the app keeps one store per mode */
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            /** @description v1-draft.20, present when the session acts for a business */
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            /** @description v1-draft.27, as `Session.memory`, so an app that reconnects still shows an unacknowledged notice */
+            memory?: components["schemas"]["SessionMemory"];
+            /** @description v1-draft.37, as `Session.anchor`, refreshed when the session's anchor was re-read */
+            anchor?: components["schemas"]["SessionAnchorView"];
+            /** @description v1-draft.40, as `Session.experience`: the value at session start, the same on every reconnect of the session */
+            experience?: components["schemas"]["ChatExperience"];
             /**
              * @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):
@@ -2044,9 +2939,12 @@ interface components {
             /** @constant */
             type: "tool.status";
             turn_id: string;
+            /** @description the step's words for builds before v1-draft.40; a newer client draws `step` */
             label: string;
             /** @enum {string} */
             state: "running" | "done" | "failed";
+            /** @description v1-draft.40, the named working step; absent from a server that predates it */
+            step?: components["schemas"]["ToolStep"];
         } | {
             /** @constant */
             type: "message.delta";
@@ -2062,6 +2960,7 @@ interface components {
             /** @constant */
             type: "message.completed";
             turn_id: string;
+            /** @description v1-draft.30: the turn's reply. It may leave out sentences streamed in a step that ended in a tool call; show it in place of the turn's streamed `message.delta` texts. */
             text: string;
             /** @description optional; spans of `text` with their source card or tool call */
             citations?: components["schemas"]["Citation"][];
@@ -2106,6 +3005,15 @@ interface components {
              */
             code: "screened" | "too_long" | "turn_in_progress" | "limit_reached" | "duplicate" | "guardrail" | "screen_unavailable";
             message: string;
+        } | {
+            /** @constant */
+            type: "context.updated";
+            revision: number;
+            /**
+             * @description present only after an explicit clear
+             * @constant
+             */
+            cleared?: true;
         } | {
             /** @constant */
             type: "session.expiring";
@@ -2114,10 +3022,10 @@ interface components {
             /** @constant */
             type: "session.closed";
             /**
-             * @description `replaced`: a newer session of the same conversation was created (close code `4409`)
+             * @description `replaced`: a newer session of the same conversation was created (close code `4409`). `deleted` (v1-draft.21): the person deleted the conversation from their history (`deleteConversation`, close code `4403`); drop it from the app's store and never resume it. A client that does not know `deleted` reads it as `revoked`, as any unknown reason.
              * @enum {string}
              */
-            reason: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "replaced";
+            reason: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "replaced" | "deleted";
         } | {
             /** @constant */
             type: "ui.answer.recorded";
@@ -2283,7 +3191,10 @@ interface components {
             threshold_policy?: string;
             policy_version: string;
             model: {
-                id: string;
+                id: components["schemas"]["ModelName"];
+                /** @description what a person reads for `id`, such as "Vinaverse Language 0.1" (v1-draft.35) */
+                label?: string;
+                /** @description `vinaverse` for a Vinaverse model (v1-draft.34) */
                 provider: string;
                 revision?: string;
             };
@@ -2550,23 +3461,578 @@ interface components {
                 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;
-            };
+        /**
+         * @description v1-draft.40, the preset a tenant starts from: `minimal` (a quiet support chat), `standard` (a calm concierge, the default) or `rich` (a messaging-first companion). The values of each are in `fixtures/api/experience/valid/presets.json`.
+         * @enum {string}
+         */
+        ChatPreset: "minimal" | "standard" | "rich";
+        /**
+         * @description v1-draft.40 (VIN-115, the chat spec's module G): how the in-app chat behaves for one agent, as the tenant set
+         *     it in Studio. Every field is optional: a field absent is the kit's own default (the `standard` preset), so an
+         *     app built before a field existed keeps working, except a field the gateway enforces (`edit`, `regenerate`,
+         *     `versions`, `fork`, `pins` stored on the server, `summary`), which resolves off when absent. That is about the
+         *     resolved value; in a setting's `overrides` an absent field is the preset's value. A client ignores a field it
+         *     does not know.
+         *
+         *     **Resolved, not raw.** Inside a conversation the value is resolved: the tenant's preset with its changes
+         *     (admin-v1 `ChatExperienceSetting`), narrowed by what this server serves (a feature it does not serve yet
+         *     resolves off) and, where a field says so, by `createSession.client.capabilities`. The kit narrows it again
+         *     with the app's own choices, then with the message's state (Try again on a booking reply is never offered);
+         *     it never widens it.
+         *
+         *     **What it cannot change** (spec G TC-05): the AI disclosure, the phone's Reduce Motion and text size, contrast
+         *     floors, performance budgets, the money and deadline rules, no edit, Try again or fork across a commitment,
+         *     and the privacy floors. None of those is a field here. Turning a feature off never hides or erases what
+         *     exists: forks, pins, reactions and versions already made stay readable.
+         *
+         *     Attachments (spec K) are a separate group, added with the attachments contract.
+         */
+        ChatExperience: {
+            preset?: components["schemas"]["ChatPreset"];
+            header?: {
+                /**
+                 * @description default `per_mode`
+                 * @enum {string}
+                 */
+                style?: "neutral" | "brand" | "per_mode";
+                /** @description the "About Riley" line; default true */
+                context?: boolean;
+            };
+            avatar?: {
+                /**
+                 * @description default `last_of_run`
+                 * @enum {string}
+                 */
+                in_thread?: "last_of_run" | "every" | "off";
+            };
+            anchor?: {
+                /** @description a compact strip once the anchor card scrolls away; default true */
+                pin_strip?: boolean;
+            };
+            composer?: {
+                /**
+                 * @description default `dictation`
+                 * @enum {string}
+                 */
+                voice?: "off" | "dictation" | "live";
+            };
+            /**
+             * @description default `outcomes`
+             * @enum {string}
+             */
+            haptics?: "off" | "outcomes" | "selection_and_outcomes";
+            /** @description voice and notifications only; default false */
+            sound?: boolean;
+            language?: {
+                /**
+                 * @description default `app_locale`
+                 * @enum {string}
+                 */
+                chips?: "app_locale" | "person_language";
+            };
+            /** @description the working line (spec A AS-10 to AS-12) */
+            working?: {
+                /**
+                 * @description `glance` shows "Working on it…" only; `steps` names the step (default); `steps_expandable` adds the step list
+                 * @enum {string}
+                 */
+                detail?: "glance" | "steps" | "steps_expandable";
+                /** @description "Still checking…" after; default 4 */
+                slow_after_s?: number;
+                /** @description "Taking longer" and Stop after; default 12 */
+                stop_after_s?: number;
+                /** @description the state glyph on the agent's mark; default true */
+                glyph?: boolean;
+            };
+            thinking?: {
+                /**
+                 * @description default `dots`
+                 * @enum {string}
+                 */
+                indicator?: "dots" | "text" | "off";
+            };
+            stream?: {
+                /**
+                 * @description default `paced`
+                 * @enum {string}
+                 */
+                reveal?: "paced" | "sentence" | "whole_reply";
+                /** @description default true */
+                caret?: boolean;
+            };
+            motion?: {
+                /**
+                 * @description `calm` uses crossfades only; default `standard`
+                 * @enum {string}
+                 */
+                level?: "calm" | "standard";
+            };
+            send?: {
+                /**
+                 * @description default `full`
+                 * @enum {string}
+                 */
+                states?: "full" | "failures_only";
+            };
+            /**
+             * @description default `off`
+             * @enum {string}
+             */
+            receipts?: "off" | "delivered";
+            skeleton?: {
+                /**
+                 * @description `quiet` never pulses; default `shaped`
+                 * @enum {string}
+                 */
+                style?: "shaped" | "quiet";
+            };
+            /** @description result cards (spec B) */
+            cards?: {
+                /** @description the card kinds drawn; absent in a setting: every kind the connector supports when it is saved (stored as that list, so a kind added later stays off). Open: an unknown kind is ignored */
+                kinds?: string[];
+                layout?: {
+                    /**
+                     * @description default `list`
+                     * @enum {string}
+                     */
+                    decision?: "list" | "strip";
+                    /**
+                     * @description default `strip`
+                     * @enum {string}
+                     */
+                    browse?: "strip" | "list";
+                };
+                /** @description the default form per card kind; absent kinds follow the layout rule */
+                form?: {
+                    [key: string]: "row" | "tile" | "expanded";
+                };
+                /**
+                 * @description default `photo_first`
+                 * @enum {string}
+                 */
+                media?: "photo_first" | "monogram" | "none";
+                /**
+                 * @description default `on`
+                 * @enum {string}
+                 */
+                prices?: "on" | "from_only" | "off";
+                /** @description default true */
+                ratings?: boolean;
+                /** @description when supported; default true */
+                distance?: boolean;
+                /** @description default true */
+                next_opening?: boolean;
+                /** @description default false */
+                compare?: boolean;
+                /** @description through the host's map; default false */
+                map?: boolean;
+                /** @description default true */
+                see_all?: boolean;
+                /** @description per card kind, the actions drawn; absent kinds draw every eligible action */
+                actions?: {
+                    [key: string]: ("open" | "book" | "message" | "save" | "compare")[];
+                };
+                /** @description the context changes a card's emphasis; default true */
+                context_lead?: boolean;
+                /** @description the "From your booking · checked just now" line; default true */
+                sources?: boolean;
+            };
+            /** @description in-chat inputs (spec C) */
+            inputs?: {
+                /** @description absent: the flow's own set */
+                enabled?: ("photo" | "address_map" | "hours" | "service_builder" | "trades" | "date_range" | "form")[];
+                photo?: {
+                    /**
+                     * @description default `both`
+                     * @enum {string}
+                     */
+                    sources?: "camera" | "library" | "both";
+                    /**
+                     * @description absent: per purpose
+                     * @enum {string}
+                     */
+                    crop?: "square" | "circle" | "free" | "none";
+                };
+                address?: {
+                    /**
+                     * @description default `on`
+                     * @enum {string}
+                     */
+                    map?: "on" | "text_only";
+                };
+                hours?: {
+                    /** @description default true */
+                    breaks?: boolean;
+                };
+                /**
+                 * @description default `always`
+                 * @enum {string}
+                 */
+                review?: "always" | "consequential_only";
+                /** @description default true */
+                natural_language_fill?: boolean;
+                /** @description the customer-facing preview during setup; default true */
+                preview?: boolean;
+            };
+            switcher?: {
+                /** @description default true */
+                enabled?: boolean;
+                /**
+                 * @description default `active_mode`
+                 * @enum {string}
+                 */
+                scope?: "active_mode" | "all_modes";
+            };
+            continue_offer?: {
+                /** @description default true */
+                enabled?: boolean;
+                /** @description Decided, Still needed, Changed since; default false */
+                checkpoint?: boolean;
+            };
+            reopen?: {
+                /**
+                 * @description default `where_left`
+                 * @enum {string}
+                 */
+                position?: "where_left" | "latest";
+            };
+            /** @description the switcher and history (spec D) */
+            history?: {
+                /** @description default true when the retention keeps transcripts */
+                enabled?: boolean;
+                /**
+                 * @description default `context`
+                 * @enum {string}
+                 */
+                group?: "context" | "day";
+                /** @description default true */
+                live_status?: boolean;
+                /** @description default true */
+                outcomes?: boolean;
+                /** @description `ConversationSummary.last_message` drawn; default false */
+                preview?: boolean;
+                /** @description default true */
+                filters?: boolean;
+                /** @description default true */
+                delete?: boolean;
+                /** @description default true */
+                archive?: boolean;
+                /** @description default true */
+                rename?: boolean;
+            };
+            drafts?: {
+                /** @description default true */
+                listed?: boolean;
+            };
+            delete?: {
+                /** @description the kit holds a delete this long; default 10 */
+                undo_seconds?: number;
+            };
+            /** @description accuracy feedback (spec F MA-01, MA-02) */
+            feedback?: {
+                /** @description helpful and not helpful; default true */
+                accuracy?: boolean;
+                /** @description the reasons offered after "not helpful", in order; empty: none. Default every one */
+                reasons?: components["schemas"]["FeedbackReason"][];
+            };
+            /** @description Reactions (spec F MA-03). `like` is a single heart, recorded as `love`; `emoji` offers `set`, in order. With `like`, `set` is `[love]`. A reaction is never a rating, a preference or a consent. */
+            reactions?: {
+                /**
+                 * @description default `like`
+                 * @enum {string}
+                 */
+                mode?: "off" | "like" | "emoji";
+                set?: components["schemas"]["ReactionKind"][];
+                /** @description a double tap gives the first reaction of `set`; default true */
+                double_tap?: boolean;
+            };
+            /** @description "How was this conversation?" once; default false */
+            csat?: boolean;
+            /** @description default true */
+            copy?: boolean;
+            share?: {
+                /**
+                 * @description text with a preview sheet; default `preview`
+                 * @enum {string}
+                 */
+                mode?: "off" | "preview";
+                /** @description persistent public links (not served yet, resolves false); default false */
+                links?: boolean;
+            };
+            /** @description the phone's own speech; default true */
+            read_aloud?: boolean;
+            /**
+             * @description Which of the person's messages may be edited (spec F MA-21): the latest (default), any after the most recent commitment, or none. Never across a commitment, whatever this says: the gateway refuses that.
+             * @enum {string}
+             */
+            edit?: "off" | "latest" | "after_commitment";
+            /** @description Try again (spec F MA-30 to MA-32); only on replies that committed nothing, enforced by the gateway */
+            regenerate?: {
+                /**
+                 * @description default `newest`
+                 * @enum {string}
+                 */
+                scope?: "off" | "newest" | "any";
+                /** @description versions per turn; default 5 */
+                max?: number;
+            };
+            /**
+             * @description default `on`
+             * @enum {string}
+             */
+            versions?: "off" | "on" | "on_with_sheet";
+            /** @description forks (spec F MA-41 to MA-49) */
+            fork?: {
+                /** @description default false */
+                enabled?: boolean;
+                /**
+                 * @description default `nested`
+                 * @enum {string}
+                 */
+                style?: "nested" | "new_conversation";
+                /** @description default true */
+                compare?: boolean;
+                /** @description default true */
+                carry_back?: boolean;
+                /** @description forks per conversation; default 5 */
+                max?: number;
+            };
+            pins?: {
+                /** @description default true */
+                messages?: boolean;
+                /** @description pinned messages per conversation; default 3 */
+                max?: number;
+                /** @description default true */
+                conversations?: boolean;
+                /**
+                 * @description `server` when the server serves pins
+                 * @enum {string}
+                 */
+                storage?: "server" | "device";
+            };
+            favorites?: {
+                /** @description default false */
+                messages?: boolean;
+                /** @description default false */
+                conversations?: boolean;
+            };
+            actions?: {
+                /**
+                 * @description default `row_newest_plus_menu`
+                 * @enum {string}
+                 */
+                surface?: "row_newest_plus_menu" | "menu_only";
+            };
+            /** @description time in the transcript (spec I LC-01); day separators, exact times and times in labels stay in every mode */
+            timestamps?: {
+                /**
+                 * @description default `run`
+                 * @enum {string}
+                 */
+                mode?: "run" | "every" | "gap";
+                /**
+                 * @description for gap labels; default 60
+                 * @enum {integer}
+                 */
+                gap_minutes?: 30 | 60 | 120;
+                /** @description default true */
+                floating_date?: boolean;
+            };
+            /** @description default true */
+            day_separators?: boolean;
+            /** @description the person's summary (spec I LC-10 to LC-12) */
+            summary?: {
+                /**
+                 * @description default `entry`
+                 * @enum {string}
+                 */
+                mode?: "off" | "entry" | "entry_with_preview";
+                /** @description default true */
+                outcome_chips?: boolean;
+                /** @description the one-line summary on history rows; default false */
+                show_in_history?: boolean;
+                /** @description default true */
+                editable?: boolean;
+            };
+            compaction?: {
+                /** @description "Earlier messages summarized"; off hides the divider only, the transcript never changes; default true */
+                divider?: boolean;
+            };
+            /** @description search (spec I LC-30); results are always the message's own text */
+            search?: {
+                /** @description empty: no search. Default both */
+                scopes?: ("conversation" | "mode")[];
+                /** @description meaning as well as words; false is words only; default true */
+                semantic?: boolean;
+            };
+            chapters?: {
+                /** @description default false */
+                enabled?: boolean;
+                /** @description default 80 */
+                min_messages?: number;
+            };
+            /** @description default true */
+            jump_to_latest?: boolean;
+            unread?: {
+                /** @description default true */
+                divider?: boolean;
+            };
+            sources?: {
+                /** @description under consequential claims; default true */
+                line?: boolean;
+            };
+            /** @description memory in the chat (spec J); off whenever the person or the tenant turned memory off */
+            memory?: {
+                /** @description default true */
+                chips?: boolean;
+                /** @description "What the agent remembers"; default false */
+                page?: boolean;
+                /** @description a conversation kept out of memory; default true */
+                per_conversation_off?: boolean;
+            };
+            handoff?: {
+                /** @description absent in a setting: every route the tenant has when it is saved (stored as that list) */
+                routes?: ("support" | "professional" | "host")[];
+                /** @description a reviewable summary attached; default true */
+                summary?: boolean;
+            };
+            /** @description default false */
+            promises?: boolean;
+            /** @description default false */
+            ideas?: boolean;
+            /** @description default false */
+            goals?: boolean;
+        };
+        /** @description v1-draft.40, `getAgentExperience`: the agent's chat experience before any session, resolved as for `Session.experience` except the client's capabilities, which no session has given yet. */
+        AgentExperience: {
+            agent: string;
+            experience_mode: components["schemas"]["ExperienceMode"];
+            experience: components["schemas"]["ChatExperience"];
+            /**
+             * Format: date-time
+             * @description when the tenant last changed it; absent while the agent runs on the defaults
+             */
+            updated_at?: string;
+        };
+        /**
+         * @description v1-draft.40, what a working step does, for its icon (spec A AS-10). Open for clients: an unknown kind is drawn as `other`.
+         * @enum {string}
+         */
+        StepKind: "search" | "availability" | "booking" | "rental" | "policy" | "price" | "setup" | "handoff" | "other";
+        /**
+         * @description v1-draft.40 (VIN-115, spec A AS-10 to AS-14): the working line of one tool call, on `tool.status`.
+         *
+         *     **The words.** `text` is the step in the present tense ("Checking Riley's openings…"), and on `done` or
+         *     `failed` `text_done` is the past tense with its outcome ("Checked Riley's openings · 3 times on Saturday";
+         *     "Couldn't check Riley's openings right now"). Both come from the tenant's closed template for the tool (the
+         *     connector manifest's `tools[].step`, admin-v1), in the session's language, or from the platform's generic
+         *     step for the tool's capability when the tenant has none. The gateway fills them, so a client draws them as
+         *     they are and never formats a template.
+         *
+         *     **Safe values only.** A template's placeholders are a closed list (`params`): each value comes from the
+         *     tool's validated arguments or its result (a resolved place's label, a resource's name the tool returned, a
+         *     service, a date), checked and cut to 60 code points, never from the model's text, a raw tool name or an
+         *     argument as the model wrote it. A value that is absent or fails its check leaves the template's generic form
+         *     ("Checking openings…"), never a guess.
+         *
+         *     `template` and `params` are there for a client that localizes on its own; most draw `text`. `id` is the same
+         *     on the `running` and the final event of one call, so the step list replaces its row in place.
+         */
+        ToolStep: {
+            id: string;
+            kind: components["schemas"]["StepKind"];
+            text: string;
+            /** @description on `done` and `failed` only */
+            text_done?: string;
+            /**
+             * @description the template the words came from: `<tool>.running`, `<tool>.done`, or `platform.<kind>`
+             * @example get_availability.running
+             */
+            template?: string;
+            params?: {
+                area?: string;
+                name?: string;
+                service?: string;
+                /** Format: date */
+                date?: string;
+            };
+            /** Format: date-time */
+            started_at: string;
+            /** @description on `done` only */
+            outcome?: {
+                /** @description the items a read found, when it is a read */
+                count?: number;
+                /**
+                 * @description `recovered`: found after the gateway widened the search; `unchecked`: nothing to count
+                 * @enum {string}
+                 */
+                summary_key?: "found" | "none" | "recovered" | "unchecked";
+            };
+        };
+        /**
+         * @description An outcome citing a decision or a turn. Append-only: a record never changes, and a later one supersedes it.
+         *
+         *     **A person's rating and reaction of a reply** (v1-draft.40, spec F MA-01 to MA-06), with `turn_id` and
+         *     `reviewer.role: end_user`:
+         *     - `thumbs_up` (helpful) and `thumbs_down` (not helpful); `thumbs_cleared` removes the rating;
+         *     - `reaction`, with `reaction` `love`, `thanks`, `haha` or `wow`, or `cleared` to remove the reaction;
+         *     - the latest record per turn and person wins, ratings and reactions apart, and a clear takes the turn out of
+         *       every count. The person is the turn's subject: the tenant's backend sends only what that person chose;
+         *     - a `thumbs_down` may carry `reason_codes` from the closed list `FeedbackReason`, and a `note` of at most 200
+         *       code points; an unknown reason code or a longer note rejects that record (`rejected[].code`
+         *       `invalid_request`);
+         *     - a `reaction` or a clear carries no `reason_codes` and no `note`; `reaction_set` records the tenant's mode and
+         *       set when the person reacted (a change of set is a measurement break);
+         *     - an agent's reply may be rated or reacted to, including a refused turn's line and a reply restored from
+         *       history, never the person's own message. A turn of another tenant or environment, or one with no reply, is
+         *       rejected (`not_found`), the same answer for each.
+         */
+        FeedbackRecord: ({
+            decision_id?: string;
+            turn_id?: string;
+            /** @enum {string} */
+            outcome: "approved" | "rejected" | "edited" | "escalated" | "user_appealed" | "appeal_upheld" | "appeal_denied" | "thumbs_up" | "thumbs_down" | "thumbs_cleared" | "reaction";
+            /**
+             * @description v1-draft.40, with `outcome` `reaction` only, and required with it
+             * @enum {string}
+             */
+            reaction?: "love" | "thanks" | "haha" | "wow" | "cleared";
+            reaction_set?: components["schemas"]["ReactionSet"];
+            /** @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;
+            /** @description a reviewer's note; a person's, at most 200 (below) */
             note?: string;
-        } & (unknown | unknown);
+        } & (unknown & unknown & unknown)) & (unknown | unknown);
+        /**
+         * @description v1-draft.40, why a reply was not helpful, from the person (spec F MA-02): "Not accurate", "Didn't answer my question", "Too long", "Something else…". A closed list: the tenant offers a subset of it.
+         * @enum {string}
+         */
+        FeedbackReason: "not_accurate" | "did_not_answer" | "too_long" | "other";
+        /**
+         * @description v1-draft.40, a reaction to a reply (spec F MA-03): love (a heart, also the single `like`), thanks, haha, wow. There is no thumbs-up reaction, so a reaction is never mistaken for a rating.
+         * @enum {string}
+         */
+        ReactionKind: "love" | "thanks" | "haha" | "wow";
+        /** @description v1-draft.40, the tenant's reactions when the person reacted (`ChatExperience.reactions`) */
+        ReactionSet: {
+            /** @enum {string} */
+            mode: "like" | "emoji";
+            set: components["schemas"]["ReactionKind"][];
+        };
+        /** @description v1-draft.40, the person's current rating and reaction of an agent message: the latest feedback record of each, absent when there is none or it was cleared. */
+        MessageFeedback: {
+            /** @enum {string} */
+            rating?: "helpful" | "not_helpful";
+            reaction?: components["schemas"]["ReactionKind"];
+        };
         FeedbackBatch: {
             records: components["schemas"]["FeedbackRecord"][];
         };
@@ -2649,7 +4115,9 @@ interface components {
             flags?: components["schemas"]["DocumentFlag"][];
             decision?: components["schemas"]["Decision"];
             model?: {
-                id?: string;
+                id?: components["schemas"]["ModelName"];
+                /** @description what a person reads for `id` (v1-draft.35) */
+                label?: string;
                 provider?: string;
             };
             error?: components["schemas"]["Problem"];
@@ -2695,7 +4163,16 @@ interface components {
         };
     };
     parameters: {
+        /** @description v1-draft.24, optional: the agent the caller acts for; when given, the conversation must be this agent's, else `404` (the same answer as an unknown id) */
+        BindingAgent: string;
+        /** @description v1-draft.24, optional: the side of the app the caller acts on; when given, the conversation must be bound to it, else `404` */
+        BindingExperienceMode: components["schemas"]["ExperienceMode"];
+        /** @description v1-draft.24, optional: the business the caller acts for; when given, the conversation must be bound to it, else `404`. With `experience_mode: business` and no `business_scope_id`, a conversation bound to a business does not match. */
+        BindingBusinessScope: components["schemas"]["BusinessScopeId"];
+        SubjectIdPath: components["schemas"]["SubjectId"];
         IdempotencyKey: string;
+        /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+        OptionalIdempotencyKey: string;
         MediaJobId: string;
         ConversationId: components["schemas"]["ConversationId"];
         SessionId: string;
@@ -2771,6 +4248,39 @@ interface operations {
             503: components["responses"]["Problem"];
         };
     };
+    listConversations: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                agent: string;
+                /** @description the side of the app; left out, the agent's template's */
+                experience_mode?: components["schemas"]["ExperienceMode"];
+                /** @description the business the person acts for; only with `experience_mode=business` */
+                business_scope_id?: components["schemas"]["BusinessScopeId"];
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Newest activity first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationPage"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
     getConversation: {
         parameters: {
             query?: never;
@@ -2797,6 +4307,78 @@ interface operations {
             410: components["responses"]["Problem"];
         };
     };
+    deleteConversation: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                /** @description v1-draft.24, optional: the agent the caller acts for; when given, the conversation must be this agent's, else `404` (the same answer as an unknown id) */
+                agent?: components["parameters"]["BindingAgent"];
+                /** @description v1-draft.24, optional: the side of the app the caller acts on; when given, the conversation must be bound to it, else `404` */
+                experience_mode?: components["parameters"]["BindingExperienceMode"];
+                /** @description v1-draft.24, optional: the business the caller acts for; when given, the conversation must be bound to it, else `404`. With `experience_mode: business` and no `business_scope_id`, a conversation bound to a business does not match. */
+                business_scope_id?: components["parameters"]["BindingBusinessScope"];
+            };
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationDeleted"];
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    listConversationMessages: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                /** @description v1-draft.24, optional: the agent the caller acts for; when given, the conversation must be this agent's, else `404` (the same answer as an unknown id) */
+                agent?: components["parameters"]["BindingAgent"];
+                /** @description v1-draft.24, optional: the side of the app the caller acts on; when given, the conversation must be bound to it, else `404` */
+                experience_mode?: components["parameters"]["BindingExperienceMode"];
+                /** @description v1-draft.24, optional: the business the caller acts for; when given, the conversation must be bound to it, else `404`. With `experience_mode: business` and no `business_scope_id`, a conversation bound to a business does not match. */
+                business_scope_id?: components["parameters"]["BindingBusinessScope"];
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The newest page first; oldest first within a page. From v1-draft.28 every page also carries `conversation`, the conversation's summary as the list gives it. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TimelinePage"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
     getSession: {
         parameters: {
             query?: never;
@@ -2820,7 +4402,7 @@ interface operations {
             404: components["responses"]["Problem"];
         };
     };
-    revokeSession: {
+    updateSessionContext: {
         parameters: {
             query?: never;
             header?: never;
@@ -2829,6 +4411,40 @@ interface operations {
             };
             cookie?: never;
         };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SessionContextUpdate"];
+            };
+        };
+        responses: {
+            /** @description The session's screen context now. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SessionContextState"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
+        };
+    };
+    revokeSession: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+                "Idempotency-Key"?: components["parameters"]["OptionalIdempotencyKey"];
+            };
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            cookie?: never;
+        };
         requestBody?: never;
         responses: {
             /** @description Revoked (idempotent) */
@@ -2841,12 +4457,16 @@ interface operations {
                 };
             };
             404: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
         };
     };
     refreshClientSecret: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+                "Idempotency-Key"?: components["parameters"]["OptionalIdempotencyKey"];
+            };
             path: {
                 session_id: components["parameters"]["SessionId"];
             };
@@ -2891,6 +4511,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
             409: components["responses"]["Problem"];
             429: components["responses"]["RateLimited"];
         };
@@ -2927,6 +4548,7 @@ interface operations {
                     "text/event-stream": string;
                 };
             };
+            403: components["responses"]["Problem"];
         };
     };
     createModerationJob: {
@@ -3005,6 +4627,30 @@ interface operations {
             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?: {
@@ -3303,6 +4949,121 @@ interface operations {
             };
         };
     };
+    getSubjectMemory: {
+        parameters: {
+            query?: {
+                experience_mode?: components["schemas"]["ExperienceMode"];
+                /** @description the business the person acts for; only with `experience_mode=business` */
+                business_scope_id?: components["schemas"]["BusinessScopeId"];
+            };
+            header?: never;
+            path: {
+                subject_id: components["parameters"]["SubjectIdPath"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SubjectMemory"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    putSubjectMemory: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                subject_id: components["parameters"]["SubjectIdPath"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SubjectMemoryChoice"];
+            };
+        };
+        responses: {
+            /** @description The choice as stored. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SubjectMemoryChoice"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    acknowledgeMemoryNotice: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                subject_id: components["parameters"]["SubjectIdPath"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    version: components["schemas"]["MemoryNoticeVersion"];
+                };
+            };
+        };
+        responses: {
+            /** @description Recorded. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    deleteMemoryPreference: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                subject_id: components["parameters"]["SubjectIdPath"];
+                preference_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Forgotten. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
     sendEvents: {
         parameters: {
             query?: never;
@@ -3433,6 +5194,59 @@ interface operations {
             403: components["responses"]["Problem"];
         };
     };
+    getAgentExperience: {
+        parameters: {
+            query?: {
+                /** @description the side of the app; left out, the agent's template's */
+                experience_mode?: components["schemas"]["ExperienceMode"];
+            };
+            header?: never;
+            path: {
+                agent: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    /** @description `private, max-age=60` */
+                    "Cache-Control"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentExperience"];
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    getMeta: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    /** @description `public, max-age=60` */
+                    "Cache-Control"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Meta"];
+                };
+            };
+        };
+    };
     getUsage: {
         parameters: {
             query?: {