@vinaverse/server 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/{vinaverse-v1.d-BVc4uyUd.d.ts → vinaverse-v1.d-DiulmRgx.d.ts}

@@ -15,11 +15,15 @@ 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`.
+         *     **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 +73,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 +119,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 +177,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 +226,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 +244,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 +264,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 +323,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;
@@ -1183,10 +1295,12 @@ interface components {
             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 */
@@ -1349,6 +1463,67 @@ 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"];
+        };
+        /**
+         * @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: {
+            /**
+             * @description A coarse screen from a fixed vocabulary; the tenant maps its own screens onto it. `other` when none fits. Customer side: `home`, `explore`, `search_results`, `professional`, `workspace`, `service`, `class`, `checkout`, `booking`, `bookings`, `inbox`, `profile`. Business side: `business_hub`, `setup`, `services`, `hours`, `location`, `gallery`, `spaces`, `space_manage`, `renters`, `payouts`, `plans`, `team`.
+             * @enum {string}
+             */
+            screen: "home" | "explore" | "search_results" | "professional" | "workspace" | "service" | "class" | "checkout" | "booking" | "bookings" | "inbox" | "profile" | "business_hub" | "setup" | "services" | "hours" | "location" | "gallery" | "spaces" | "space_manage" | "renters" | "payouts" | "plans" | "team" | "other";
+            /** @description the object on the screen, as the tenant's read tools name it; `id` is a tool id (letters, digits and `_`, `.`, `:`, `-`), since it reaches the agent's working notes */
+            entity?: {
+                /** @enum {string} */
+                type: "professional" | "workspace" | "service" | "class" | "booking" | "location";
+                id: string;
+            };
+            /** @description the filters the screen shows, typed; free text never */
+            filters?: {
+                service_ids?: string[];
+                category_ids?: string[];
+                area_id?: string;
+                /** Format: date */
+                date_from?: string;
+                /** Format: date */
+                date_to?: string;
+                price_max?: components["schemas"]["Money"];
+            };
+            /** @description the tenant's counter for this person's screen state; a later update never goes back to a lower one (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.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>`. */
@@ -1367,6 +1542,11 @@ interface components {
                 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 */
@@ -1381,6 +1561,14 @@ interface components {
             disclosure: string;
             /** @description The conversation this session belongs to, the same for every session of it, however it was resumed (by `conversation_key` or `conversation_id`). Present whenever the session belongs to a conversation: when the request named one, and for every guided-flow session. It is absent only for a session with no conversation, and optional in the schema so clients built on earlier drafts keep working. */
             conversation_id?: components["schemas"]["ConversationId"];
+            /** @description v1-draft.20, the session's mode, as given or as the agent's template sets it */
+            experience_mode?: components["schemas"]["ExperienceMode"];
+            /** @description v1-draft.20, present when the session acts for a business */
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            /** @description v1-draft.20, the screen context the session accepted, when `createSession` gave one */
+            screen_context?: components["schemas"]["ScreenContext"];
+            /** @description v1-draft.20, absent when the tenant's manifest has no welcome for the session's mode */
+            welcome?: components["schemas"]["Welcome"];
         };
         SessionStatus: {
             id: string;
@@ -1391,10 +1579,10 @@ interface components {
             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).
+             * @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";
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left" | "deleted";
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
@@ -1443,6 +1631,35 @@ 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. */
+        ScopeProvenance: {
+            policy_id: string;
+            version: string;
+            /** @enum {string} */
+            reason: "off_scope" | "competitor" | "blocked_topic";
+        };
         /**
          * @description `ref` is present on every customer-agent card (professional … handoff); copilot cards (metric_chart … document) may omit it, since a metric, cluster or claim is not a tenant object. A `question` card (guided flows) carries `question`, has no `actions` (the person answers with `ui.answer`), uses `title` as a short label for the question, and its `source` names the tool call that fetched the flow's definition.
          *     A `next_step` card is a step the person finishes on the tenant's own screen (payouts, a plan purchase, photos). It has a `title` (at most 80 code points), a `body` (at most 300) and exactly one action: `action: open`, with a `label` (at most 40) and a `deep_link`. It may omit `ref`, and its `source` names the tool call the step came from. - **Nothing is written.** Tapping the action opens `deep_link` in the tenant's app. The app sends no
@@ -1462,14 +1679,17 @@ 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.
          */
         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)
              * @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";
             question?: components["schemas"]["Question"];
             proposal?: components["schemas"]["Proposal"];
             ref?: components["schemas"]["CardRef"];
@@ -1477,6 +1697,17 @@ interface components {
             subtitle?: string;
             /** Format: uri */
             image_url?: string;
+            /** @description v1-draft.20, a `professional` or `workspace` card's photos, the first the hero */
+            images?: components["schemas"]["CardImage"][];
+            /**
+             * Format: date-time
+             * @description v1-draft.20, a `professional` or `workspace` card's earliest open time, as the tenant's tool returned it
+             */
+            next_available?: string;
+            group?: components["schemas"]["CardGroup"];
+            /** @description v1-draft.20, a `links` card's links */
+            links?: components["schemas"]["CardLink"][];
+            provenance?: components["schemas"]["ScopeProvenance"];
             rating?: {
                 value_ppm: number;
                 count: number;
@@ -1520,7 +1751,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 +1769,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;
                 };
@@ -1582,7 +1814,7 @@ interface components {
             snippet?: string;
             /** Format: date-time */
             updated_at?: string;
-        } & (unknown & unknown & unknown);
+        } & (unknown & unknown & unknown & unknown);
         /** @enum {string} */
         ValueUnit: "count" | "ppm" | "micros_usd" | "ms";
         MetricRef: {
@@ -1590,6 +1822,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 +2055,83 @@ 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. No message text: the title is from the conversation's last search intent or its date, never the person's words. */
+        ConversationSummary: {
+            id: components["schemas"]["ConversationId"];
+            agent: string;
+            experience_mode: components["schemas"]["ExperienceMode"];
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            title: string;
+            /**
+             * @description `intent`: the last search intent (service and place); `date`: the day it started
+             * @enum {string}
+             */
+            title_source: "intent" | "date";
+            /** Format: date-time */
+            started_at: string;
+            /** Format: date-time */
+            last_activity_at: string;
+            /** @description the messages its timeline holds (cards not counted) */
+            message_count: number;
+            /**
+             * @description `open`: a session can resume it; `ended`: it can only be read
+             * @enum {string}
+             */
+            state: "open" | "ended";
+        };
+        TimelinePage: {
+            data: components["schemas"]["TimelineItem"][];
+            /** @description the next older page; null at the conversation's start */
+            next_cursor: string | null;
+        };
+        /**
+         * @description v1-draft.21: one item of a past conversation, a message or a card its turn drew. `id` is stable and unique within the conversation; a message's `event_id` is its live event's identifier (`TranscriptItem.id`), the key an app merges live and resumed messages by, with `role`. A card is read-only in history.
+         *     Unlike `session.ready.transcript`, the history holds a guardrail's refusals: the person's message a guardrail refused and the fixed line said instead of an answer both carry `refusal: true`, so the app draws them as it drew them live (muted, never offered again). A `proposal` card carries `proposal_outcome`, what became of it.
+         */
+        TimelineItem: {
+            /** @constant */
+            type: "message";
+            id: string;
+            /**
+             * @description a client tolerates a role it does not know, as in `TranscriptItem`
+             * @enum {string}
+             */
+            role: "person" | "assistant" | "staff";
+            text: string;
+            /** Format: date-time */
+            at: string;
+            /** @description absent on a `person` message sent without a `client_event_id` */
+            event_id?: string;
+            turn_id?: string;
+            /** @description `assistant` only, present only when true: the reply stopped before it finished */
+            interrupted?: boolean;
+            /**
+             * @description Present only when true: a guardrail refused this turn. On a `person` message, the text it refused (as recorded, card-like digits masked); on an `assistant` message, the fixed line said instead of an answer.
+             * @constant
+             */
+            refusal?: true;
+        } | {
+            /** @constant */
+            type: "card";
+            id: string;
+            turn_id: string;
+            /** Format: date-time */
+            at: string;
+            card: components["schemas"]["Card"];
+            /**
+             * @description A `proposal` card only, always present on one: the outcome the app reported for it (`ui.action` `confirmed`, `declined`, `failed` or `expired`), or `pending` while none was reported. Draw it as settled; a past proposal is never confirmed from history.
+             * @enum {string}
+             */
+            proposal_outcome?: "pending" | "confirmed" | "declined" | "failed" | "expired";
+        };
+        ConversationDeleted: {
+            conversation_id: components["schemas"]["ConversationId"];
+            sessions_revoked: number;
+        };
         /** @description A time slot the person picked on a `time_slots` card (v1-draft.17, `docs/realtime-protocol.md` §6): the slot's `id`, and the `call_id` of the tool call the card came from (the card's `source.call_id`), so the runtime checks the pick against the evidence it holds for that call. Both are copied from the card; never built by the app. */
         SlotSelection: {
             id: string;
@@ -2002,6 +2312,10 @@ 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 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):
@@ -2106,6 +2420,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 +2437,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";
@@ -2695,7 +3018,15 @@ 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"];
         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 +3102,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 +3161,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. */
+            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 +3256,7 @@ interface operations {
             404: components["responses"]["Problem"];
         };
     };
-    revokeSession: {
+    updateSessionContext: {
         parameters: {
             query?: never;
             header?: never;
@@ -2829,6 +3265,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 +3311,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 +3365,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
             409: components["responses"]["Problem"];
             429: components["responses"]["RateLimited"];
         };
@@ -2927,6 +3402,7 @@ interface operations {
                     "text/event-stream": string;
                 };
             };
+            403: components["responses"]["Problem"];
         };
     };
     createModerationJob: {
@@ -3005,6 +3481,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?: {