@helpai/elements 0.25.0 → 0.26.0

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-B0uvvJYK.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, H as HandshakeResponse, L as Link, P as PAGE_AREA_SUGGESTIONS, f as PageContext, S as ServerConfig, b as SiteConfig, U as UserContext, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial, g as assetSchema, h as blocksConfigSchema, i as connectionConfigPartialSchema, j as connectionConfigSchema, k as cssColorSchema, l as cssLengthSchema, m as endpointsSchema, n as handshakeResponseSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, u as userContextSchema, t as uuid7Schema, w as widgetConfigPartialSchema, v as widgetConfigSchema, x as widgetSettingsPartialSchema, y as widgetSettingsSchema } from './deployment-2pMWV4oW.js';
 import { z } from 'zod';
 
 /**
@@ -56,9 +56,9 @@ declare const presentationSchema: z.ZodObject<{
         inset: z.ZodOptional<z.ZodString>;
         initialSize: z.ZodDefault<z.ZodEnum<{
             fullscreen: "fullscreen";
+            normal: "normal";
             expanded: "expanded";
             auto: "auto";
-            normal: "normal";
         }>>;
         autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
     }, z.core.$loose>>;
@@ -148,9 +148,9 @@ declare const launcherSizeSchema: z.ZodEnum<{
 }>;
 type LauncherSize = z.infer<typeof launcherSizeSchema>;
 declare const calloutShapeSchema: z.ZodEnum<{
-    callout: "callout";
     pill: "pill";
     bubble: "bubble";
+    callout: "callout";
 }>;
 type CalloutShape = z.infer<typeof calloutShapeSchema>;
 declare const calloutPositionSchema: z.ZodEnum<{
@@ -162,9 +162,9 @@ type CalloutPosition = z.infer<typeof calloutPositionSchema>;
 declare const launcherCalloutSchema: z.ZodObject<{
     text: z.ZodDefault<z.ZodString>;
     shape: z.ZodDefault<z.ZodEnum<{
-        callout: "callout";
         pill: "pill";
         bubble: "bubble";
+        callout: "callout";
     }>>;
     position: z.ZodDefault<z.ZodEnum<{
         auto: "auto";
@@ -195,9 +195,9 @@ declare const launcherOptionsSchema: z.ZodObject<{
     callout: z.ZodOptional<z.ZodObject<{
         text: z.ZodDefault<z.ZodString>;
         shape: z.ZodDefault<z.ZodEnum<{
-            callout: "callout";
             pill: "pill";
             bubble: "bubble";
+            callout: "callout";
         }>>;
         position: z.ZodDefault<z.ZodEnum<{
             auto: "auto";
@@ -240,9 +240,9 @@ type LauncherOptions = z.infer<typeof launcherOptionsSchema>;
 
 declare const initialSizeSchema: z.ZodEnum<{
     fullscreen: "fullscreen";
+    normal: "normal";
     expanded: "expanded";
     auto: "auto";
-    normal: "normal";
 }>;
 declare const resizeOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -269,9 +269,9 @@ declare const sizeOptionsSchema: z.ZodObject<{
     inset: z.ZodOptional<z.ZodString>;
     initialSize: z.ZodDefault<z.ZodEnum<{
         fullscreen: "fullscreen";
+        normal: "normal";
         expanded: "expanded";
         auto: "auto";
-        normal: "normal";
     }>>;
     autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
 }, z.core.$loose>;
@@ -323,43 +323,43 @@ type FeatureFlags = z.infer<typeof featureFlagsSchema>;
  */
 
 declare const actionNameSchema: z.ZodEnum<{
-    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    clear: "clear";
-    theme: "theme";
+    close: "close";
     language: "language";
+    theme: "theme";
     textSize: "textSize";
     history: "history";
+    clear: "clear";
     sound: "sound";
 }>;
 type ActionName = z.infer<typeof actionNameSchema>;
 declare const headerActionsSchema: z.ZodArray<z.ZodEnum<{
-    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    clear: "clear";
-    theme: "theme";
+    close: "close";
     language: "language";
+    theme: "theme";
     textSize: "textSize";
     history: "history";
+    clear: "clear";
     sound: "sound";
 }>>;
 type HeaderActions = z.infer<typeof headerActionsSchema>;
 /** Section wrapper — `actions` list wrapped under `header` in the dashboard form. */
 declare const headerSchema: z.ZodObject<{
     actions: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        close: "close";
         expand: "expand";
         fullscreen: "fullscreen";
         popOut: "popOut";
-        clear: "clear";
-        theme: "theme";
+        close: "close";
         language: "language";
+        theme: "theme";
         textSize: "textSize";
         history: "history";
+        clear: "clear";
         sound: "sound";
     }>>>;
 }, z.core.$loose>;
