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

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { A as AnswerInput, h as AuthMode, b as CONTRACT, c as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, C as ClientSecret, k as Connection, l as ConversationEngine, m as ConversationState, F as FetchLike, n as Frame, H as HeldCard, f as HeldQuestion, M as Message, g as Proposal, P as ProposalOutcome, Q as Question, R as Reconnect, o as ServerEvent, p as ServerEventOf, q as ServerEventType, r as SessionEvents, S as SessionInfo, a as SessionOptions, s as SessionStatus, t as SseTarget, T as ToolLine, u as TranscriptItem, v as TurnInput, V as VinaverseClientError, w as VinaverseSession, W as WebSocketFactory, x as WebSocketLike, y as cardActionSse, i as isKnownCard, z as sseFrames, B as turnSse } from './session--W6JXfwo.cjs';
+export { A as AnswerInput, l as AuthMode, b as CONTRACT, c as Card, f as CardKind, h as ClientErrorCode, m as ClientEvent, C as ClientSecret, n as Connection, o as ConversationEngine, p as ConversationState, F as FetchLike, q as Frame, H as HeldCard, i as HeldQuestion, M as Message, j as Proposal, P as ProposalOutcome, Q as Question, R as Reconnect, r as ServerEvent, s as ServerEventOf, t as ServerEventType, u as SessionEvents, S as SessionInfo, a as SessionOptions, v as SessionStatus, w as SseTarget, T as ToolLine, x as TranscriptItem, y as TurnInput, V as VinaverseClientError, z as VinaverseSession, B as WebSocketFactory, D as WebSocketLike, E as cardActionSse, k as isKnownCard, G as sseFrames, I as turnSse } from './session-C3qZwGPG.cjs';
 
 /**
  * The client secret, checked: an app holds only the session's `vv_cs_` secret, which the tenant's backend got from

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AnswerInput, h as AuthMode, b as CONTRACT, c as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, C as ClientSecret, k as Connection, l as ConversationEngine, m as ConversationState, F as FetchLike, n as Frame, H as HeldCard, f as HeldQuestion, M as Message, g as Proposal, P as ProposalOutcome, Q as Question, R as Reconnect, o as ServerEvent, p as ServerEventOf, q as ServerEventType, r as SessionEvents, S as SessionInfo, a as SessionOptions, s as SessionStatus, t as SseTarget, T as ToolLine, u as TranscriptItem, v as TurnInput, V as VinaverseClientError, w as VinaverseSession, W as WebSocketFactory, x as WebSocketLike, y as cardActionSse, i as isKnownCard, z as sseFrames, B as turnSse } from './session--W6JXfwo.js';
+export { A as AnswerInput, l as AuthMode, b as CONTRACT, c as Card, f as CardKind, h as ClientErrorCode, m as ClientEvent, C as ClientSecret, n as Connection, o as ConversationEngine, p as ConversationState, F as FetchLike, q as Frame, H as HeldCard, i as HeldQuestion, M as Message, j as Proposal, P as ProposalOutcome, Q as Question, R as Reconnect, r as ServerEvent, s as ServerEventOf, t as ServerEventType, u as SessionEvents, S as SessionInfo, a as SessionOptions, v as SessionStatus, w as SseTarget, T as ToolLine, x as TranscriptItem, y as TurnInput, V as VinaverseClientError, z as VinaverseSession, B as WebSocketFactory, D as WebSocketLike, E as cardActionSse, k as isKnownCard, G as sseFrames, I as turnSse } from './session-C3qZwGPG.js';
 
 /**
  * The client secret, checked: an app holds only the session's `vv_cs_` secret, which the tenant's backend got from

package/dist/index.js

@@ -1,3 +1,3 @@
-export { CONTRACT, ConversationEngine, VinaverseClientError, VinaverseSession, cardActionSse, clientSecret, isKnownCard, sseFrames, turnSse } from './chunk-AWHPWRGT.js';
+export { CONTRACT, ConversationEngine, VinaverseClientError, VinaverseSession, cardActionSse, clientSecret, isKnownCard, sseFrames, turnSse } from './chunk-MKUNSAMT.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{session--W6JXfwo.d.cts → session-C3qZwGPG.d.cts}

@@ -1,6 +1,6 @@
 declare const CONTRACT: {
-    readonly api: "v1-draft.17";
-    readonly commit: "fe4fb7d2945e1ced2bce7d44e85a4b28005e46df";
+    readonly api: "v1-draft.20";
+    readonly commit: "5f6f41bdbfbdd6eadf21180eed1ffddfa5310355";
 };
 
 /** A frame as received or sent: its `type`, and whatever else the contract gives it. */
