@vinaverse/client 0.1.0-alpha.10 → 0.1.0-alpha.11

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-export { C as CONTRACT } from './contract-DmQs8amJ.cjs';
-export { A as AnswerInput, h as AuthMode, a as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, k as ClientSecret, l as Connection, m as ConversationEngine, n as ConversationState, F as FetchLike, o as Frame, H as HeldCard, f as HeldQuestion, M as Message, P as Proposal, g as ProposalOutcome, Q as Question, R as Reconnect, S as Schemas, p as ServerEvent, q as ServerEventOf, r as ServerEventType, s as SessionEvents, t as SessionInfo, u 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, G as components, i as isKnownCard, I as operations, J as paths, K as sseFrames, L as turnSse } from './session-CPz4pcPu.cjs';
+export { C as CONTRACT } from './contract-Be2oVHNr.cjs';
+export { A as AnswerInput, h as AuthMode, a as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, k as ClientSecret, l as Connection, m as ConversationEngine, n as ConversationState, F as FetchLike, o as Frame, H as HeldCard, f as HeldQuestion, M as Message, P as Proposal, g as ProposalOutcome, Q as Question, R as Reconnect, S as Schemas, p as ServerEvent, q as ServerEventOf, r as ServerEventType, s as SessionEvents, t as SessionInfo, u 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, G as components, i as isKnownCard, I as operations, J as paths, K as sseFrames, L as turnSse } from './session-D0ijOQX3.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,5 +1,5 @@
-export { C as CONTRACT } from './contract-DmQs8amJ.js';
-export { A as AnswerInput, h as AuthMode, a as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, k as ClientSecret, l as Connection, m as ConversationEngine, n as ConversationState, F as FetchLike, o as Frame, H as HeldCard, f as HeldQuestion, M as Message, P as Proposal, g as ProposalOutcome, Q as Question, R as Reconnect, S as Schemas, p as ServerEvent, q as ServerEventOf, r as ServerEventType, s as SessionEvents, t as SessionInfo, u 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, G as components, i as isKnownCard, I as operations, J as paths, K as sseFrames, L as turnSse } from './session-CPz4pcPu.js';
+export { C as CONTRACT } from './contract-Be2oVHNr.js';
+export { A as AnswerInput, h as AuthMode, a as Card, d as CardKind, e as ClientErrorCode, j as ClientEvent, k as ClientSecret, l as Connection, m as ConversationEngine, n as ConversationState, F as FetchLike, o as Frame, H as HeldCard, f as HeldQuestion, M as Message, P as Proposal, g as ProposalOutcome, Q as Question, R as Reconnect, S as Schemas, p as ServerEvent, q as ServerEventOf, r as ServerEventType, s as SessionEvents, t as SessionInfo, u 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, G as components, i as isKnownCard, I as operations, J as paths, K as sseFrames, L as turnSse } from './session-D0ijOQX3.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,4 +1,4 @@
-export { CONTRACT } from './chunk-YNUHXJD6.js';
+export { CONTRACT } from './chunk-D56MNG3E.js';
 export { ConversationEngine, VinaverseClientError, VinaverseSession, cardActionSse, clientSecret, isKnownCard, sseFrames, turnSse } from './chunk-GWLLUOFY.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{runtime-Z1RI10lU.d.ts → runtime-6O0qIPmo.d.cts}