@@ -375,33 +375,33 @@ type HeaderOptions = z.infer<typeof headerSchema>;
  */
 
 declare const feedbackEventSchema: z.ZodEnum<{
-    voiceStart: "voiceStart";
-    voiceStop: "voiceStop";
     error: "error";
     messageReceived: "messageReceived";
     messageSent: "messageSent";
+    voiceStart: "voiceStart";
+    voiceStop: "voiceStop";
 }>;
 type FeedbackEvent = z.infer<typeof feedbackEventSchema>;
 declare const soundOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     volume: z.ZodDefault<z.ZodNumber>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
 }, z.core.$loose>;
 type SoundOptions = z.infer<typeof soundOptionsSchema>;
 declare const hapticsOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
 }, z.core.$loose>;
 type HapticsOptions = z.infer<typeof hapticsOptionsSchema>;
@@ -410,21 +410,21 @@ declare const feedbackSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         volume: z.ZodDefault<z.ZodNumber>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
     }, z.core.$loose>>;
     haptics: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
@@ -544,16 +544,16 @@ type FooterOptions = z.infer<typeof footerSchema>;
 
 declare const fieldTypeSchema: z.ZodEnum<{
     number: "number";
-    select: "select";
-    textarea: "textarea";
-    time: "time";
     text: "text";
-    checkbox: "checkbox";
-    radio: "radio";
     url: "url";
     email: "email";
     tel: "tel";
     date: "date";
+    time: "time";
+    textarea: "textarea";
+    select: "select";
+    radio: "radio";
+    checkbox: "checkbox";
     multiselect: "multiselect";
 }>;
 type FieldType = z.infer<typeof fieldTypeSchema>;
@@ -578,16 +578,16 @@ declare const formFieldSchema: z.ZodObject<{
     label: z.ZodString;
     type: z.ZodEnum<{
         number: "number";
-        select: "select";
-        textarea: "textarea";
-        time: "time";
         text: "text";
-        checkbox: "checkbox";
-        radio: "radio";
         url: "url";
         email: "email";
         tel: "tel";
         date: "date";
+        time: "time";
+        textarea: "textarea";
+        select: "select";
+        radio: "radio";
+        checkbox: "checkbox";
         multiselect: "multiselect";
     }>;
     placeholder: z.ZodOptional<z.ZodString>;
@@ -638,16 +638,16 @@ declare const formDefSchema: z.ZodObject<{
         label: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
-            select: "select";
-            textarea: "textarea";
-            time: "time";
             text: "text";
-            checkbox: "checkbox";
-            radio: "radio";
             url: "url";
             email: "email";
             tel: "tel";
             date: "date";
+            time: "time";
+            textarea: "textarea";
+            select: "select";
+            radio: "radio";
+            checkbox: "checkbox";
             multiselect: "multiselect";
         }>;
         placeholder: z.ZodOptional<z.ZodString>;
@@ -698,16 +698,16 @@ declare const formsSchema: z.ZodArray<z.ZodObject<{
         label: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
-            select: "select";
-            textarea: "textarea";
-            time: "time";
             text: "text";
-            checkbox: "checkbox";
-            radio: "radio";
             url: "url";
             email: "email";
             tel: "tel";
             date: "date";
+            time: "time";
+            textarea: "textarea";
+            select: "select";
+            radio: "radio";
+            checkbox: "checkbox";
             multiselect: "multiselect";
         }>;
         placeholder: z.ZodOptional<z.ZodString>;
@@ -775,24 +775,24 @@ type I18nOptions = z.infer<typeof i18nSchema>;
  * One tab → no tab bar (just that content). Zero → an empty state. Only
  * meaningful in `floating` / `drawer` / `modal` modes.
  *
- * The list arrives via the start-conversation (`config.modules`); each non-chat
+ * The list arrives via the handshake (`config.modules`); each non-chat
  * tab lazy-fetches its content from `GET /content` scoped by its
  * `category`. See `docs/api/messenger-modules.md` + `docs/api/content.md`.
  */
 
 declare const moduleLayoutSchema: z.ZodEnum<{
-    home: "home";
     chat: "chat";
     help: "help";
+    home: "home";
     news: "news";
 }>;
 type ModuleLayout = z.infer<typeof moduleLayoutSchema>;
 declare const moduleSchema: z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
-        home: "home";
         chat: "chat";
         help: "help";
+        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -818,9 +818,9 @@ type ModuleOptions = z.infer<typeof moduleSchema>;
 declare const modulesSchema: z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
-        home: "home";
         chat: "chat";
         help: "help";
+        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/schema.json

@@ -32,8 +32,14 @@
           "minLength": 1,
           "maxLength": 2048
         },