@@ -187,6 +187,12 @@ declare class ConversationEngine {
     sent(event: Frame): void;
     received(event: Frame): void;
     private ready;
+    /**
+     * A transcript merged by key: an item the app holds keeps its place, with the text the server recorded; one it does
+     * not hold goes just after the nearest earlier item it does (just before the first later one when none came before,
+     * at the end when it holds none of them). Nothing the app holds is dropped.
+     */
+    private mergeTranscript;
     private hold;
     private recorded;
     private rejected;
@@ -411,6 +417,56 @@ 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; live updates are a later addition. Never arbitrary page text, URLs, names, amounts or instructions: only these fields, from this vocabulary. */
+        ScreenContext: {
+            /**
+             * @description A coarse screen from a fixed vocabulary; the tenant maps its own screens onto it. `other` when none fits. Customer side: `home`, `explore`, `search_results`, `professional`, `workspace`, `service`, `class`, `checkout`, `booking`, `bookings`, `inbox`, `profile`. Business side: `business_hub`, `setup`, `services`, `hours`, `location`, `gallery`, `spaces`, `space_manage`, `renters`, `payouts`, `plans`, `team`.
+             * @enum {string}
+             */
+            screen: "home" | "explore" | "search_results" | "professional" | "workspace" | "service" | "class" | "checkout" | "booking" | "bookings" | "inbox" | "profile" | "business_hub" | "setup" | "services" | "hours" | "location" | "gallery" | "spaces" | "space_manage" | "renters" | "payouts" | "plans" | "team" | "other";
+            /** @description the object on the screen, as the tenant's read tools name it; `id` is a tool id (letters, digits and `_`, `.`, `:`, `-`), since it reaches the agent's working notes */
+            entity?: {
+                /** @enum {string} */
+                type: "professional" | "workspace" | "service" | "class" | "booking" | "location";
+                id: string;
+            };
+            /** @description the filters the screen shows, typed; free text never */
+            filters?: {
+                service_ids?: string[];
+                category_ids?: string[];
+                area_id?: string;
+                /** Format: date */
+                date_from?: string;
+                /** Format: date */
+                date_to?: string;
+                price_max?: components["schemas"]["Money"];
+            };
+            /** @description the tenant's counter for this person's screen state; a later update never goes back to a lower one */
+            revision: number;
+        };
+        /** @description v1-draft.20: a tap target the app draws under the welcome. Tapping it sends `message` as the person's own text (an `input.text`, or `createTurnSse`), exactly as if they typed it; it starts nothing else. */
+        Chip: {
+            /** @description in Unicode code points */
+            label: string;
+            /** @description in Unicode code points */
+            message: string;
+        };
+        /** @description v1-draft.20: the tenant's greeting for the session's mode, with the chips of the session's screen when its manifest has some for it (else the mode's own), from the connector manifest (admin-v1 `Connector.welcome`), checked when the manifest loads. The app shows it the moment the session is ready: it costs no model call and is not a turn. The agent knows it was shown and does not greet again. */
+        Welcome: {
+            /** @description in Unicode code points */
+            text: string;
+            chips: components["schemas"]["Chip"][];
         };
         ClientSecret: {
             /** @description `vv_cs_` and base64url characters, so the secret is a valid WebSocket subprotocol token in `bearer.<secret>`. */
@@ -429,6 +485,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 */
@@ -443,6 +504,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;
@@ -505,6 +574,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
@@ -524,14 +622,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"];
@@ -539,6 +640,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;
@@ -582,7 +694,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;
                 }[];
@@ -600,6 +712,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;
                 };
@@ -644,7 +757,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: {
@@ -652,6 +765,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. */
@@ -1064,6 +1178,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):
@@ -1785,6 +1903,11 @@ type Proposal = Schemas['Proposal'];
 type TranscriptItem = Schemas['TranscriptItem'];
 type ClientSecret = Schemas['ClientSecret'];
 type TurnInput = Schemas['TurnInput'];
