@smooai/chat-widget 0.10.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smooai/chat-widget",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Embeddable AI chat as a framework-light web component — the Aurora Glass design, streaming replies, grounded sources, and per-brand theming. Speaks the smooth-operator WebSocket protocol.",
   "license": "MIT",
   "author": "SmooAI",
@@ -58,7 +58,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@smooai/smooth-operator": "^1.8.0",
+    "@smooai/smooth-operator": "^1.21.1",
     "libphonenumber-js": "^1.13.7",
     "zustand": "^5.0.14"
   },

package/src/config.ts

@@ -106,6 +106,12 @@ export interface ChatWidgetConfig {
      * Clicking one sends it. Capped at 5 for layout.
      */
     examplePrompts?: string[];
+    /**
+     * Show mid-conversation suggested-reply chips ("quick replies") under the
+     * latest assistant message when the agent returns follow-up suggestions.
+     * Clicking one sends it. Defaults to `true` (shown unless explicitly `false`).
+     */
+    showSuggestedReplies?: boolean;
     /** Require the visitor's name before chatting. */
     requireName?: boolean;
     /** Require the visitor's email before chatting. */
@@ -180,6 +186,7 @@ export function resolveConfig(config: ChatWidgetConfig): ResolvedConfig {
         startOpen: config.startOpen ?? false,
         hideBranding: config.hideBranding ?? false,
         examplePrompts: (config.examplePrompts ?? []).filter((p) => p.trim().length > 0).slice(0, 5),
+        showSuggestedReplies: config.showSuggestedReplies ?? true,
         requireName: config.requireName ?? false,
         requireEmail: config.requireEmail ?? false,
         requirePhone: config.requirePhone ?? false,

package/src/conversation.ts

@@ -75,6 +75,13 @@ export interface ChatMessage {
      * defensively off the terminal event — see {@link extractCitations}.
      */
     citations?: Citation[];
+    /**
+     * Suggested follow-up replies ("quick replies") the agent offered on the
+     * terminal `eventual_response`. Set ONLY on the finalized assistant message —
+     * never mid-stream. Read defensively (see {@link extractSuggestions}); capped
+     * at 4 for layout. Absent when the turn offered none.
+     */
+    suggestions?: string[];
 }
 
 export type ConnectionStatus = 'idle' | 'connecting' | 'ready' | 'error' | 'closed';
@@ -86,6 +93,9 @@ export type ConnectionStatus = 'idle' | 'connecting' | 'ready' | 'error' | 'clos
  *   Resume with {@link ConversationController.verifyOtp}.
  * - `confirm` — the agent wants to run a state-mutating tool and needs approval.
  *   Resume with {@link ConversationController.confirmTool}.
+ * - `interaction` — the agent raised a Rich Interaction (structured card, e.g.
+ *   identity intake). Resume with {@link ConversationController.submitInteraction}
+ *   or {@link ConversationController.declineInteraction}.
  */
 export type Interrupt =
     | {
@@ -99,7 +109,28 @@ export type Interrupt =
           error?: string;
           attemptsRemaining?: number;
       }
-    | { kind: 'confirm'; toolId?: string; actionDescription?: string };
+    | { kind: 'confirm'; toolId?: string; actionDescription?: string }
+    | {
+          kind: 'interaction';
+          /** Server-generated interaction instance id (echoed on submit). */
+          interactionId: string;
+          /** The Rich Interaction kind (e.g. `identity_intake`) — selects the card. */
+          interactionKind: string;
+          /** Kind-specific render spec (identity_intake: `{ fields: [...] }`). */
+          spec: Record<string, unknown>;
+          /** Why the agent raised it (card header copy). */
+          reason?: string;
+          /** Per-field server-side validation errors (from `interaction_invalid`). */
+          errors?: { field: string; message: string }[];
+      };
+
+/**
+ * The Rich-Interaction render capabilities this widget declares at session
+ * create (`supports`). Must stay aligned with the card registry in
+ * `element.ts` (`INTERACTION_CARDS`) — registering a card IS declaring its
+ * capability; a test asserts the two match.
+ */
+export const SUPPORTED_INTERACTION_CAPABILITIES: readonly string[] = ['identity_form'];
 
 export interface UserInfo {
     name?: string;
@@ -183,6 +214,20 @@ function extractCitations(inner: unknown): Citation[] {
     return out;
 }
 
+/**
+ * Pull the suggested follow-up replies out of a terminal `eventual_response`'s
+ * `response` object (`response.suggestedNextActions`). Optional + back-compatible
+ * like citations — read defensively (tolerating absence, non-array shapes, and
+ * non-string / blank entries) and capped at 4 so a chatty agent can't overflow
+ * the composer chip row.
+ */
+function extractSuggestions(response: unknown): string[] {
+    if (!response || typeof response !== 'object') return [];
+    const raw = (response as { suggestedNextActions?: unknown }).suggestedNextActions;
+    if (!Array.isArray(raw)) return [];
+    return raw.filter((s): s is string => typeof s === 'string' && s.trim().length > 0).slice(0, 4);
+}
+
 /** A `get_conversation_messages` row, narrowed defensively off the wire. */
 interface WireMessage {
     id?: string;
@@ -211,6 +256,9 @@ export class ConversationController {
     /** requestId of the in-flight turn — used to resume OTP / tool confirmations. */
     private activeRequestId: string | null = null;
     private interrupt: Interrupt | null = null;
+    /** Values from the last interaction submit, merged into the persisted
+     *  identity (identity_intake only) once the server acks them. */
+    private pendingInteractionValues: { kind: string; values: Record<string, unknown> } | null = null;
     private identityRestore: IdentityRestore = { phase: 'idle' };
     /**
      * True once the resume probe (persisted-pointer get_session OR the
@@ -316,6 +364,41 @@ export class ConversationController {
         this.setInterrupt(null);
     }
 
+    /**
+     * Submit a Rich Interaction card to resume the parked turn. The server
+     * routes to the kind's validator: invalid values come back as an
+     * `interaction_invalid` event (the card re-renders with per-field errors —
+     * the turn stays parked); a valid submit is acked and the turn resumes.
+     * No-op if not awaiting an interaction.
+     */
+    submitInteraction(values: Record<string, unknown>): void {
+        if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'interaction') return;
+        // Stash the values so the ack (immediate_response) can merge accepted
+        // identity values into the persisted store.
+        this.pendingInteractionValues = { kind: this.interrupt.interactionKind, values };
+        this.client.submitInteraction({
+            sessionId: this.sessionId,
+            requestId: this.activeRequestId,
+            interactionId: this.interrupt.interactionId,
+            kind: this.interrupt.interactionKind,
+            values,
+        });
+    }
+
+    /** Decline the pending Rich Interaction; the agent continues without it. */
+    declineInteraction(): void {
+        if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'interaction') return;
+        this.client.submitInteraction({
+            sessionId: this.sessionId,
+            requestId: this.activeRequestId,
+            interactionId: this.interrupt.interactionId,
+            kind: this.interrupt.interactionKind,
+            declined: true,
+        });
+        this.pendingInteractionValues = null;
+        this.setInterrupt(null);
+    }
+
     private nextId(prefix: string): string {
         this.seq += 1;
         return `${prefix}-${this.seq}-${Date.now().toString(36)}`;
@@ -522,6 +605,10 @@ export class ConversationController {
             userName: state.identity.name,
             userEmail: state.identity.email,
             browserFingerprint: this.fingerprint(),
+            // Declare the Rich-Interaction cards this widget can render (derived
+            // from the card registry), so the server emits `interaction_required`
+            // for those kinds instead of the conversational fallback.
+            supports: [...SUPPORTED_INTERACTION_CAPABILITIES],
             ...(metadata ? { metadata } : {}),
         });
         this.sessionId = session.sessionId;
@@ -623,6 +710,11 @@ export class ConversationController {
             if (citations.length > 0) {
                 assistant.citations = citations;
             }
+            // Suggested follow-up replies from the terminal event, when present.
+            const suggestions = extractSuggestions(inner?.response);
+            if (suggestions.length > 0) {
+                assistant.suggestions = suggestions;
+            }
             assistant.streaming = false;
             this.emitMessages();
         } catch (err) {
@@ -674,7 +766,51 @@ export class ConversationController {
             case 'write_confirmation_required':
                 this.setInterrupt({ kind: 'confirm', toolId: str(inner.toolId), actionDescription: str(inner.actionDescription) });
                 break;
-            default:
+            case 'interaction_required': {
+                const interactionId = str(inner.interactionId);
+                const kind = str(inner.kind);
+                const spec = inner.spec && typeof inner.spec === 'object' ? (inner.spec as Record<string, unknown>) : {};
+                if (!interactionId || !kind) break; // not renderable — ignore
+                this.pendingInteractionValues = null;
+                this.setInterrupt({
+                    kind: 'interaction',
+                    interactionId,
+                    interactionKind: kind,
+                    spec,
+                    reason: str(inner.reason),
+                });
+                break;
+            }
+            case 'interaction_invalid':
+                if (this.interrupt?.kind === 'interaction' && this.interrupt.interactionId === str(inner.interactionId)) {
+                    const errors: { field: string; message: string }[] = [];
+                    if (Array.isArray(inner.errors)) {
+                        for (const e of inner.errors) {
+                            if (!e || typeof e !== 'object') continue;
+                            const o = e as Record<string, unknown>;
+                            const field = str(o.field);
+                            if (field) errors.push({ field, message: str(o.message) ?? 'Invalid value' });
+                        }
+                    }
+                    this.pendingInteractionValues = null;
+                    this.setInterrupt({ ...this.interrupt, errors });
+                }
+                break;
+            case 'immediate_response':
+                // Mid-turn immediate_response while an interaction card is showing
+                // is the submit/decline ack: the park resolved — clear the card
+                // and, for accepted identity values, persist them.
+                if (this.interrupt?.kind === 'interaction') {
+                    const pending = this.pendingInteractionValues;
+                    if (pending && pending.kind === 'identity_intake') {
+                        const v = pending.values as { name?: string; email?: string; phone?: string };
+                        this.store.getState().mergeIdentity({ name: v.name, email: v.email, phone: v.phone });
+                    }
+                    this.pendingInteractionValues = null;
+                    this.setInterrupt(null);
+                }
+                break;
+                        default:
                 break;
         }
     }

package/src/element.ts

@@ -17,7 +17,7 @@
 import { AsYouType, isValidPhoneNumber, parsePhoneNumber } from 'libphonenumber-js/min';
 import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
 import { needsUserInfo, resolveConfig } from './config.js';
-import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt } from './conversation.js';
+import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt, SUPPORTED_INTERACTION_CAPABILITIES } from './conversation.js';
 import { SMOOTH_ICON_SVG } from './logo.js';
 import { cleanCitationSnippet, escapeHtml, renderMarkdown, safeHttpUrl } from './markdown.js';
 import { buildStyles } from './styles.js';
@@ -71,10 +71,166 @@ const ICON = {
     chev: `<svg width="11" height="11" viewBox="0 0 24 24" fill="none"><path d="m9 6 6 6-6 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
     /** OTP interrupt — a padlock. */
     lock: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="5" y="10.5" width="14" height="9.5" rx="2.2" stroke="currentColor" stroke-width="1.7"/><path d="M8 10.5V8a4 4 0 0 1 8 0v2.5" stroke="currentColor" stroke-width="1.7"/></svg>`,
+    /** Identity-intake interrupt — a person. */
+    user: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="12" cy="8.2" r="3.4" stroke="currentColor" stroke-width="1.7"/><path d="M5.5 19.5c.8-3.1 3.4-4.8 6.5-4.8s5.7 1.7 6.5 4.8" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/></svg>`,
     /** Tool-confirmation interrupt — a shield. */
     shield: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 3 5 6v5c0 4.4 3 7.2 7 8.5 4-1.3 7-4.1 7-8.5V6l-7-3Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="m9 11.5 2 2 4-4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
 } as const;
 
+/**
+ * The Rich Interactions **card registry**: interaction kind → overlay card.
+ * `interaction_required { kind }` looks its card up here; registering a card IS
+ * declaring the widget's render capability for that kind (see
+ * `SUPPORTED_INTERACTION_CAPABILITIES` in conversation.ts — a test keeps the
+ * two aligned). Adding a kind = one card builder + one entry.
+ *
+ * The existing OTP and tool-approval overlays are prior instances of this same
+ * shape and should retrofit onto this registry later (their wire events predate
+ * the pattern).
+ */
+export interface InteractionCardContext {
+    /** Submit kind-shaped values (resumes the parked turn; server validates). */
+    submit: (values: Record<string, unknown>) => void;
+    /** Decline the interaction (the agent continues without it). */
+    decline: () => void;
+    /** Persisted visitor identity, for pre-filling known fields. */
+    prefill: { name?: string; email?: string; phone?: string };
+    /** Wire live phone formatting + validity hint onto a form's phone input. */
+    wirePhoneField: (form: HTMLFormElement) => void;
+}
+
+export interface InteractionCard {
+    /** The render capability this card provides (goes into `supports`). */
+    capability: string;
+    /** Card header title. */
+    title: string;
+    /** Static, trusted header icon SVG. */
+    icon: string;
+    /** Build the card body for an `interaction` interrupt. */
+    build: (it: Extract<Interrupt, { kind: 'interaction' }>, ctx: InteractionCardContext) => HTMLElement;
+}
+
+/**
+ * The identity_intake card: the fields the agent requested (pre-chat form field
+ * pattern — same classes, same phone formatting), per-field server errors, a
+ * submit and a decline affordance. Server-supplied text (reason, labels, error
+ * messages) is set via `textContent` — never innerHTML.
+ */
+function buildIdentityIntakeCard(it: Extract<Interrupt, { kind: 'interaction' }>, ctx: InteractionCardContext): HTMLElement {
+    const form = document.createElement('form');
+    form.className = 'int-form';
+    form.noValidate = true;
+
+    if (it.reason) {
+        const desc = document.createElement('div');
+        desc.className = 'int-desc';
+        desc.textContent = it.reason;
+        form.appendChild(desc);
+    }
+
+    const DEFAULTS: Record<string, { label: string; type: string; autocomplete: string }> = {
+        name: { label: 'Name', type: 'text', autocomplete: 'name' },
+        email: { label: 'Email', type: 'email', autocomplete: 'email' },
+        phone: { label: 'Phone', type: 'tel', autocomplete: 'tel' },
+    };
+
+    // Parse the kind's spec defensively: `{ fields: [{ key, required, label? }] }`.
+    const rawFields = Array.isArray(it.spec.fields) ? it.spec.fields : [];
+    const fields: { key: 'name' | 'email' | 'phone'; required: boolean; label?: string }[] = [];
+    for (const f of rawFields) {
+        if (!f || typeof f !== 'object') continue;
+        const o = f as Record<string, unknown>;
+        const key = typeof o.key === 'string' ? o.key : '';
+        if (key !== 'name' && key !== 'email' && key !== 'phone') continue;
+        fields.push({ key, required: o.required === true, label: typeof o.label === 'string' ? o.label : undefined });
+    }
+    if (fields.length === 0) fields.push({ key: 'email', required: true });
+
+    for (const f of fields) {
+        const d = DEFAULTS[f.key]!;
+        const label = document.createElement('label');
+        label.className = 'pc-field';
+        const caption = document.createElement('span');
+        caption.textContent = f.label ?? d.label;
+        const input = document.createElement('input');
+        input.name = f.key;
+        input.type = d.type;
+        input.setAttribute('autocomplete', d.autocomplete);
+        input.required = f.required;
+        const prefill = ctx.prefill[f.key];
+        if (prefill) input.value = prefill;
+        label.append(caption, input);
+        if (f.key === 'phone') {
+            const hint = document.createElement('span');
+            hint.className = 'pc-hint';
+            hint.setAttribute('aria-live', 'polite');
+            label.appendChild(hint);
+        }
+        // Per-field server-side validation error (interaction_invalid).
+        const serverError = it.errors?.find((e) => e.field === f.key);
+        if (serverError) {
+            label.classList.add('invalid');
+            const err = document.createElement('span');
+            err.className = 'int-error';
+            err.textContent = serverError.message;
+            label.appendChild(err);
+        }
+        form.appendChild(label);
+    }
+
+    const row = document.createElement('div');
+    row.className = 'int-row';
+    const decline = document.createElement('button');
+    decline.className = 'int-btn';
+    decline.type = 'button';
+    decline.textContent = 'No thanks';
+    decline.addEventListener('click', () => ctx.decline());
+    const share = document.createElement('button');
+    share.className = 'int-btn primary';
+    share.type = 'submit';
+    share.textContent = 'Share details';
+    row.append(decline, share);
+    form.appendChild(row);
+
+    form.addEventListener('submit', (ev) => {
+        ev.preventDefault();
+        if (!form.reportValidity()) return;
+        const data = new FormData(form);
+        const val = (k: string) => ((data.get(k) as string | null)?.trim() || undefined);
+
+        // Phone: mirror the pre-chat rules — block a required-but-invalid number,
+        // prefer canonical E.164 when it parses (the server re-validates anyway).
+        const rawPhone = val('phone');
+        const phoneInput = form.querySelector('input[name="phone"]') as HTMLInputElement | null;
+        if (rawPhone && phoneInput && !isValidPhoneNumber(rawPhone, PHONE_DEFAULT_REGION)) {
+            const field = phoneInput.closest('.pc-field');
+            field?.classList.add('invalid');
+            const hint = field?.querySelector('.pc-hint');
+            if (hint) hint.textContent = 'Enter a valid phone number';
+            if (phoneInput.hasAttribute('required')) {
+                phoneInput.focus();
+                return;
+            }
+        }
+        const phone = rawPhone ? (phoneToE164(rawPhone) ?? rawPhone) : undefined;
+        ctx.submit({ name: val('name'), email: val('email'), phone });
+    });
+    // Same live phone formatting + validity hint as the pre-chat form.
+    ctx.wirePhoneField(form);
+    queueMicrotask(() => (form.querySelector('input') as HTMLInputElement | null)?.focus());
+    return form;
+}
+
+/** Kind → card. See the registry doc above. */
+export const INTERACTION_CARDS: Record<string, InteractionCard> = {
+    identity_intake: {
+        capability: 'identity_form',
+        title: 'Share your details',
+        icon: ICON.user,
+        build: buildIdentityIntakeCard,
+    },
+};
+
 // `safeHttpUrl` / `escapeHtml` live in `./markdown.js` (the markdown renderer
 // needs them too); re-exported here for back-compat with existing importers.
 export { escapeHtml, safeHttpUrl } from './markdown.js';
@@ -97,6 +253,8 @@ export class SmoothAgentChatElement extends HTMLElement {
     private hasSent = false;
     /** Starter prompts shown as chips in the empty state. */
     private examplePrompts: string[] = [];
+    /** Whether mid-conversation suggested-reply chips are shown (config). */
+    private showSuggestedReplies = true;
     /** Resolved greeting text, cached so async (rAF) renders can reuse it. */
     private greeting = '';
     /** Current mid-turn interrupt (OTP / tool-confirmation), or null. */
@@ -117,6 +275,7 @@ export class SmoothAgentChatElement extends HTMLElement {
     private dotEl: HTMLElement | null = null;
     private inputEl: HTMLTextAreaElement | null = null;
     private sendBtn: HTMLButtonElement | null = null;
+    private suggestionsEl: HTMLElement | null = null;
 
     // ── Smooth streaming reveal ──
     // Tokens arrive in variable-size bursts at uneven rates, so revealing text in
@@ -209,6 +368,7 @@ export class SmoothAgentChatElement extends HTMLElement {
             startOpen: this.overrides.startOpen ?? this.hasAttribute('start-open'),
             hideBranding: this.overrides.hideBranding ?? this.hasAttribute('hide-branding'),
             examplePrompts: this.overrides.examplePrompts,
+            showSuggestedReplies: this.overrides.showSuggestedReplies,
             requireName: this.overrides.requireName,
             requireEmail: this.overrides.requireEmail,
             requirePhone: this.overrides.requirePhone,
@@ -247,10 +407,14 @@ export class SmoothAgentChatElement extends HTMLElement {
                 onInterrupt: (interrupt) => {
                     this.interrupt = interrupt;
                     this.renderInterrupt();
+                    // Suggestion chips are hidden while an interrupt overlay is up.
+                    this.renderSuggestions();
                 },
                 onIdentityRestore: (state) => {
                     this.identityRestore = state;
                     this.renderInterrupt();
+                    // The restore overlay reuses the interrupt slot — hide chips too.
+                    this.renderSuggestions();
                 },
             });
             if (resolved.startOpen) this.open = true;
@@ -303,6 +467,7 @@ export class SmoothAgentChatElement extends HTMLElement {
 
         // Remember starter prompts + greeting for the empty-state chips / async renders.
         this.examplePrompts = resolved.examplePrompts;
+        this.showSuggestedReplies = resolved.showSuggestedReplies;
         this.greeting = resolved.greeting;
 
         // Gate the conversation behind a pre-chat identity form when required.
@@ -348,6 +513,7 @@ export class SmoothAgentChatElement extends HTMLElement {
         const footerHtml = footerInner ? `<div class="footer">${footerInner}</div>` : '';
         const chatHtml = `
                 <div class="messages"></div>
+                <div class="reply-suggestions"></div>
                 <div class="interrupt hidden"></div>
                 <div class="composer-wrap">
                     <div class="composer">
@@ -385,6 +551,7 @@ export class SmoothAgentChatElement extends HTMLElement {
         this.inputEl = container.querySelector('textarea');
         this.sendBtn = container.querySelector('.send');
         this.interruptEl = container.querySelector('.interrupt');
+        this.suggestionsEl = container.querySelector('.reply-suggestions');
 
         this.launcherEl?.addEventListener('click', () => this.openChat());
         container.querySelector('.close')?.addEventListener('click', () => this.closeChat());
@@ -469,21 +636,38 @@ export class SmoothAgentChatElement extends HTMLElement {
         head.className = 'int-head';
         const ico = document.createElement('span');
         ico.className = 'int-ico';
-        ico.innerHTML = it.kind === 'otp' ? ICON.lock : ICON.shield; // static, trusted
+        const card_meta = it.kind === 'interaction' ? INTERACTION_CARDS[it.interactionKind] : undefined;
+        if (it.kind === 'interaction' && !card_meta) {
+            // A kind we have no card for (shouldn't happen — we only declare
+            // capabilities for registered cards). Decline so the turn never hangs.
+            this.controller?.declineInteraction();
+            el.classList.add('hidden');
+            return;
+        }
+        ico.innerHTML = it.kind === 'otp' ? ICON.lock : it.kind === 'interaction' ? (card_meta?.icon ?? ICON.user) : ICON.shield; // static, trusted
         const title = document.createElement('span');
         title.className = 'int-title';
-        title.textContent = it.kind === 'otp' ? 'Verification required' : 'Confirm this action';
+        title.textContent = it.kind === 'otp' ? 'Verification required' : it.kind === 'interaction' ? (card_meta?.title ?? 'One more thing') : 'Confirm this action';
         head.append(ico, title);
         card.appendChild(head);
 
-        if (it.actionDescription) {
+        if (it.kind !== 'interaction' && it.actionDescription) {
             const desc = document.createElement('div');
             desc.className = 'int-desc';
             desc.textContent = it.actionDescription;
             card.appendChild(desc);
         }
 
-        if (it.kind === 'otp') {
+        if (it.kind === 'interaction') {
+            card.appendChild(
+                card_meta!.build(it, {
+                    submit: (values) => this.controller?.submitInteraction(values),
+                    decline: () => this.controller?.declineInteraction(),
+                    prefill: this.controller?.getStore().getState().identity ?? {},
+                    wirePhoneField: (form) => this.wirePhoneField(form),
+                }),
+            );
+        } else if (it.kind === 'otp') {
             if (it.sent?.maskedDestination) {
                 const sent = document.createElement('div');
                 sent.className = 'int-sent';
@@ -936,6 +1120,39 @@ export class SmoothAgentChatElement extends HTMLElement {
             }
         }
         this.scrollToBottom(true);
+        this.renderSuggestions();
+    }
+
+    /**
+     * Render (or clear) the mid-conversation suggested-reply chips under the
+     * composer. Shown ONLY when: the feature is enabled, no interrupt / restore
+     * overlay is active (those reuse the slot above the composer), and the LATEST
+     * message is a finalized assistant turn that carried suggestions. A new turn
+     * (agent or the visitor typing) appends messages, so the latest is no longer
+     * that assistant message and the chips clear on the next render. Chips reuse
+     * the empty-state `.prompts`/`.chip` styling and send via the same path.
+     */
+    private renderSuggestions(): void {
+        const el = this.suggestionsEl;
+        if (!el) return;
+        el.replaceChildren();
+        if (!this.showSuggestedReplies) return;
+        // Hidden while an OTP / tool-confirmation / restore overlay is active.
+        if (this.interrupt || this.identityRestore.phase !== 'idle') return;
+        const last = this.messages[this.messages.length - 1];
+        if (!last || last.role !== 'assistant' || last.streaming || !last.suggestions || last.suggestions.length === 0) return;
+
+        const chips = document.createElement('div');
+        chips.className = 'prompts';
+        for (const suggestion of last.suggestions) {
+            const chip = document.createElement('button');
+            chip.type = 'button';
+            chip.className = 'chip';
+            chip.textContent = suggestion;
+            chip.addEventListener('click', () => this.submitPrompt(suggestion));
+            chips.appendChild(chip);
+        }
+        el.appendChild(chips);
     }
 
     // ─────────────────────── Smooth streaming reveal ───────────────────────────

package/src/styles.ts

@@ -605,6 +605,10 @@ ${
     transform: translateY(-1px);
 }
 
+/* ───────────── Mid-conversation suggested-reply chips ─────────────── */
+.reply-suggestions { padding: 0 14px 4px; }
+.reply-suggestions:empty { display: none; }
+
 /* ─────────────── OTP / tool-confirmation interrupt ────────────────── */
 .interrupt { padding: 0 14px; }
 .int-card {
@@ -639,6 +643,9 @@ ${
     border-color: color-mix(in srgb, var(--sac-primary) 60%, transparent);
     box-shadow: 0 0 0 4px color-mix(in srgb, var(--sac-primary) 14%, transparent);
 }
+.int-form { display: flex; flex-direction: column; gap: 10px; margin-top: 10px; }
+.int-form .pc-field input { width: 100%; box-sizing: border-box; }
+.int-form .int-error { margin-top: 2px; }
 .int-btn {
     border: 1px solid color-mix(in srgb, var(--sac-border) 80%, transparent);
     background: var(--sac-surface-2);
@@ -658,8 +665,14 @@ ${
     color: var(--sac-primary-text);
     box-shadow: 0 6px 14px -6px color-mix(in srgb, var(--sac-primary) 65%, transparent);
 }
-.int-row .int-btn { flex: 1; }
-.int-row .int-input + .int-btn { flex: 0 0 auto; }
+.int-row .int-form { display: flex; flex-direction: column; gap: 10px; margin-top: 10px; }
+.int-form .pc-field input { width: 100%; box-sizing: border-box; }
+.int-form .int-error { margin-top: 2px; }
+.int-btn { flex: 1; }
+.int-row .int-input + .int-form { display: flex; flex-direction: column; gap: 10px; margin-top: 10px; }
+.int-form .pc-field input { width: 100%; box-sizing: border-box; }
+.int-form .int-error { margin-top: 2px; }
+.int-btn { flex: 0 0 auto; }
 .int-error { margin-top: 8px; font-size: 12px; color: #f87171; }
 .int-card { position: relative; }
 .int-close {