+        "agentBaseUrl": {
+          "description": "Full agent-API base — set it to reach a STANDALONE `module-help-ai-agent-api` directly (local module on its own port, e.g. `http://localhost:3087`; routes attach as-is: `/ai-agent/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048
+        },
         "dataBaseUrl": {
-          "description": "Full data-API base (e.g. `https://help.ai/api/data`) — the service serving content, form definitions (`GET /forms`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataBaseUrl` > derived from the main origin (`${baseUrl}/api/data`).",
+          "description": "Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3106`) — the service serving content, form definitions (`GET /forms`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataBaseUrl` > derived from the main origin (`${baseUrl}/api/data`).",
           "type": "string",
           "minLength": 1,
           "maxLength": 2048
@@ -160,13 +166,13 @@
           "type": "object",
           "properties": {
             "upload": {
-              "default": "/ai/agent/upload-file",
+              "default": "/ai-agent/upload-file",
               "type": "string",
               "minLength": 1,
               "maxLength": 2048
             },
             "transcribe": {
-              "default": "/ai/agent/transcribe-audio",
+              "default": "/ai-agent/transcribe-audio",
               "type": "string",
               "minLength": 1,
               "maxLength": 2048
@@ -188,8 +194,8 @@
           "description": "HTTP endpoint overrides. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`), `submitForm` to the data base (`dataBaseUrl`); absolute URLs are accepted too.",
           "examples": [
             {
-              "upload": "/ai/agent/upload-file",
-              "transcribe": "/ai/agent/transcribe-audio"
+              "upload": "/ai-agent/upload-file",
+              "transcribe": "/ai-agent/transcribe-audio"
             },
             {
               "upload": "https://help.ai/uploads/presign"
@@ -475,7 +481,7 @@
               "type": "boolean"
             },
             "popOutUrl": {
-              "description": "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/start-conversation.widget.behavior.popOutUrl`.",
+              "description": "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/handshake.widget.behavior.popOutUrl`.",
               "type": "string",
               "minLength": 1,
               "maxLength": 2048
@@ -1877,7 +1883,7 @@
               "maximum": 1
             },
             "token": {
-              "description": "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/start-conversation` response — never set by hand (see `docs/api/tracking-collector.md`).",
+              "description": "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response — never set by hand (see `docs/api/tracking-collector.md`).",
               "type": "string",
               "maxLength": 512
             }
@@ -1895,10 +1901,10 @@
           ]
         },
         "site": {
-          "description": "Site config — applies in `mode: \"page\"`. Comes from the start-conversation response, not user-edited."
+          "description": "Site config — applies in `mode: \"page\"`. Comes from the handshake response, not user-edited."
         },
         "blocks": {
-          "description": "Blocks (nav + link cards) — applies in `mode: \"page\"`. Comes from the start-conversation response."
+          "description": "Blocks (nav + link cards) — applies in `mode: \"page\"`. Comes from the handshake response."
         }
       },
       "required": [
@@ -1929,7 +1935,7 @@
         }
       ]
     },