+/** v1-draft.20: the tenant's greeting for the session's mode, and the chips that send a message as the person's own. */
+type Welcome = Schemas['Welcome'];
+type CardImage = Schemas['CardImage'];
+type CardGroup = Schemas['CardGroup'];
+type CardLink = Schemas['CardLink'];
 /** The session as createSession returns it to the tenant's backend, which passes this part to the app. */
 type SessionInfo = Pick<Schemas['Session'], 'id' | 'realtime_url' | 'turns_url' | 'conversation_id'> & {
     client_secret: ClientSecret | string;
@@ -2025,4 +2148,4 @@ declare class VinaverseSession {
     private emit;
 }
 
-export { type AnswerInput as A, turnSse as B, type ClientSecret as C, type FetchLike as F, type HeldCard as H, type Message as M, type ProposalOutcome as P, type Question as Q, type Reconnect as R, type SessionInfo as S, type ToolLine as T, VinaverseClientError as V, type WebSocketFactory as W, type SessionOptions as a, CONTRACT as b, type Card as c, type CardKind as d, type ClientErrorCode as e, type HeldQuestion as f, type Proposal as g, type AuthMode as h, isKnownCard as i, type ClientEvent as j, type Connection as k, ConversationEngine as l, type ConversationState as m, type Frame as n, type ServerEvent as o, type ServerEventOf as p, type ServerEventType as q, type SessionEvents as r, type SessionStatus as s, type SseTarget as t, type TranscriptItem as u, type TurnInput as v, VinaverseSession as w, type WebSocketLike as x, cardActionSse as y, sseFrames as z };
+export { type AnswerInput as A, type WebSocketFactory as B, type ClientSecret as C, type WebSocketLike as D, cardActionSse as E, type FetchLike as F, sseFrames as G, type HeldCard as H, turnSse as I, type Message as M, type ProposalOutcome as P, type Question as Q, type Reconnect as R, type SessionInfo as S, type ToolLine as T, VinaverseClientError as V, type Welcome as W, type SessionOptions as a, CONTRACT as b, type Card as c, type CardGroup as d, type CardImage as e, type CardKind as f, type CardLink as g, type ClientErrorCode as h, type HeldQuestion as i, type Proposal as j, isKnownCard as k, type AuthMode as l, type ClientEvent as m, type Connection as n, ConversationEngine as o, type ConversationState as p, type Frame as q, type ServerEvent as r, type ServerEventOf as s, type ServerEventType as t, type SessionEvents as u, type SessionStatus as v, type SseTarget as w, type TranscriptItem as x, type TurnInput as y, VinaverseSession as z };

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

@@ -1,6 +1,6 @@
 declare const CONTRACT: {
-    readonly api: "v1-draft.17";
-    readonly commit: "fe4fb7d2945e1ced2bce7d44e85a4b28005e46df";
+    readonly api: "v1-draft.20";
+    readonly commit: "5f6f41bdbfbdd6eadf21180eed1ffddfa5310355";
 };
 
 /** A frame as received or sent: its `type`, and whatever else the contract gives it. */
@@ -187,6 +187,12 @@ declare class ConversationEngine {
     sent(event: Frame): void;
     received(event: Frame): void;
     private ready;
+    /**
+     * A transcript merged by key: an item the app holds keeps its place, with the text the server recorded; one it does
+     * not hold goes just after the nearest earlier item it does (just before the first later one when none came before,
+     * at the end when it holds none of them). Nothing the app holds is dropped.
+     */
+    private mergeTranscript;
     private hold;
     private recorded;
     private rejected;
@@ -411,6 +417,56 @@ 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; live updates are a later addition. Never arbitrary page text, URLs, names, amounts or instructions: only these fields, from this vocabulary. */
+        ScreenContext: {
+            /**
+             * @description A coarse screen from a fixed vocabulary; the tenant maps its own screens onto it. `other` when none fits. Customer side: `home`, `explore`, `search_results`, `professional`, `workspace`, `service`, `class`, `checkout`, `booking`, `bookings`, `inbox`, `profile`. Business side: `business_hub`, `setup`, `services`, `hours`, `location`, `gallery`, `spaces`, `space_manage`, `renters`, `payouts`, `plans`, `team`.
+             * @enum {string}
+             */
+            screen: "home" | "explore" | "search_results" | "professional" | "workspace" | "service" | "class" | "checkout" | "booking" | "bookings" | "inbox" | "profile" | "business_hub" | "setup" | "services" | "hours" | "location" | "gallery" | "spaces" | "space_manage" | "renters" | "payouts" | "plans" | "team" | "other";
+            /** @description the object on the screen, as the tenant's read tools name it; `id` is a tool id (letters, digits and `_`, `.`, `:`, `-`), since it reaches the agent's working notes */
+            entity?: {
+                /** @enum {string} */
+                type: "professional" | "workspace" | "service" | "class" | "booking" | "location";
+                id: string;
+            };
+            /** @description the filters the screen shows, typed; free text never */
+            filters?: {
+                service_ids?: string[];
+                category_ids?: string[];
+                area_id?: string;
+                /** Format: date */
+                date_from?: string;
+                /** Format: date */
+                date_to?: string;
+                price_max?: components["schemas"]["Money"];
+            };
+            /** @description the tenant's counter for this person's screen state; a later update never goes back to a lower one */
+            revision: number;
+        };
+        /** @description v1-draft.20: a tap target the app draws under the welcome. Tapping it sends `message` as the person's own text (an `input.text`, or `createTurnSse`), exactly as if they typed it; it starts nothing else. */
+        Chip: {
+            /** @description in Unicode code points */
+            label: string;
+            /** @description in Unicode code points */
+            message: string;
+        };
+        /** @description v1-draft.20: the tenant's greeting for the session's mode, with the chips of the session's screen when its manifest has some for it (else the mode's own), from the connector manifest (admin-v1 `Connector.welcome`), checked when the manifest loads. The app shows it the moment the session is ready: it costs no model call and is not a turn. The agent knows it was shown and does not greet again. */
+        Welcome: {
+            /** @description in Unicode code points */
+            text: string;
+            chips: components["schemas"]["Chip"][];
         };
         ClientSecret: {
             /** @description `vv_cs_` and base64url characters, so the secret is a valid WebSocket subprotocol token in `bearer.<secret>`. */
@@ -429,6 +485,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 */
@@ -443,6 +504,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;
@@ -505,6 +574,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
@@ -524,14 +622,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"];
@@ -539,6 +640,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;
@@ -582,7 +694,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;
                 }[];
@@ -600,6 +712,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;
                 };
@@ -644,7 +757,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: {
@@ -652,6 +765,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. */
@@ -1064,6 +1178,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):
@@ -1785,6 +1903,11 @@ type Proposal = Schemas['Proposal'];
 type TranscriptItem = Schemas['TranscriptItem'];
 type ClientSecret = Schemas['ClientSecret'];
 type TurnInput = Schemas['TurnInput'];
+/** v1-draft.20: the tenant's greeting for the session's mode, and the chips that send a message as the person's own. */
+type Welcome = Schemas['Welcome'];
+type CardImage = Schemas['CardImage'];
+type CardGroup = Schemas['CardGroup'];
+type CardLink = Schemas['CardLink'];
 /** The session as createSession returns it to the tenant's backend, which passes this part to the app. */
 type SessionInfo = Pick<Schemas['Session'], 'id' | 'realtime_url' | 'turns_url' | 'conversation_id'> & {
     client_secret: ClientSecret | string;
@@ -2025,4 +2148,4 @@ declare class VinaverseSession {
     private emit;
 }
 
-export { type AnswerInput as A, turnSse as B, type ClientSecret as C, type FetchLike as F, type HeldCard as H, type Message as M, type ProposalOutcome as P, type Question as Q, type Reconnect as R, type SessionInfo as S, type ToolLine as T, VinaverseClientError as V, type WebSocketFactory as W, type SessionOptions as a, CONTRACT as b, type Card as c, type CardKind as d, type ClientErrorCode as e, type HeldQuestion as f, type Proposal as g, type AuthMode as h, isKnownCard as i, type ClientEvent as j, type Connection as k, ConversationEngine as l, type ConversationState as m, type Frame as n, type ServerEvent as o, type ServerEventOf as p, type ServerEventType as q, type SessionEvents as r, type SessionStatus as s, type SseTarget as t, type TranscriptItem as u, type TurnInput as v, VinaverseSession as w, type WebSocketLike as x, cardActionSse as y, sseFrames as z };
+export { type AnswerInput as A, type WebSocketFactory as B, type ClientSecret as C, type WebSocketLike as D, cardActionSse as E, type FetchLike as F, sseFrames as G, type HeldCard as H, turnSse as I, type Message as M, type ProposalOutcome as P, type Question as Q, type Reconnect as R, type SessionInfo as S, type ToolLine as T, VinaverseClientError as V, type Welcome as W, type SessionOptions as a, CONTRACT as b, type Card as c, type CardGroup as d, type CardImage as e, type CardKind as f, type CardLink as g, type ClientErrorCode as h, type HeldQuestion as i, type Proposal as j, isKnownCard as k, type AuthMode as l, type ClientEvent as m, type Connection as n, ConversationEngine as o, type ConversationState as p, type Frame as q, type ServerEvent as r, type ServerEventOf as s, type ServerEventType as t, type SessionEvents as u, type SessionStatus as v, type SseTarget as w, type TranscriptItem as x, type TurnInput as y, VinaverseSession as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinaverse/client",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Vinaverse for apps: the realtime session client (WebSocket with SSE fallback, resume, typed events and cards). No UI.",
   "license": "Apache-2.0",
   "author": "Vinaverse, Inc.",
@@ -63,16 +63,16 @@
   },
   "size-limit": [
     {
-      "name": "@vinaverse/client (ESM, everything; why 6.7 kB: docs/architecture/client.md, Size budget)",
+      "name": "@vinaverse/client (ESM, everything; why 7 kB: docs/architecture/client.md, Size budget)",
       "path": "dist/index.js",
       "import": "*",
-      "limit": "6.7 kB"
+      "limit": "7 kB"
     },
     {
       "name": "@vinaverse/client/conversation (ESM, everything, the session included; docs/architecture/conversation.md, Size budget)",
       "path": "dist/conversation/index.js",
       "import": "*",
-      "limit": "12 kB"
+      "limit": "13 kB"
     }
   ],
   "scripts": {