@vinaverse/server 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/{vinaverse-v1.d-BVc4uyUd.d.ts → vinaverse-v1.d-DGSY4GsY.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,
@@ -158,7 +162,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 +182,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 +241,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;
@@ -1349,6 +1379,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>`. */
@@ -1367,6 +1447,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 +1466,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;
@@ -1443,6 +1536,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 +1584,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 +1602,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 +1656,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 +1674,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 +1719,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 +1727,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. */
@@ -2002,6 +2140,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):
@@ -2891,6 +3033,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
             409: components["responses"]["Problem"];
             429: components["responses"]["RateLimited"];
         };
@@ -2927,6 +3070,7 @@ interface operations {
                     "text/event-stream": string;
                 };
             };
+            403: components["responses"]["Problem"];
         };
     };
     createModerationJob: {
@@ -3005,6 +3149,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?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinaverse/server",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Vinaverse for Node backends: verify webhooks into typed contract events, with adapters for AWS Lambda, Express, Fastify and Hono, serve tools, and call the Vinaverse API typed.",
   "license": "Apache-2.0",
   "author": "Vinaverse, Inc.",