-    "StartConversationResponse": {
+    "HandshakeResponse": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "type": "object",
       "properties": {
@@ -2242,7 +2248,7 @@
                   "type": "boolean"
                 },
                 "popOutUrl": {
-                  "description": "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/start-conversation.widget.behavior.popOutUrl`.",
+                  "description": "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/handshake.widget.behavior.popOutUrl`.",
                   "type": "string",
                   "minLength": 1,
                   "maxLength": 2048
@@ -3282,7 +3288,7 @@
                   "maximum": 1
                 },
                 "token": {
-                  "description": "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/start-conversation` response — never set by hand (see `docs/api/tracking-collector.md`).",
+                  "description": "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response — never set by hand (see `docs/api/tracking-collector.md`).",
                   "type": "string",
                   "maxLength": 512
                 }
@@ -3520,13 +3526,6 @@
         "conversationId": {
           "type": "string"
         },
-        "canContinue": {
-          "type": "boolean"
-        },
-        "messages": {
-          "type": "array",
-          "items": {}
-        },
         "userPrefs": {
           "type": "object",
           "propertyNames": {
@@ -3561,9 +3560,7 @@
         "deployment",
         "agent",
         "visitorId",
-        "conversationId",
-        "canContinue",
-        "messages"
+        "conversationId"
       ],
       "additionalProperties": {}
     }

package/schema.mjs

@@ -129,7 +129,7 @@ var behaviorSchema = z4.object({
     "Show tool/function calls the model makes (e.g. search) as inline chips in the transcript. `false` (default) hides them."
   ),
   popOutUrl: z4.string().min(1).max(2048).optional().describe(
-    "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/start-conversation.widget.behavior.popOutUrl`."
+    "URL the `popOut` action opens in a new tab (carries `?conversation=<id>&widgetId=<id>` query params). Falls back to the brand's build-time default. Set this to point at your own dedicated chat page (e.g. `https://app.acme.com/chat`). Server-pushable on `/handshake.widget.behavior.popOutUrl`."
   )
 }).loose().describe("Lifecycle + streaming behaviour. Doesn't affect visual presentation.").meta({
   examples: [
@@ -575,7 +575,7 @@ var trackingSchema = z15.object({
   ),
   sampleRate: z15.number().min(0).max(1).optional().describe("Per-visitor sampling 0..1 (decided once per page load, keeping funnels intact). Default `1`."),
   token: z15.string().max(512).optional().describe(
-    "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/start-conversation` response \u2014 never set by hand (see `docs/api/tracking-collector.md`)."
+    "Anti-forgery token, echoed as `tk=` on every hit. Server-issued in the `/handshake` response \u2014 never set by hand (see `docs/api/tracking-collector.md`)."
   )
 }).loose().describe(
   "Anonymous usage tracking for the widget owner \u2014 GA-style pixel events (open, send, form submit, \u2026) with page / device / locale dimensions. Never includes message content; visitors are identified only by the widget's anonymous visitorId."
@@ -585,8 +585,8 @@ var trackingSchema = z15.object({
 
 // src/schema/widget.ts
 var endpointsSchema = z16.object({
-  upload: z16.string().min(1).max(2048).default("/ai/agent/upload-file"),
-  transcribe: z16.string().min(1).max(2048).default("/ai/agent/transcribe-audio"),
+  upload: z16.string().min(1).max(2048).default("/ai-agent/upload-file"),
+  transcribe: z16.string().min(1).max(2048).default("/ai-agent/transcribe-audio"),
   submitForm: z16.string().min(1).max(2048).default("/submit-form").describe(
     "Form submission endpoint. The widget POSTs each completed form's values here (fire-and-forget), keyed by the same visitorId + conversationId as the conversation; the payload carries `formId` + `trigger` so the backend can route. Optional \u2014 a 404 is ignored."
   )
@@ -594,7 +594,7 @@ var endpointsSchema = z16.object({
   "HTTP endpoint overrides. `upload` / `transcribe` paths are appended to the agent base (`${baseUrl}/api/agent`), `submitForm` to the data base (`dataBaseUrl`); absolute URLs are accepted too."
 ).meta({
   examples: [
-    { upload: "/ai/agent/upload-file", transcribe: "/ai/agent/transcribe-audio" },
+    { upload: "/ai-agent/upload-file", transcribe: "/ai-agent/transcribe-audio" },
     { upload: "https://help.ai/uploads/presign" },
     { submitForm: "https://crm.acme.com/leads" }
   ]
@@ -643,8 +643,11 @@ var connectionConfigSchema = z16.object({
   baseUrl: z16.string().min(1).max(2048).optional().describe(
     "MAIN site origin (e.g. `https://help.ai`) \u2014 the API modules derive from it: agent API at `${baseUrl}/api/agent`, data API at `${baseUrl}/api/data`. Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."
   ),
+  agentBaseUrl: z16.string().min(1).max(2048).optional().describe(
+    "Full agent-API base \u2014 set it to reach a STANDALONE `module-help-ai-agent-api` directly (local module on its own port, e.g. `http://localhost:3087`; routes attach as-is: `/ai-agent/handshake`). Precedence: this option > derived from the main origin (`${baseUrl}/api/agent`). Not server-pushable."
+  ),
   dataBaseUrl: z16.string().min(1).max(2048).optional().describe(
-    "Full data-API base (e.g. `https://help.ai/api/data`) \u2014 the service serving content, form definitions (`GET /forms`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."
+    "Full data-API base (e.g. `https://help.ai/api/data`, or a standalone local module like `http://localhost:3106`) \u2014 the service serving content, form definitions (`GET /forms`), and form submissions at root-level paths. Precedence: this option > server-pushed `config.dataBaseUrl` > derived from the main origin (`${baseUrl}/api/data`)."
   ),
   userContext: userContextSchema.optional(),
   pageContext: pageContextSchema.optional(),
@@ -684,7 +687,7 @@ var widgetSettingsSchema = z16.object({
   modules: modulesSchema.optional(),
   tracking: trackingSchema.optional()
 }).loose().describe(
-  "Portal-configurable widget settings \u2014 fourteen sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-conversation` under `config`."
+  "Portal-configurable widget settings \u2014 fourteen sections, one per dashboard tab. The backend pushes this same shape on `/ai-agent/handshake` under `config`."
 ).meta({
   examples: [
     { presentation: { mode: "floating", position: "bottom-right" }, theme: "auto" },
@@ -702,10 +705,8 @@ var widgetSettingsSchema = z16.object({
 });
 var widgetConfigSchema = connectionConfigSchema.extend({
   ...widgetSettingsSchema.shape,
-  site: z16.unknown().optional().describe(
-    'Site config \u2014 applies in `mode: "page"`. Comes from the start-conversation response, not user-edited.'
-  ),
-  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-conversation response.')
+  site: z16.unknown().optional().describe('Site config \u2014 applies in `mode: "page"`. Comes from the handshake response, not user-edited.'),
+  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the handshake response.')
 }).describe(
   "Full client widget config \u2014 connection (where + auth) + widget settings (look + behaviour) + page-mode extras. This is what the runtime parses on `mount()` / `init()`. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here \u2014 the runtime silently ignores irrelevant fields rather than rejecting them so the same object can flow across mode changes."
 ).meta({
@@ -754,7 +755,7 @@ var handshakeWelcomeSuggestionSchema = z17.object({
   text: z17.string().optional()
 }).loose();
 var rebindReasonSchema = z17.enum(["conflict", "expired", "invalid"]);
-var startConversationResponseSchema = z17.object({
+var handshakeResponseSchema = z17.object({
   deployment: z17.object({
     id: z17.string(),
     name: z17.string(),
@@ -788,8 +789,6 @@ var startConversationResponseSchema = z17.object({
   }).loose().optional(),
   visitorId: z17.string(),
   conversationId: z17.string(),
-  canContinue: z17.boolean(),
-  messages: z17.array(z17.unknown()),
   /**
    * Per-visitor preferences (locale picker, theme picker, sound
    * mute, dragged panel size). Distinct from `config` — this is
@@ -845,7 +844,7 @@ function emitJsonSchema() {
     description: "Canonical config schemas for the embeddable AI agent elements widget.",
     definitions: {
       WidgetConfig: z19.toJSONSchema(widgetConfigSchema),
-      StartConversationResponse: z19.toJSONSchema(startConversationResponseSchema)
+      HandshakeResponse: z19.toJSONSchema(handshakeResponseSchema)
     }
   };
 }
@@ -878,6 +877,7 @@ export {
   formFieldSchema,
   formTriggerSchema,
   formsSchema,
+  handshakeResponseSchema,
   hapticsOptionsSchema,
   headerActionsSchema,
   headerSchema,
@@ -907,7 +907,6 @@ export {
   siteConfigSchema,
   sizeOptionsSchema,
   soundOptionsSchema,
-  startConversationResponseSchema,
   stringsOverrideSchema,
   themeFieldSchema,
   themeOverridesSchema,

package/web-component.d.ts

@@ -8,7 +8,7 @@
  *
  * Mode resolution: the tag itself doesn't pin a default mode. When no
  * `mode=…` attribute is set, the resolver default (`"floating"`) seeds
- * the very first frame — which the App's start-conversation gate keeps blank
+ * the very first frame — which the App's handshake gate keeps blank
  * — then the server's pushed `widget.presentation.mode` wins via
  * `mergeServerConfig` (subscribed in `boot()` below). Drop a bare
  * `<web-ai-chat public-key="…" ai-agent-deployment-id="…">` on the