@smooai/chat-widget 0.3.0 → 0.5.0

package/README.md

@@ -1,20 +1,26 @@
-<div align="center">
+<p align="center">
+  <a href="https://smoo.ai"><img src=".github/banner.png" alt="@smooai/chat-widget — Embeddable AI chat as a web component" width="100%" /></a>
+</p>
 
-# @smooai/chat-widget
+<p align="center">
+  <a href="https://www.npmjs.com/package/@smooai/chat-widget"><img src="https://img.shields.io/npm/v/@smooai/chat-widget?style=for-the-badge&color=00A6A6&label=npm&logo=npm&logoColor=white&labelColor=020618" alt="npm"></a>
+  <a href="https://smoo.ai/platform/support"><img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618" alt="Smoo AI"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-F49F0A?style=for-the-badge&labelColor=020618" alt="license"></a>
+</p>
 
-### Embeddable AI chat as a framework-light web component.
+<p align="center">
+  <img src="https://img.shields.io/badge/gzip-~19%20kB-FF6B6C?style=flat-square" alt="bundle size">
+  <a href="https://github.com/SmooAI/chat-widget/actions/workflows/ci.yml"><img src="https://github.com/SmooAI/chat-widget/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
 
-**Streaming replies · grounded sources · popover or full-page · inherits _your_ brand color.**
-
-[![npm](https://img.shields.io/npm/v/@smooai/chat-widget?color=00a6a6&label=npm)](https://www.npmjs.com/package/@smooai/chat-widget)
-[![CI](https://github.com/SmooAI/chat-widget/actions/workflows/ci.yml/badge.svg)](https://github.com/SmooAI/chat-widget/actions/workflows/ci.yml)
-[![bundle](https://img.shields.io/badge/gzip-~19%20kB-4f8bff)](https://github.com/SmooAI/chat-widget)
-[![license](https://img.shields.io/badge/license-MIT-8b5cf6)](./LICENSE)
-
-</div>
+<p align="center">
+  <a href="#why-this-widget"><b>Features</b></a> &nbsp;·&nbsp; <a href="#install"><b>Install</b></a> &nbsp;·&nbsp; <a href="#quick-start"><b>Usage</b></a> &nbsp;·&nbsp; <a href="#theming"><b>Theming</b></a> &nbsp;·&nbsp; <a href="#part-of-smoo-ai"><b>Platform</b></a>
+</p>
 
 ---
 
+> A self-contained, streaming chat surface you drop into any site with one tag. No React on the host page, no CSS to import, ~19 kB gzipped, with the smooth-operator protocol client built in.
+
 `<smooth-agent-chat>` is a self-contained chat web component for the
 [smooth-operator](https://github.com/SmooAI/smooth-operator) protocol. Drop in one
 `<script>` tag (or import the ESM module) and you get a polished, streaming,
@@ -60,7 +66,36 @@ installed automatically.
 
 ## Quick start
 
-### 1. Declarative — a `<script>` tag + the element
+### 1. Recommended — the deferred loader (best Core Web Vitals)
+
+Include the tiny **loader** (~2 KB gzipped) eagerly. It does nothing expensive on
+load — it waits until the page is past its critical render (`requestIdleCallback`
+after `load`, **or** the visitor's first pointer/keydown/scroll, **or** an 8 s
+fallback), and only *then* injects the full widget module. The widget never
+competes with your page's LCP/TBT, but it's instantly there the moment a visitor
+shows intent.
+
+```html
+<script>
+    window.SmoothAgentChatConfig = {
+        endpoint: 'wss://your-host/ws',
+        agentId: '11111111-1111-4111-8111-111111111111',
+        agentName: 'Support',
+        greeting: 'Hi! How can I help?',
+    };
+</script>
+<script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget-loader.global.js" async></script>
+```
+
+The loader resolves the widget module as a sibling of its own URL (override with
+`data-src`), so a single CDN path is all you need. For the simplest installs you
+can skip the config global and use `data-*` attributes on the loader tag
+(`data-endpoint`, `data-agent-id`, `data-primary`, `data-mode`).
+
+### 2. Declarative — eager `<script>` + the element
+
+Simplest, but the module evaluates during page load — prefer the loader above on
+performance-sensitive (especially marketing) pages.
 
 ```html
 <script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget.global.js"></script>
@@ -75,7 +110,7 @@ installed automatically.
 
 The IIFE bundle auto-registers the element on load.
 
-### 2. Programmatic — bundler / ESM
+### 3. Programmatic — bundler / ESM
 
 ```ts
 import { mountChatWidget } from '@smooai/chat-widget';
@@ -155,12 +190,15 @@ mountChatWidget({
   the collected name/email are attached to the conversation session (phone rides
   session metadata). Set **`allowAnonymous: true`** to skip the form.
 
-### OTP & tool confirmation (programmatic)
+### OTP & tool confirmation (HITL)
 
-The `ConversationController` surfaces mid-turn pauses via an `onInterrupt`
-callback — `otp_verification_required` and `write_confirmation_required` — and
-resumes them with `verifyOtp(code)` / `confirmTool(approved)`. (A built-in dialog
-UI for these is on the roadmap; the protocol plumbing ships today.)
+When a turn pauses for **OTP verification** or a **tool-write approval**, the
+widget shows an inline overlay above the composer — an OTP code prompt (with
+masked destination + retry state) or an Approve/Decline confirmation — and
+resumes the turn automatically. Under the hood the `ConversationController`
+surfaces `otp_verification_required` / `write_confirmation_required` via an
+`onInterrupt` callback and resumes with `verifyOtp(code)` / `confirmTool(approved)`,
+so you can also drive it programmatically.
 
 ## Full-page mode
 
@@ -232,6 +270,25 @@ pnpm test:e2e       # Playwright live e2e (gated — see e2e/)
 Open `index.html` (e.g. `pnpm dlx serve .`) after a build for the interactive,
 backend-free showcase.
 
+## Part of Smoo AI
+
+`@smooai/chat-widget` is built and open-sourced by **[Smoo AI](https://smoo.ai)** — the AI-powered business platform with AI built into every product: CRM, customer support, campaigns, field service, observability, and developer tools.
+
+- 🚀 **Customer support on the platform** — [smoo.ai/platform/support](https://smoo.ai/platform/support)
+- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
+- 🧩 **Sibling repos** — [smooth-operator](https://github.com/SmooAI/smooth-operator) (the protocol it renders), [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) (the engine), [@smooai/config](https://github.com/SmooAI/config), [@smooai/logger](https://github.com/SmooAI/logger)
+
+## Contributing
+
+Issues and PRs welcome. Run `pnpm check` (typecheck + test + build) before opening
+a PR.
+
 ## License
 
-MIT © [SmooAI](https://github.com/SmooAI)
+MIT © [Smoo AI](https://smoo.ai)
+
+---
+
+<p align="center">
+  Built by <a href="https://smoo.ai"><strong>Smoo AI</strong></a> — AI built into every product.
+</p>

package/dist/chat-widget-loader.global.js

@@ -0,0 +1,157 @@
+(function() {
+	//#region src/loader-core.ts
+	/**
+	* Tiny, dependency-free deferred loader for `@smooai/chat-widget`.
+	*
+	* The recommended embed: a host includes this *small* script eagerly, and it
+	* defers injecting the real (heavier) `chat-widget.global.js` module until the
+	* page is past its critical render — so the widget never competes with the host
+	* page's LCP/TBT. It triggers the real load on the **first** of:
+	*
+	*   - `window` `load` → `requestIdleCallback` (idle time), or
+	*   - user intent (`pointerdown` / `keydown` / `scroll`), or
+	*   - an 8s fallback.
+	*
+	* After the module loads (which registers `<smooth-agent-chat>` and exposes
+	* `window.SmoothAgentChat`), it mounts the widget with the host's config.
+	*
+	* Deliberately imports nothing from the widget itself — this file must stay a
+	* few hundred bytes so including it eagerly is free.
+	*
+	* ## Config
+	* Set a global before/with the loader (any `ChatWidgetConfig`, plus an optional
+	* `src` pointing at the module bundle):
+	*
+	* ```html
+	* <script>window.SmoothAgentChatConfig = { endpoint: 'wss://…/ws', agentId: '…' };<\/script>
+	* <script src="https://cdn/…/chat-widget-loader.global.js" async><\/script>
+	* ```
+	*
+	* Or, for the simplest installs, `data-*` attributes on the loader's own tag
+	* (`data-endpoint`, `data-agent-id`, `data-primary`, `data-mode`, `data-src`).
+	* If no config is found, the module is still loaded (registering the element) so
+	* a `<smooth-agent-chat …>` placed directly in markup upgrades itself.
+	*/
+	/** Must match `ELEMENT_TAG` in `element.ts`; inlined to avoid importing it. */
+	const ELEMENT_TAG = "smooth-agent-chat";
+	/** Default module filename, resolved as a sibling of the loader script. */
+	const DEFAULT_MODULE = "chat-widget.global.js";
+	/**
+	* Resolve the module URL: explicit `src` (config or `data-src`) wins, else a
+	* sibling of the loader script, else the bare default filename.
+	*/
+	function resolveModuleSrc(win, script) {
+		const fromConfig = win.SmoothAgentChatConfig?.src;
+		if (fromConfig) return fromConfig;
+		const fromAttr = script?.getAttribute("data-src");
+		if (fromAttr) return fromAttr;
+		const selfSrc = script?.src;
+		if (selfSrc) return selfSrc.replace(/[^/]*$/, DEFAULT_MODULE);
+		return DEFAULT_MODULE;
+	}
+	/**
+	* The widget mount config: the `SmoothAgentChatConfig` global (minus the
+	* loader-only `src`), or `data-*` attributes. `undefined` ⇒ no programmatic
+	* mount (a markup element will upgrade itself once the module registers it).
+	*/
+	function resolveMountConfig(win, script) {
+		if (win.SmoothAgentChatConfig) {
+			const { src: _src, ...config } = win.SmoothAgentChatConfig;
+			return Object.keys(config).length > 0 ? config : void 0;
+		}
+		if (!script) return void 0;
+		const endpoint = script.getAttribute("data-endpoint");
+		const agentId = script.getAttribute("data-agent-id");
+		if (!endpoint && !agentId) return void 0;
+		const config = {};
+		if (endpoint) config.endpoint = endpoint;
+		if (agentId) config.agentId = agentId;
+		const primary = script.getAttribute("data-primary");
+		if (primary) config.theme = { primary };
+		const mode = script.getAttribute("data-mode");
+		if (mode) config.mode = mode;
+		return config;
+	}
+	/**
+	* Install the deferred loader. Idempotent per call; the IIFE entry
+	* (`loader.ts`) invokes it once on script execution.
+	*/
+	function initChatWidgetLoader() {
+		const win = window;
+		const script = document.currentScript ?? null;
+		const moduleSrc = resolveModuleSrc(win, script);
+		let loaded = false;
+		let idleId;
+		let fallbackId;
+		function mountWhenReady() {
+			const config = resolveMountConfig(win, script);
+			if (!config) return;
+			const apply = () => {
+				try {
+					win.SmoothAgentChat?.mount(config);
+				} catch (error) {
+					console.error("[chat-widget loader] mount failed", error);
+				}
+			};
+			if (win.SmoothAgentChat) apply();
+			else if (window.customElements?.whenDefined) window.customElements.whenDefined(ELEMENT_TAG).then(apply, apply);
+			else apply();
+		}
+		function teardown() {
+			if (idleId !== void 0) {
+				window.cancelIdleCallback?.(idleId);
+				window.clearTimeout(idleId);
+			}
+			if (fallbackId !== void 0) window.clearTimeout(fallbackId);
+			window.removeEventListener("pointerdown", load);
+			window.removeEventListener("keydown", load);
+			window.removeEventListener("scroll", load);
+		}
+		function load() {
+			if (loaded) return;
+			loaded = true;
+			teardown();
+			const tag = document.createElement("script");
+			tag.src = moduleSrc;
+			tag.onload = mountWhenReady;
+			tag.onerror = () => console.error("[chat-widget loader] failed to load", moduleSrc);
+			document.head.appendChild(tag);
+		}
+		function schedule() {
+			if (window.requestIdleCallback) idleId = window.requestIdleCallback(() => load(), { timeout: 5e3 });
+			else idleId = window.setTimeout(load, 2500);
+			fallbackId = window.setTimeout(load, 8e3);
+		}
+		window.addEventListener("pointerdown", load, {
+			once: true,
+			passive: true
+		});
+		window.addEventListener("keydown", load, { once: true });
+		window.addEventListener("scroll", load, {
+			once: true,
+			passive: true
+		});
+		if (document.readyState === "complete") schedule();
+		else window.addEventListener("load", schedule, { once: true });
+	}
+	//#endregion
+	//#region src/loader.ts
+	/**
+	* Standalone IIFE entry for the **deferred loader** — built to
+	* `dist/chat-widget-loader.global.js`.
+	*
+	* This is the recommended embed: include it eagerly (it's tiny) and it lazily
+	* injects the real `chat-widget.global.js` module only once the host page is
+	* past its critical render (idle / user intent / 8s fallback), so the widget
+	* never competes with the host's LCP/TBT. See {@link initChatWidgetLoader}.
+	*
+	* ```html
+	* <script>window.SmoothAgentChatConfig = { endpoint: 'wss://…/ws', agentId: '…' };<\/script>
+	* <script src="https://cdn/…/chat-widget-loader.global.js" async><\/script>
+	* ```
+	*/
+	initChatWidgetLoader();
+	//#endregion
+})();
+
+//# sourceMappingURL=chat-widget-loader.global.js.map

package/dist/chat-widget-loader.global.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-loader.global.js","names":[],"sources":["../src/loader-core.ts","../src/loader.ts"],"sourcesContent":["/**\n * Tiny, dependency-free deferred loader for `@smooai/chat-widget`.\n *\n * The recommended embed: a host includes this *small* script eagerly, and it\n * defers injecting the real (heavier) `chat-widget.global.js` module until the\n * page is past its critical render — so the widget never competes with the host\n * page's LCP/TBT. It triggers the real load on the **first** of:\n *\n *   - `window` `load` → `requestIdleCallback` (idle time), or\n *   - user intent (`pointerdown` / `keydown` / `scroll`), or\n *   - an 8s fallback.\n *\n * After the module loads (which registers `<smooth-agent-chat>` and exposes\n * `window.SmoothAgentChat`), it mounts the widget with the host's config.\n *\n * Deliberately imports nothing from the widget itself — this file must stay a\n * few hundred bytes so including it eagerly is free.\n *\n * ## Config\n * Set a global before/with the loader (any `ChatWidgetConfig`, plus an optional\n * `src` pointing at the module bundle):\n *\n * ```html\n * <script>window.SmoothAgentChatConfig = { endpoint: 'wss://…/ws', agentId: '…' };</script>\n * <script src=\"https://cdn/…/chat-widget-loader.global.js\" async></script>\n * ```\n *\n * Or, for the simplest installs, `data-*` attributes on the loader's own tag\n * (`data-endpoint`, `data-agent-id`, `data-primary`, `data-mode`, `data-src`).\n * If no config is found, the module is still loaded (registering the element) so\n * a `<smooth-agent-chat …>` placed directly in markup upgrades itself.\n */\n\n/** Must match `ELEMENT_TAG` in `element.ts`; inlined to avoid importing it. */\nconst ELEMENT_TAG = 'smooth-agent-chat';\n/** Default module filename, resolved as a sibling of the loader script. */\nconst DEFAULT_MODULE = 'chat-widget.global.js';\n\ntype MountFn = (config: Record<string, unknown>, target?: HTMLElement) => unknown;\n\ninterface LoaderWindow extends Window {\n    SmoothAgentChat?: { mount: MountFn };\n    SmoothAgentChatConfig?: Record<string, unknown> & { src?: string };\n}\n\n/**\n * Resolve the module URL: explicit `src` (config or `data-src`) wins, else a\n * sibling of the loader script, else the bare default filename.\n */\nfunction resolveModuleSrc(win: LoaderWindow, script: HTMLScriptElement | null): string {\n    const fromConfig = win.SmoothAgentChatConfig?.src;\n    if (fromConfig) return fromConfig;\n    const fromAttr = script?.getAttribute('data-src');\n    if (fromAttr) return fromAttr;\n    const selfSrc = script?.src;\n    if (selfSrc) return selfSrc.replace(/[^/]*$/, DEFAULT_MODULE);\n    return DEFAULT_MODULE;\n}\n\n/**\n * The widget mount config: the `SmoothAgentChatConfig` global (minus the\n * loader-only `src`), or `data-*` attributes. `undefined` ⇒ no programmatic\n * mount (a markup element will upgrade itself once the module registers it).\n */\nfunction resolveMountConfig(win: LoaderWindow, script: HTMLScriptElement | null): Record<string, unknown> | undefined {\n    if (win.SmoothAgentChatConfig) {\n        const { src: _src, ...config } = win.SmoothAgentChatConfig;\n        // Only `src` (no real fields) ⇒ no programmatic mount; a markup element\n        // upgrades itself once the module registers it.\n        return Object.keys(config).length > 0 ? config : undefined;\n    }\n    if (!script) return undefined;\n    const endpoint = script.getAttribute('data-endpoint');\n    const agentId = script.getAttribute('data-agent-id');\n    if (!endpoint && !agentId) return undefined;\n    const config: Record<string, unknown> = {};\n    if (endpoint) config.endpoint = endpoint;\n    if (agentId) config.agentId = agentId;\n    const primary = script.getAttribute('data-primary');\n    if (primary) config.theme = { primary };\n    const mode = script.getAttribute('data-mode');\n    if (mode) config.mode = mode;\n    return config;\n}\n\n/**\n * Install the deferred loader. Idempotent per call; the IIFE entry\n * (`loader.ts`) invokes it once on script execution.\n */\nexport function initChatWidgetLoader(): void {\n    const win = window as LoaderWindow;\n    const script = (document.currentScript as HTMLScriptElement | null) ?? null;\n    const moduleSrc = resolveModuleSrc(win, script);\n\n    let loaded = false;\n    let idleId: number | undefined;\n    let fallbackId: number | undefined;\n\n    function mountWhenReady(): void {\n        const config = resolveMountConfig(win, script);\n        if (!config) return; // markup element upgrades itself; nothing to mount\n        const apply = () => {\n            try {\n                win.SmoothAgentChat?.mount(config);\n            } catch (error) {\n                console.error('[chat-widget loader] mount failed', error);\n            }\n        };\n        if (win.SmoothAgentChat) {\n            apply();\n        } else if (window.customElements?.whenDefined) {\n            window.customElements.whenDefined(ELEMENT_TAG).then(apply, apply);\n        } else {\n            apply();\n        }\n    }\n\n    function teardown(): void {\n        if (idleId !== undefined) {\n            // The id is either an idle handle or (fallback path) a timeout id;\n            // both cancels are no-ops on the wrong kind, so calling both is safe.\n            window.cancelIdleCallback?.(idleId);\n            window.clearTimeout(idleId);\n        }\n        if (fallbackId !== undefined) window.clearTimeout(fallbackId);\n        window.removeEventListener('pointerdown', load);\n        window.removeEventListener('keydown', load);\n        window.removeEventListener('scroll', load);\n    }\n\n    function load(): void {\n        if (loaded) return;\n        loaded = true;\n        teardown();\n        const tag = document.createElement('script');\n        tag.src = moduleSrc;\n        tag.onload = mountWhenReady;\n        tag.onerror = () => console.error('[chat-widget loader] failed to load', moduleSrc);\n        document.head.appendChild(tag);\n    }\n\n    function schedule(): void {\n        if (window.requestIdleCallback) {\n            idleId = window.requestIdleCallback(() => load(), { timeout: 5000 });\n        } else {\n            idleId = window.setTimeout(load, 2500) as unknown as number;\n        }\n        fallbackId = window.setTimeout(load, 8000) as unknown as number;\n    }\n\n    // User intent loads immediately (they're about to want the widget).\n    window.addEventListener('pointerdown', load, { once: true, passive: true });\n    window.addEventListener('keydown', load, { once: true });\n    window.addEventListener('scroll', load, { once: true, passive: true });\n\n    if (document.readyState === 'complete') {\n        schedule();\n    } else {\n        window.addEventListener('load', schedule, { once: true });\n    }\n}\n","/**\n * Standalone IIFE entry for the **deferred loader** — built to\n * `dist/chat-widget-loader.global.js`.\n *\n * This is the recommended embed: include it eagerly (it's tiny) and it lazily\n * injects the real `chat-widget.global.js` module only once the host page is\n * past its critical render (idle / user intent / 8s fallback), so the widget\n * never competes with the host's LCP/TBT. See {@link initChatWidgetLoader}.\n *\n * ```html\n * <script>window.SmoothAgentChatConfig = { endpoint: 'wss://…/ws', agentId: '…' };</script>\n * <script src=\"https://cdn/…/chat-widget-loader.global.js\" async></script>\n * ```\n */\nimport { initChatWidgetLoader } from './loader-core.js';\n\ninitChatWidgetLoader();\n"],"mappings":"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"}

package/dist/chat-widget.global.js

@@ -1305,6 +1305,63 @@ var SmoothAgentChat = (function(exports) {
     transform: translateY(-1px);
 }
 
+/* ─────────────── OTP / tool-confirmation interrupt ────────────────── */
+.interrupt { padding: 0 14px; }
+.int-card {
+    border: 1px solid color-mix(in srgb, var(--sac-primary) 35%, var(--sac-border));
+    background: color-mix(in srgb, var(--sac-primary) 8%, var(--sac-surface-2));
+    border-radius: 14px;
+    padding: 12px 13px;
+    animation: sac-msg-in .3s var(--sac-ease) both;
+}
+.int-head { display: flex; align-items: center; gap: 8px; }
+.int-ico { display: flex; color: var(--sac-primary); }
+.int-ico svg { width: 17px; height: 17px; }
+.int-title { font-size: 13.5px; font-weight: 650; }
+.int-desc { margin-top: 5px; font-size: 12.5px; line-height: 1.45; color: color-mix(in srgb, var(--sac-text) 80%, transparent); }
+.int-sent { margin-top: 6px; font-size: 11.5px; color: color-mix(in srgb, var(--sac-text) 60%, transparent); }
+.int-row { display: flex; gap: 8px; margin-top: 10px; }
+.int-input {
+    flex: 1;
+    min-width: 0;
+    border: 1px solid color-mix(in srgb, var(--sac-border) 80%, transparent);
+    background: var(--sac-bg);
+    color: var(--sac-text);
+    border-radius: 10px;
+    padding: 9px 11px;
+    font-family: inherit;
+    font-size: 14px;
+    letter-spacing: .14em;
+    outline: none;
+    transition: border-color .2s ease, box-shadow .2s ease;
+}
+.int-input:focus {
+    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-btn {
+    border: 1px solid color-mix(in srgb, var(--sac-border) 80%, transparent);
+    background: var(--sac-surface-2);
+    color: var(--sac-text);
+    border-radius: 10px;
+    padding: 9px 14px;
+    font-family: inherit;
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: transform .2s var(--sac-ease), background .2s ease, border-color .2s ease;
+}
+.int-btn:hover { transform: translateY(-1px); }
+.int-btn.primary {
+    border: none;
+    background: linear-gradient(150deg, var(--sac-primary), var(--sac-primary-2));
+    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-error { margin-top: 8px; font-size: 12px; color: #f87171; }
+
 .hidden { display: none !important; }
 
 @media (prefers-reduced-motion: reduce) {
@@ -1339,7 +1396,11 @@ var SmoothAgentChat = (function(exports) {
 		/** Send — an upward arrow. */
 		send: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 19V6M12 6l-5.5 5.5M12 6l5.5 5.5" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
 		/** Sources disclosure caret. */
-		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>`
+		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>`,
+		/** 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>`
 	};
 	/**
 	* Return `url` only if it is a valid absolute `http(s)` URL, else `null`.
@@ -1376,6 +1437,9 @@ var SmoothAgentChat = (function(exports) {
 		hasSent = false;
 		/** Starter prompts shown as chips in the empty state. */
 		examplePrompts = [];
+		/** Current mid-turn interrupt (OTP / tool-confirmation), or null. */
+		interrupt = null;
+		interruptEl = null;
 		panelEl = null;
 		launcherEl = null;
 		messagesEl = null;
@@ -1468,6 +1532,10 @@ var SmoothAgentChat = (function(exports) {
 						this.status = status;
 						this.renderStatus();
 						this.renderComposerState();
+					},
+					onInterrupt: (interrupt) => {
+						this.interrupt = interrupt;
+						this.renderInterrupt();
 					}
 				});
 				if (resolved.startOpen) this.open = true;
@@ -1510,6 +1578,7 @@ var SmoothAgentChat = (function(exports) {
             </div>`;
 			const chatHtml = `
                 <div class="messages"></div>
+                <div class="interrupt hidden"></div>
                 <div class="composer-wrap">
                     <div class="composer">
                         <textarea rows="1" placeholder="${escapeHtml(resolved.placeholder)}"></textarea>
@@ -1536,6 +1605,7 @@ var SmoothAgentChat = (function(exports) {
 			this.dotEl = container.querySelector(".dot");
 			this.inputEl = container.querySelector("textarea");
 			this.sendBtn = container.querySelector(".send");
+			this.interruptEl = container.querySelector(".interrupt");
 			this.launcherEl?.addEventListener("click", () => this.openChat());
 			container.querySelector(".close")?.addEventListener("click", () => this.closeChat());
 			this.sendBtn?.addEventListener("click", () => this.submit());
@@ -1556,6 +1626,97 @@ var SmoothAgentChat = (function(exports) {
 			if (!gating) this.renderMessages(resolved.greeting);
 			this.renderStatus();
 			this.renderComposerState();
+			this.renderInterrupt();
+		}
+		/**
+		* Render (or clear) the mid-turn interrupt overlay above the composer:
+		* an OTP code prompt or a tool-write confirmation. Server-supplied text is
+		* set via `textContent` (never innerHTML); only static icons use innerHTML.
+		*/
+		renderInterrupt() {
+			const el = this.interruptEl;
+			if (!el) return;
+			el.replaceChildren();
+			const it = this.interrupt;
+			if (!it) {
+				el.classList.add("hidden");
+				return;
+			}
+			el.classList.remove("hidden");
+			const card = document.createElement("div");
+			card.className = "int-card";
+			const head = document.createElement("div");
+			head.className = "int-head";
+			const ico = document.createElement("span");
+			ico.className = "int-ico";
+			ico.innerHTML = it.kind === "otp" ? ICON.lock : ICON.shield;
+			const title = document.createElement("span");
+			title.className = "int-title";
+			title.textContent = it.kind === "otp" ? "Verification required" : "Confirm this action";
+			head.append(ico, title);
+			card.appendChild(head);
+			if (it.actionDescription) {
+				const desc = document.createElement("div");
+				desc.className = "int-desc";
+				desc.textContent = it.actionDescription;
+				card.appendChild(desc);
+			}
+			if (it.kind === "otp") {
+				if (it.sent?.maskedDestination) {
+					const sent = document.createElement("div");
+					sent.className = "int-sent";
+					sent.textContent = `Code sent to ${it.sent.maskedDestination}${it.sent.channel ? ` via ${it.sent.channel}` : ""}.`;
+					card.appendChild(sent);
+				}
+				const row = document.createElement("div");
+				row.className = "int-row";
+				const input = document.createElement("input");
+				input.className = "int-input";
+				input.type = "text";
+				input.inputMode = "numeric";
+				input.autocomplete = "one-time-code";
+				input.placeholder = "Enter code";
+				const submit = () => {
+					const code = input.value.trim();
+					if (code) this.controller?.verifyOtp(code);
+				};
+				input.addEventListener("keydown", (ev) => {
+					if (ev.key === "Enter") {
+						ev.preventDefault();
+						submit();
+					}
+				});
+				const verify = document.createElement("button");
+				verify.className = "int-btn primary";
+				verify.type = "button";
+				verify.textContent = "Verify";
+				verify.addEventListener("click", submit);
+				row.append(input, verify);
+				card.appendChild(row);
+				if (it.error) {
+					const err = document.createElement("div");
+					err.className = "int-error";
+					err.textContent = it.attemptsRemaining != null ? `${it.error} (${it.attemptsRemaining} left)` : it.error;
+					card.appendChild(err);
+				}
+				queueMicrotask(() => input.focus());
+			} else {
+				const row = document.createElement("div");
+				row.className = "int-row";
+				const decline = document.createElement("button");
+				decline.className = "int-btn";
+				decline.type = "button";
+				decline.textContent = "Decline";
+				decline.addEventListener("click", () => this.controller?.confirmTool(false));
+				const approve = document.createElement("button");
+				approve.className = "int-btn primary";
+				approve.type = "button";
+				approve.textContent = "Approve";
+				approve.addEventListener("click", () => this.controller?.confirmTool(true));
+				row.append(decline, approve);
+				card.appendChild(row);
+			}
+			el.appendChild(card);
 		}
 		/** Collect identity from the pre-chat form, then drop into the chat view. */
 		handlePrechatSubmit(form) {