chatablex-web-sdk 1.0.34 → 1.0.36

package/dist/index.d.mts

@@ -279,8 +279,15 @@ interface AgentLockConfig {
     allowCancel?: boolean;
     /** Overlay background opacity, 0–1 (default: 0.3). */
     opacity?: number;
-    /** Auto-unlock timeout in ms (default: 30000). 0 disables. */
+    /** Auto-unlock timeout for a single tool execution, in ms (default: 30000). 0 disables. */
     timeout?: number;
+    /**
+     * Safety auto-unlock timeout for a whole agent turn, in ms (default: 0 =
+     * disabled, rely on the host's turn-end signal). When the host drives a
+     * turn-level lock (the lock spans the entire agent response, not just one
+     * tool), this acts purely as a fallback in case the turn-end signal is lost.
+     */
+    turnTimeout?: number;
     /** Delay before actually removing the overlay after unlock, to avoid flicker between consecutive tools (default: 200ms). */
     debounceUnlock?: number;
 }

package/dist/index.d.ts

@@ -279,8 +279,15 @@ interface AgentLockConfig {
     allowCancel?: boolean;
     /** Overlay background opacity, 0–1 (default: 0.3). */
     opacity?: number;
-    /** Auto-unlock timeout in ms (default: 30000). 0 disables. */
+    /** Auto-unlock timeout for a single tool execution, in ms (default: 30000). 0 disables. */
     timeout?: number;
+    /**
+     * Safety auto-unlock timeout for a whole agent turn, in ms (default: 0 =
+     * disabled, rely on the host's turn-end signal). When the host drives a
+     * turn-level lock (the lock spans the entire agent response, not just one
+     * tool), this acts purely as a fallback in case the turn-end signal is lost.
+     */
+    turnTimeout?: number;
     /** Delay before actually removing the overlay after unlock, to avoid flicker between consecutive tools (default: 200ms). */
     debounceUnlock?: number;
 }

package/dist/index.js

@@ -553,8 +553,10 @@ var DEFAULT_CONFIG = {
   allowCancel: true,
   opacity: 0.3,
   timeout: 3e4,
+  turnTimeout: 0,
   debounceUnlock: 200
 };