@@ -1,5 +1,5 @@
-import { S as SessionRequest, b as ConversationSession, C as ConversationStore, f as ConversationPersistence, a as ConversationOptions } from './store-DZka9T2-.js';
-import { S as Schemas, k as ClientSecret } from './session-CPz4pcPu.js';
+import { S as SessionRequest, b as ConversationSession, C as ConversationStore, f as ConversationPersistence, a as ConversationOptions } from './store-CxoHwd64.cjs';
+import { S as Schemas, k as ClientSecret } from './session-D0ijOQX3.cjs';
 
 /** Whose conversation: a person (null for a guest), the app's side, the business acted for, and the thread. */
 interface AgentKey {
@@ -144,6 +144,22 @@ interface AgentBackend {
     endSessions?(): Promise<void>;
     /** History's delete: the tenant's API deletes the person's conversation (authenticated, theirs only). */
     deleteConversation?(conversationId: string): Promise<void>;
+    /**
+     * History: the person's past conversations with the agent, newest activity first, a page at a time (`cursor` from
+     * the page before). The person comes from the backend's authentication, never from here.
+     */
+    listConversations?(query: {
+        readonly mode: string;
+        readonly scope: string | null;
+        readonly agent: string | null;
+        readonly limit?: number;
+        readonly cursor: string | null;
+    }, signal?: AbortSignal): Promise<Schemas['ConversationPage']>;
+    /** History: a past conversation's messages and cards, the newest page first, oldest first within a page. */
+    readConversation?(conversationId: string, page: {
+        readonly limit?: number;
+        readonly cursor: string | null;
+    }, signal?: AbortSignal): Promise<Schemas['TimelinePage']>;
 }
 type AgentRating = 'up' | 'down';
 type AgentFailure = 'ended' | 'unreachable' | 'unavailable';
@@ -283,6 +299,8 @@ interface AgentInsecureAddresses {
     readonly turns?: boolean;
 }
 interface AgentRuntime {
+    /** The app's backend, as given: history (`@vinaverse/client/history`) reads its pages through it. */
+    readonly backend: AgentBackend;
     /** The key's conversation: the same while it lives; a new one after `startNew`, `dispose` or its end. */
     conversation(key: AgentKey): AgentConversation;
     /**
@@ -338,6 +356,11 @@ interface AgentRuntime {
      * (the status held before, if any, stays). One object until it changes, for `useSyncExternalStore`.
      */
     getStatusState(): AgentStatusState;
+    /**
+     * Which person's turn it is on this device: a number that changes at every sign-out and erasure. Work begun under an
+     * older one (a history page, a transcript) is dropped when it lands.
+     */
+    epoch(): number;
     /** The agent's name: from the newest session, else from the status. */
     getName(): string | null;
     /** Told when the status or name changes, and when a key's conversation is let go (its next one is another). */

package/dist/{runtime-CISPp9nJ.d.cts → runtime-CNgz2_8G.d.ts}

@@ -1,5 +1,5 @@
-import { S as SessionRequest, b as ConversationSession, C as ConversationStore, f as ConversationPersistence, a as ConversationOptions } from './store-BxiicOKG.cjs';
-import { S as Schemas, k as ClientSecret } from './session-CPz4pcPu.cjs';
+import { S as SessionRequest, b as ConversationSession, C as ConversationStore, f as ConversationPersistence, a as ConversationOptions } from './store-CGRSxVcL.js';
+import { S as Schemas, k as ClientSecret } from './session-D0ijOQX3.js';
 
 /** Whose conversation: a person (null for a guest), the app's side, the business acted for, and the thread. */
 interface AgentKey {
@@ -144,6 +144,22 @@ interface AgentBackend {
     endSessions?(): Promise<void>;
     /** History's delete: the tenant's API deletes the person's conversation (authenticated, theirs only). */
     deleteConversation?(conversationId: string): Promise<void>;
+    /**
+     * History: the person's past conversations with the agent, newest activity first, a page at a time (`cursor` from
+     * the page before). The person comes from the backend's authentication, never from here.
+     */
+    listConversations?(query: {
+        readonly mode: string;
+        readonly scope: string | null;
+        readonly agent: string | null;
+        readonly limit?: number;
+        readonly cursor: string | null;
+    }, signal?: AbortSignal): Promise<Schemas['ConversationPage']>;
+    /** History: a past conversation's messages and cards, the newest page first, oldest first within a page. */
+    readConversation?(conversationId: string, page: {
+        readonly limit?: number;
+        readonly cursor: string | null;
+    }, signal?: AbortSignal): Promise<Schemas['TimelinePage']>;
 }
 type AgentRating = 'up' | 'down';
 type AgentFailure = 'ended' | 'unreachable' | 'unavailable';
@@ -283,6 +299,8 @@ interface AgentInsecureAddresses {
     readonly turns?: boolean;
 }
 interface AgentRuntime {
+    /** The app's backend, as given: history (`@vinaverse/client/history`) reads its pages through it. */
+    readonly backend: AgentBackend;
     /** The key's conversation: the same while it lives; a new one after `startNew`, `dispose` or its end. */
     conversation(key: AgentKey): AgentConversation;
     /**
@@ -338,6 +356,11 @@ interface AgentRuntime {
      * (the status held before, if any, stays). One object until it changes, for `useSyncExternalStore`.
      */
     getStatusState(): AgentStatusState;
+    /**
+     * Which person's turn it is on this device: a number that changes at every sign-out and erasure. Work begun under an
+     * older one (a history page, a transcript) is dropped when it lands.
+     */
+    epoch(): number;
     /** The agent's name: from the newest session, else from the status. */
     getName(): string | null;
     /** Told when the status or name changes, and when a key's conversation is let go (its next one is another). */

package/dist/{session-CPz4pcPu.d.cts → session-D0ijOQX3.d.cts}

@@ -130,7 +130,7 @@ interface paths {
          *     - 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, 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.
+         *     **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;
@@ -150,7 +150,7 @@ interface paths {
          * @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: `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.
+         *     **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;
@@ -177,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;
@@ -556,10 +578,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 */
@@ -733,7 +757,7 @@ interface components {
         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. */
+        /** @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`.
@@ -757,8 +781,19 @@ interface components {
                 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 */
+            /** @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: {
@@ -1668,6 +1703,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";
@@ -2257,6 +2301,12 @@ 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;
@@ -2398,6 +2448,12 @@ interface operations {
         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: {
@@ -2426,6 +2482,12 @@ interface operations {
         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;
             };
@@ -2477,6 +2539,37 @@ interface operations {
             404: components["responses"]["Problem"];
         };
     };
+    updateSessionContext: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            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;

package/dist/{session-CPz4pcPu.d.ts → session-D0ijOQX3.d.ts}

@@ -130,7 +130,7 @@ interface paths {
          *     - 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, 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.
+         *     **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;
@@ -150,7 +150,7 @@ interface paths {
          * @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: `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.
+         *     **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;
@@ -177,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;
@@ -556,10 +578,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 */
@@ -733,7 +757,7 @@ interface components {
         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. */
+        /** @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`.
@@ -757,8 +781,19 @@ interface components {
                 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 */
+            /** @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: {
@@ -1668,6 +1703,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";
@@ -2257,6 +2301,12 @@ 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;
@@ -2398,6 +2448,12 @@ interface operations {
         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: {
@@ -2426,6 +2482,12 @@ interface operations {
         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;
             };
@@ -2477,6 +2539,37 @@ interface operations {
             404: components["responses"]["Problem"];
         };
     };
+    updateSessionContext: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                session_id: components["parameters"]["SessionId"];
+            };
+            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;

package/dist/{store-DZka9T2-.d.ts → store-CGRSxVcL.d.ts}

@@ -1,4 +1,4 @@
-import { W as Welcome, H as HeldCard, T as ToolLine, t as SessionInfo, k as ClientSecret, u as SessionOptions, A as AnswerInput, g as ProposalOutcome } from './session-CPz4pcPu.js';
+import { W as Welcome, H as HeldCard, T as ToolLine, t as SessionInfo, k as ClientSecret, u as SessionOptions, A as AnswerInput, g as ProposalOutcome } from './session-D0ijOQX3.js';
 
 type ConversationStatus = 
 /** Asking the tenant's backend for a session. */

package/dist/{store-BxiicOKG.d.cts → store-CxoHwd64.d.cts}

@@ -1,4 +1,4 @@
-import { W as Welcome, H as HeldCard, T as ToolLine, t as SessionInfo, k as ClientSecret, u as SessionOptions, A as AnswerInput, g as ProposalOutcome } from './session-CPz4pcPu.cjs';
+import { W as Welcome, H as HeldCard, T as ToolLine, t as SessionInfo, k as ClientSecret, u as SessionOptions, A as AnswerInput, g as ProposalOutcome } from './session-D0ijOQX3.cjs';
 
 type ConversationStatus = 
 /** Asking the tenant's backend for a session. */