+var TURN_EVENT = "agentLock";
 var OVERLAY_ID = "__chatablex_agent_lock_overlay__";
 var BLOCKED_EVENTS = [
   "mousedown",
@@ -580,13 +582,14 @@ function blockEvent(e) {
   e.stopPropagation();
   e.preventDefault();
 }
-function createAgentLockModule(_bridge, userConfig = {}) {
+function createAgentLockModule(bridge, userConfig = {}) {
   const cfg = { ...DEFAULT_CONFIG, ...userConfig };
   const logoSrc = cfg.logoUrl || bee_default;
   const listeners = /* @__PURE__ */ new Map();
   let overlayEl = null;
   let locked = false;
   let lockCount = 0;
+  let turnActive = false;
   let timeoutTimer = null;
   let debounceTimer = null;
   let currentMessage = cfg.message;
@@ -697,6 +700,7 @@ function createAgentLockModule(_bridge, userConfig = {}) {
     if (!locked) return;
     locked = false;
     lockCount = 0;
+    turnActive = false;
     clearTimeoutTimer();
     clearDebounceTimer();
     if (cfg.mode === "overlay") {
@@ -704,11 +708,34 @@ function createAgentLockModule(_bridge, userConfig = {}) {
     }
     emit("unlock", { requestId });
   }
+  function maybeUnlock(requestId) {
+    if (turnActive || lockCount > 0) return;
+    forceUnlock(requestId);
+  }
+  function scheduleDebouncedUnlock(requestId) {
+    clearDebounceTimer();
+    debounceTimer = setTimeout(() => maybeUnlock(requestId), cfg.debounceUnlock);
+  }
   function handleCancel() {
     const rid = void 0;
     forceUnlock(rid);
     emit("cancel", { requestId: rid });
   }
+  function setTurn(active) {
+    if (!cfg.enabled) return;
+    if (active) {
+      turnActive = true;
+      clearDebounceTimer();
+      if (!locked) {
+        doLock(cfg.message, cfg.turnTimeout);
+      } else {
+        startTimeout(cfg.turnTimeout);
+      }
+    } else {
+      turnActive = false;
+      if (lockCount === 0) scheduleDebouncedUnlock();
+    }
+  }
   function lock(opts) {
     if (!cfg.enabled) return;
     const msg = opts?.message ?? cfg.message;
@@ -734,32 +761,32 @@ function createAgentLockModule(_bridge, userConfig = {}) {
     clearDebounceTimer();
     lockCount++;
     if (!locked) {
-      doLock(cfg.message, cfg.timeout, requestId);
+      doLock(cfg.message, turnActive ? cfg.turnTimeout : cfg.timeout, requestId);
     }
   }
   function _autoUnlock(requestId) {
     if (!cfg.enabled) return;
     lockCount = Math.max(0, lockCount - 1);
     if (lockCount === 0) {
-      clearDebounceTimer();
-      debounceTimer = setTimeout(() => {
-        if (lockCount === 0) {
-          forceUnlock(requestId);
-        }
-      }, cfg.debounceUnlock);
+      scheduleDebouncedUnlock(requestId);
     }
   }
   function _destroy() {
+    if (removeTurnListener) removeTurnListener();
     forceUnlock();
     listeners.clear();
   }
+  const removeTurnListener = bridge.addEventListener(TURN_EVENT, (data) => {
+    const active = !!data?.active;
+    setTurn(active);
+  });
   return { lock, unlock, isLocked, on, off, _autoLock, _autoUnlock, _destroy };
 }
 
 // package.json
 var package_default = {
   name: "chatablex-web-sdk",
-  version: "1.0.34",
+  version: "1.0.36",
   description: "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/dist/index.mjs

@@ -521,8 +521,10 @@ var DEFAULT_CONFIG = {
   allowCancel: true,
   opacity: 0.3,
   timeout: 3e4,
+  turnTimeout: 0,
   debounceUnlock: 200
 };
+var TURN_EVENT = "agentLock";
 var OVERLAY_ID = "__chatablex_agent_lock_overlay__";
 var BLOCKED_EVENTS = [
   "mousedown",
@@ -548,13 +550,14 @@ function blockEvent(e) {
   e.stopPropagation();
   e.preventDefault();
 }
-function createAgentLockModule(_bridge, userConfig = {}) {
+function createAgentLockModule(bridge, userConfig = {}) {
   const cfg = { ...DEFAULT_CONFIG, ...userConfig };
   const logoSrc = cfg.logoUrl || bee_default;
   const listeners = /* @__PURE__ */ new Map();
   let overlayEl = null;
   let locked = false;
   let lockCount = 0;
+  let turnActive = false;
   let timeoutTimer = null;
   let debounceTimer = null;
   let currentMessage = cfg.message;
@@ -665,6 +668,7 @@ function createAgentLockModule(_bridge, userConfig = {}) {
     if (!locked) return;
     locked = false;
     lockCount = 0;
+    turnActive = false;
     clearTimeoutTimer();
     clearDebounceTimer();
     if (cfg.mode === "overlay") {
@@ -672,11 +676,34 @@ function createAgentLockModule(_bridge, userConfig = {}) {
     }
     emit("unlock", { requestId });
   }
+  function maybeUnlock(requestId) {
+    if (turnActive || lockCount > 0) return;
+    forceUnlock(requestId);
+  }
+  function scheduleDebouncedUnlock(requestId) {
+    clearDebounceTimer();
+    debounceTimer = setTimeout(() => maybeUnlock(requestId), cfg.debounceUnlock);
+  }
   function handleCancel() {
     const rid = void 0;
     forceUnlock(rid);
     emit("cancel", { requestId: rid });
   }
+  function setTurn(active) {
+    if (!cfg.enabled) return;
+    if (active) {
+      turnActive = true;
+      clearDebounceTimer();
+      if (!locked) {
+        doLock(cfg.message, cfg.turnTimeout);
+      } else {
+        startTimeout(cfg.turnTimeout);
+      }
+    } else {
+      turnActive = false;
+      if (lockCount === 0) scheduleDebouncedUnlock();
+    }
+  }
   function lock(opts) {
     if (!cfg.enabled) return;
     const msg = opts?.message ?? cfg.message;
@@ -702,32 +729,32 @@ function createAgentLockModule(_bridge, userConfig = {}) {
     clearDebounceTimer();
     lockCount++;
     if (!locked) {
-      doLock(cfg.message, cfg.timeout, requestId);
+      doLock(cfg.message, turnActive ? cfg.turnTimeout : cfg.timeout, requestId);
     }
   }
   function _autoUnlock(requestId) {
     if (!cfg.enabled) return;
     lockCount = Math.max(0, lockCount - 1);
     if (lockCount === 0) {
-      clearDebounceTimer();
-      debounceTimer = setTimeout(() => {
-        if (lockCount === 0) {
-          forceUnlock(requestId);
-        }
-      }, cfg.debounceUnlock);
+      scheduleDebouncedUnlock(requestId);
     }
   }
   function _destroy() {
+    if (removeTurnListener) removeTurnListener();
     forceUnlock();
     listeners.clear();
   }
+  const removeTurnListener = bridge.addEventListener(TURN_EVENT, (data) => {
+    const active = !!data?.active;
+    setTurn(active);
+  });
   return { lock, unlock, isLocked, on, off, _autoLock, _autoUnlock, _destroy };
 }
 
 // package.json
 var package_default = {
   name: "chatablex-web-sdk",
-  version: "1.0.34",
+  version: "1.0.36",
   description: "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatablex-web-sdk",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "description": "ChatableX Web SDK for AI App WebUI development. Provides bridge communication with the ChatableX Flutter client.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/modules/agentLock.ts

@@ -16,9 +16,17 @@ const DEFAULT_CONFIG: Required<AgentLockConfig> = {
   allowCancel: true,
   opacity: 0.3,
   timeout: 30_000,
+  turnTimeout: 0,
   debounceUnlock: 200,
 };
 
+/**
+ * Bridge event pushed by the Flutter host to lock the UI for the *entire* agent
+ * turn (from the moment the agent starts responding until the turn ends),
+ * rather than only during each individual tool execution. Payload: `{ active }`.
+ */
+const TURN_EVENT = 'agentLock';
+
 const OVERLAY_ID = '__chatablex_agent_lock_overlay__';
 
 /**
@@ -55,7 +63,7 @@ export interface AgentLockModule extends ChatableXAgentLock {
 }
 
 export function createAgentLockModule(
-  _bridge: Bridge,
+  bridge: Bridge,
   userConfig: AgentLockConfig = {},
 ): AgentLockModule {
   const cfg: Required<AgentLockConfig> = { ...DEFAULT_CONFIG, ...userConfig };
@@ -65,6 +73,12 @@ export function createAgentLockModule(
   let overlayEl: HTMLDivElement | null = null;
   let locked = false;
   let lockCount = 0;
+  /**
+   * True while an agent *turn* is in progress (driven by the host's
+   * {@link TURN_EVENT}). Keeps the overlay up across the whole response — and
+   * across the gaps between individual tool calls — until the turn ends.
+   */
+  let turnActive = false;
   let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let currentMessage = cfg.message;
@@ -181,6 +195,7 @@ export function createAgentLockModule(
     if (!locked) return;
     locked = false;
     lockCount = 0;
+    turnActive = false;
     clearTimeoutTimer();
     clearDebounceTimer();
     if (cfg.mode === 'overlay') {
@@ -189,12 +204,51 @@ export function createAgentLockModule(
     emit('unlock', { requestId });
   }
 
+  /**
+   * Release the lock only when nothing is still holding it — i.e. no agent turn
+   * is in progress and no tool execution is outstanding. This is what keeps the
+   * overlay from flickering off between tools or mid-turn.
+   */
+  function maybeUnlock(requestId?: string): void {
+    if (turnActive || lockCount > 0) return;
+    forceUnlock(requestId);
+  }
+
+  function scheduleDebouncedUnlock(requestId?: string): void {
+    clearDebounceTimer();
+    debounceTimer = setTimeout(() => maybeUnlock(requestId), cfg.debounceUnlock);
+  }
+
   function handleCancel(): void {
     const rid = undefined; // auto mode tracks this externally
+    // Explicit user cancel wins over any in-progress turn/tool tracking.
     forceUnlock(rid);
     emit('cancel', { requestId: rid });
   }
 
+  /**
+   * Turn-level lock driven by the host (see {@link TURN_EVENT}). Holds the
+   * overlay for the entire agent response; tool-level auto lock/unlock nests
+   * inside without tearing the overlay down.
+   */
+  function setTurn(active: boolean): void {
+    if (!cfg.enabled) return;
+    if (active) {
+      turnActive = true;
+      clearDebounceTimer();
+      if (!locked) {
+        doLock(cfg.message, cfg.turnTimeout);
+      } else {
+        // Already locked by a tool — extend its timeout to the (longer) turn
+        // budget so a 30s tool timeout can't drop the overlay mid-turn.
+        startTimeout(cfg.turnTimeout);
+      }
+    } else {
+      turnActive = false;
+      if (lockCount === 0) scheduleDebouncedUnlock();
+    }
+  }
+
   // Public API -----------------------------------------------------------------
 
   function lock(opts?: { message?: string; timeout?: number }): void {
@@ -229,7 +283,9 @@ export function createAgentLockModule(
     clearDebounceTimer();
     lockCount++;
     if (!locked) {
-      doLock(cfg.message, cfg.timeout, requestId);
+      // Inside a turn the (longer) turn budget governs; standalone tool calls
+      // keep the per-tool timeout.
+      doLock(cfg.message, turnActive ? cfg.turnTimeout : cfg.timeout, requestId);
     }
   }
 
@@ -237,19 +293,21 @@ export function createAgentLockModule(
     if (!cfg.enabled) return;
     lockCount = Math.max(0, lockCount - 1);
     if (lockCount === 0) {
-      clearDebounceTimer();
-      debounceTimer = setTimeout(() => {
-        if (lockCount === 0) {
-          forceUnlock(requestId);
-        }
-      }, cfg.debounceUnlock);
+      scheduleDebouncedUnlock(requestId);
     }
   }
 
   function _destroy(): void {
+    if (removeTurnListener) removeTurnListener();
     forceUnlock();
     listeners.clear();
   }
 
+  // Listen for host-driven turn lock/unlock. Payload shape: `{ active: boolean }`.
+  const removeTurnListener = bridge.addEventListener(TURN_EVENT, (data) => {
+    const active = !!(data as { active?: unknown } | undefined)?.active;
+    setTurn(active);
+  });
+
   return { lock, unlock, isLocked, on, off, _autoLock, _autoUnlock, _destroy };
 }

package/src/types.ts

@@ -354,8 +354,15 @@ export interface AgentLockConfig {
   allowCancel?: boolean;
   /** Overlay background opacity, 0–1 (default: 0.3). */
   opacity?: number;
-  /** Auto-unlock timeout in ms (default: 30000). 0 disables. */
+  /** Auto-unlock timeout for a single tool execution, in ms (default: 30000). 0 disables. */
   timeout?: number;
+  /**
+   * Safety auto-unlock timeout for a whole agent turn, in ms (default: 0 =
+   * disabled, rely on the host's turn-end signal). When the host drives a
+   * turn-level lock (the lock spans the entire agent response, not just one
+   * tool), this acts purely as a fallback in case the turn-end signal is lost.
+   */
+  turnTimeout?: number;
   /** Delay before actually removing the overlay after unlock, to avoid flicker between consecutive tools (default: 200ms). */
   debounceUnlock?: number;
 }