@modelnex/sdk 0.5.45 → 0.5.47

package/dist/index.js

@@ -1119,6 +1119,159 @@ function serializeContexts(contexts) {
 
 // src/hooks/useModelNexSocket.ts
 init_dev_logging();
+
+// src/utils/debug-tools.ts
+var lastActionEffect = null;
+function normalizeText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+function isElementVisible(el) {
+  if (!(el instanceof HTMLElement)) return false;
+  const style = window.getComputedStyle(el);
+  if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+    return false;
+  }
+  const rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+function safeQueryAll2(selector) {
+  try {
+    return Array.from(document.querySelectorAll(selector)).filter(
+      (el) => el instanceof HTMLElement
+    );
+  } catch {
+    return [];
+  }
+}
+function classifyLevel(el, text) {
+  const levelHint = `${el.getAttribute("data-variant") || ""} ${el.className || ""} ${text}`.toLowerCase();
+  if (/\berror|danger|invalid|failed|required\b/.test(levelHint)) return "error";
+  if (/\bwarn|warning|caution\b/.test(levelHint)) return "warning";
+  return "info";
+}
+function classifySource(el) {
+  const role = (el.getAttribute("role") || "").toLowerCase();
+  if (role === "alert") return "alert";
+  if (role === "status") return "status";
+  if (el.hasAttribute("aria-live")) return "aria-live";
+  const classHint = String(el.className || "").toLowerCase();
+  if (/\bbanner\b/.test(classHint)) return "banner";
+  return "inline";
+}
+function selectorHintFor(el) {
+  if (el.id) return `#${el.id}`;
+  if (el.getAttribute("data-testid")) return `[data-testid="${el.getAttribute("data-testid")}"]`;
+  const role = el.getAttribute("role");
+  return role ? `${el.tagName.toLowerCase()}[role="${role}"]` : el.tagName.toLowerCase();
+}
+function collectUiMessages(options) {
+  const includeHidden = Boolean(options?.includeHidden);
+  const maxItems = Math.max(1, Math.min(Number(options?.maxItems || 10), 20));
+  const selectors = [
+    '[role="alert"]',
+    '[role="status"]',
+    "[aria-live]",
+    '[aria-invalid="true"]',
+    "[data-error]",
+    "[data-warning]",
+    ".error",
+    ".warning",
+    ".alert",
+    ".toast",
+    ".banner"
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const selector of selectors) {
+    for (const el of safeQueryAll2(selector)) {
+      const visible = isElementVisible(el);
+      if (!includeHidden && !visible) continue;
+      const text = normalizeText(el.textContent);
+      if (!text || text.length < 2) continue;
+      const key = `${selector}:${text.toLowerCase()}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      results.push({
+        id: `ui_${results.length + 1}`,
+        level: classifyLevel(el, text),
+        text,
+        source: classifySource(el),
+        visible,
+        selectorHint: selectorHintFor(el)
+      });
+      if (results.length >= maxItems) return results;
+    }
+  }
+  return results;
+}
+function captureDebugSnapshot() {
+  return {
+    route: `${window.location.pathname}${window.location.search}${window.location.hash}`,
+    title: document.title || "",
+    uiMessages: collectUiMessages({ maxItems: 6 }),
+    timestamp: Date.now()
+  };
+}
+function diffUiMessages(before, after) {
+  const beforeKeys = new Set(before.map((entry) => `${entry.level}:${entry.text}`));
+  return after.filter((entry) => !beforeKeys.has(`${entry.level}:${entry.text}`));
+}
+function summarizeEffect(record) {
+  const routeChanged = record.before.route !== record.after.route;
+  const titleChanged = record.before.title !== record.after.title;
+  const newMessages = diffUiMessages(record.before.uiMessages, record.after.uiMessages);
+  const changed = routeChanged || titleChanged || newMessages.length > 0 || !record.success || record.before.timestamp !== record.after.timestamp;
+  const parts = [];
+  if (routeChanged) parts.push(`route changed from ${record.before.route} to ${record.after.route}`);
+  if (titleChanged) parts.push("page title changed");
+  if (newMessages.length > 0) parts.push(`new UI messages: ${newMessages.map((entry) => entry.text).join(" | ")}`);
+  if (!record.success && record.error) parts.push(`action failed: ${record.error}`);
+  if (parts.length === 0) parts.push("no obvious route/title/message change detected");
+  return {
+    summary: parts.join("; "),
+    changed
+  };
+}
+function recordLastActionEffect(record) {
+  const summary = summarizeEffect(record);
+  lastActionEffect = {
+    ...record,
+    ...summary
+  };
+  return lastActionEffect;
+}
+function getLastActionEffectRecord() {
+  return lastActionEffect;
+}
+function inspectDomElementState(el) {
+  const rect = el.getBoundingClientRect();
+  const describedByIds = normalizeText(el.getAttribute("aria-describedby")).split(/\s+/).filter(Boolean);
+  const describedByText = describedByIds.map((id) => normalizeText(document.getElementById(id)?.textContent)).filter(Boolean).join(" | ");
+  const labelText = normalizeText(
+    el.labels?.[0]?.textContent || el.getAttribute("aria-label") || el.getAttribute("name") || el.getAttribute("id") || el.textContent
+  );
+  return {
+    tag: el.tagName.toLowerCase(),
+    label: labelText || null,
+    text: normalizeText(el.textContent).slice(0, 300) || null,
+    value: "value" in el ? normalizeText(String(el.value || "")) || null : null,
+    visible: isElementVisible(el),
+    enabled: !el.hasAttribute("disabled") && el.getAttribute("aria-disabled") !== "true",
+    focused: document.activeElement === el,
+    ariaInvalid: el.getAttribute("aria-invalid") === "true",
+    describedByText: describedByText || null,
+    role: el.getAttribute("role") || null,
+    selectorHint: selectorHintFor(el),
+    rect: {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height)
+    }
+  };
+}
+
+// src/hooks/useModelNexSocket.ts
 function useModelNexSocket({
   serverUrl,
   actions,
@@ -1216,11 +1369,22 @@ function useModelNexSocket({
         const NAV_ACTION_IDS = ["navigate_to_documents", "navigate_to_templates", "navigate_to_inbox", "navigate_to_settings", "navigate_to_template", "navigate_to_document", "navigate_to_folder", "navigate_editor_step"];
         const action = currentActions.get(actionId);
         if (action) {
+          const beforeSnapshot = captureDebugSnapshot();
+          const startedAt = Date.now();
           try {
             const validatedParams = action.schema.parse(params);
             log("[SDK] Executing action", { actionId });
             const execResult = await action.execute(validatedParams);
             log("[SDK] Action completed", { actionId });
+            recordLastActionEffect({
+              actionId,
+              success: true,
+              error: null,
+              startedAt,
+              finishedAt: Date.now(),
+              before: beforeSnapshot,
+              after: captureDebugSnapshot()
+            });
             sendResult(true, execResult);
             if (NAV_ACTION_IDS.includes(actionId)) {
               requestAnimationFrame(() => {
@@ -1245,6 +1409,15 @@ function useModelNexSocket({
           } catch (err) {
             const errMsg = err instanceof Error ? err.message : String(err);
             console.error(`[ModelNex SDK] Execution failed for ${actionId}: ${errMsg}`);
+            recordLastActionEffect({
+              actionId,
+              success: false,
+              error: errMsg,
+              startedAt,
+              finishedAt: Date.now(),
+              before: beforeSnapshot,
+              after: captureDebugSnapshot()
+            });
             if (isSdkDebugEnabled(devMode)) {
               window.dispatchEvent(
                 new CustomEvent("modelnex-debug", {
@@ -2290,7 +2463,7 @@ function isTourEligible(tour, userProfile) {
 var resolutionCache = /* @__PURE__ */ new Map();
 var DEFAULT_WORKFLOW_SEARCH_LIMIT = 5;
 var WORKFLOW_TYPES = ["onboarding", "tour"];
-function safeQueryAll2(selector) {
+function safeQueryAll3(selector) {
   try {
     return Array.from(document.querySelectorAll(selector)).filter(
       (el) => el instanceof HTMLElement
@@ -2299,6 +2472,9 @@ function safeQueryAll2(selector) {
     return [];
   }
 }
+function safeQueryOne(selector) {
+  return safeQueryAll3(selector)[0] || null;
+}
 var ROW_SELECTORS = 'tr, [role="row"], [role="listitem"], li, [data-row], [class*="row"], [class*="card"], article, section';
 function getRowText(el) {
   const row = el.closest(ROW_SELECTORS);
@@ -2330,6 +2506,20 @@ function makeTarget(el, via) {
     resolvedVia: via
   };
 }
+function resolveInspectableElement(params, getTagStore) {
+  if (params.selector) {
+    const bySelector = safeQueryOne(params.selector);
+    if (bySelector) return makeTarget(bySelector, "single-selector");
+  }
+  if (params.fingerprint) {
+    return resolveTargetElement(
+      params.fingerprint,
+      { patternId: params.patternId, textContaining: params.textContaining },
+      getTagStore()
+    );
+  }
+  return null;
+}
 function resolveTargetElement(fingerprint, options, tagStore) {
   const elements = extractInteractiveElements();
   const byFp = elements.find((e) => e.fingerprint === fingerprint);
@@ -2338,7 +2528,7 @@ function resolveTargetElement(fingerprint, options, tagStore) {
   if (cached) {
     const cachedEl = elements.find((e) => e.fingerprint === cached.resolvedFingerprint);
     if (cachedEl?.element) return makeTarget(cachedEl.element, "cache");
-    const selectorMatches = safeQueryAll2(cached.selector);
+    const selectorMatches = safeQueryAll3(cached.selector);
     if (selectorMatches.length === 1) {
       return makeTarget(selectorMatches[0], "cache");
     }
@@ -2357,7 +2547,7 @@ function resolveTargetElement(fingerprint, options, tagStore) {
   const fallbackTags = patternId ? selectorTags.filter((t) => t.patternId !== patternId) : [];
   for (const tagSet of [candidateTags, fallbackTags]) {
     for (const tag of tagSet) {
-      const matched = safeQueryAll2(tag.selector);
+      const matched = safeQueryAll3(tag.selector);
       if (matched.length === 0) continue;
       for (const el of matched) {
         const fp = generateFingerprint(el);
@@ -2443,7 +2633,7 @@ function lastResortScan(fingerprint, options, elements) {
   }
   if (bestEl) return makeTarget(bestEl, "fuzzy");
   if (fpTextHint) {
-    const ariaMatches = safeQueryAll2(`[aria-label*="${CSS.escape(fpTextHint)}"], [data-testid*="${CSS.escape(fpTextHint)}"]`);
+    const ariaMatches = safeQueryAll3(`[aria-label*="${CSS.escape(fpTextHint)}"], [data-testid*="${CSS.escape(fpTextHint)}"]`);
     if (textContaining && ariaMatches.length > 1) {
       let best = null;
       let bestS = 0;
@@ -2785,6 +2975,68 @@ function createWaitAction(getTagStore) {
     }
   };
 }
+var getUiMessagesSchema = import_zod2.z.object({
+  includeHidden: import_zod2.z.boolean().optional().describe("Include currently hidden UI messages when true. Defaults to false."),
+  maxItems: import_zod2.z.number().int().min(1).max(20).optional().describe("Maximum number of messages to return. Defaults to 10.")
+});
+function createGetUiMessagesAction() {
+  return {
+    id: "get_ui_messages",
+    description: "Return current UI-facing messages such as alerts, warnings, toasts, banners, and inline validation text.",
+    schema: getUiMessagesSchema,
+    execute: async (params) => {
+      const messages = collectUiMessages(params);
+      return {
+        messages,
+        total: messages.length,
+        capturedAt: Date.now()
+      };
+    }
+  };
+}
+var getLastActionEffectSchema = import_zod2.z.object({});
+function createGetLastActionEffectAction() {
+  return {
+    id: "get_last_action_effect",
+    description: "Return a compact summary of what changed after the most recent agent action.",
+    schema: getLastActionEffectSchema,
+    execute: async () => {
+      return {
+        effect: getLastActionEffectRecord()
+      };
+    }
+  };
+}
+var inspectElementStateSchema = import_zod2.z.object({
+  fingerprint: import_zod2.z.string().optional().describe("Fingerprint of the target element to inspect."),
+  selector: import_zod2.z.string().optional().describe("Optional CSS selector for direct inspection when a fingerprint is unavailable."),
+  patternId: import_zod2.z.string().optional().describe("Optional patternId from tagged elements for disambiguation."),
+  textContaining: import_zod2.z.string().optional().describe("Optional row or label text used to disambiguate similar elements.")
+});
+function createInspectElementStateAction(getTagStore) {
+  return {
+    id: "inspect_element_state",
+    description: "Inspect one specific element and return its current visibility, enabled state, value/text, aria state, and associated error/help text.",
+    schema: inspectElementStateSchema,
+    execute: async (params) => {
+      const target = resolveInspectableElement(params, getTagStore);
+      if (!target) {
+        return {
+          found: false,
+          reason: "Element not found from the provided fingerprint or selector."
+        };
+      }
+      return {
+        found: true,
+        target: {
+          fingerprint: target.fingerprint,
+          resolvedVia: target.resolvedVia
+        },
+        element: inspectDomElementState(target.element)
+      };
+    }
+  };
+}
 var searchDocsSchema = import_zod2.z.object({
   query: import_zod2.z.string().describe("The search query to find relevant documentation."),
   limit: import_zod2.z.number().optional().describe("Maximum number of results to return (default: 5).")
@@ -2954,6 +3206,9 @@ var BUILTIN_ACTION_IDS = {
   click: "click_element",
   fill: "fill_input",
   wait: "request_user_action",
+  getUiMessages: "get_ui_messages",
+  getLastActionEffect: "get_last_action_effect",
+  inspectElementState: "inspect_element_state",
   searchDocs: "search_docs",
   searchTaggedElements: "search_tagged_elements",
   searchWorkflows: "search_workflows",
@@ -2990,6 +3245,9 @@ function useBuiltinActions(registerAction, unregisterAction, tagStore, serverUrl
     registerAction(createClickAction(getTagStore));
     registerAction(createFillAction(getTagStore));
     registerAction(createWaitAction(getTagStore));
+    registerAction(createGetUiMessagesAction());
+    registerAction(createGetLastActionEffectAction());
+    registerAction(createInspectElementStateAction(getTagStore));
     registerAction(createSearchDocsAction(getServerUrl, getWebsiteId));
     registerAction(createSearchTaggedElementsAction(getTagStore));
     registerAction(createSearchWorkflowsAction(workflowToolGetters));
@@ -3000,6 +3258,9 @@ function useBuiltinActions(registerAction, unregisterAction, tagStore, serverUrl
       unregisterAction(BUILTIN_ACTION_IDS.click);
       unregisterAction(BUILTIN_ACTION_IDS.fill);
       unregisterAction(BUILTIN_ACTION_IDS.wait);
+      unregisterAction(BUILTIN_ACTION_IDS.getUiMessages);
+      unregisterAction(BUILTIN_ACTION_IDS.getLastActionEffect);
+      unregisterAction(BUILTIN_ACTION_IDS.inspectElementState);
       unregisterAction(BUILTIN_ACTION_IDS.searchDocs);
       unregisterAction(BUILTIN_ACTION_IDS.searchTaggedElements);
       unregisterAction(BUILTIN_ACTION_IDS.searchWorkflows);
@@ -4471,6 +4732,13 @@ function useTourPlayback({
           },
           resolve: async () => {
             let targetEl = null;
+            if (typeof params.selector === "string" && params.selector.trim()) {
+              try {
+                targetEl = document.querySelector(params.selector.trim());
+              } catch {
+                targetEl = null;
+              }
+            }
             if (params.uid) {
               const { getElementByUid: getElementByUid2 } = await Promise.resolve().then(() => (init_aom(), aom_exports));
               targetEl = getElementByUid2(params.uid);
@@ -4615,6 +4883,49 @@ function useTourPlayback({
           const resolution = typeof action.params?.resolution === "string" ? action.params.resolution : void 0;
           return { result: await captureScreenshot(selector, resolution) };
         }
+        if (action.type === "get_ui_messages") {
+          const includeHidden = action.params?.includeHidden === true;
+          const maxItems = Number.isFinite(action.params?.maxItems) ? Number(action.params.maxItems) : void 0;
+          const messages = collectUiMessages({ includeHidden, maxItems });
+          return {
+            result: {
+              messages,
+              total: messages.length,
+              capturedAt: Date.now()
+            }
+          };
+        }
+        if (action.type === "get_last_action_effect") {
+          return {
+            result: {
+              effect: getLastActionEffectRecord()
+            }
+          };
+        }
+        if (action.type === "inspect_element_state") {
+          const targetEl = await resolveTargetElement2(action.params, currentStep);
+          if (!targetEl) {
+            return {
+              success: false,
+              result: {
+                found: false,
+                reason: "Element not found from the provided fingerprint, selector, uid, or text hint."
+              },
+              error: "inspect_element_not_found"
+            };
+          }
+          const resolvedVia = typeof action.params?.selector === "string" && action.params.selector.trim() ? "selector" : action.params?.uid ? "uid" : action.params?.fingerprint ? "fingerprint" : action.params?.textContaining ? "textContaining" : "fallback";
+          return {
+            result: {
+              found: true,
+              target: {
+                fingerprint: targetEl.getAttribute("data-modelnex-fp") || null,
+                resolvedVia
+              },
+              element: inspectDomElementState(targetEl)
+            }
+          };
+        }
         if (action.type === "navigate_to_url") {
           const nextUrl = typeof action.params?.url === "string" ? action.params.url : "";
           if (!nextUrl) {
@@ -4667,8 +4978,13 @@ function useTourPlayback({
           handleTourEnd();
           return { result: "ended" };
         }
-        console.warn(`[TourClient] Unknown action type: ${String(action?.type ?? "unknown")}. Skipping.`);
-        return { result: "unknown_action_skipped" };
+        const unknownAction = String(action?.type ?? "unknown");
+        console.warn(`[TourClient] Unknown action type: ${unknownAction}. Skipping.`);
+        return {
+          success: false,
+          result: "unknown_action_skipped",
+          error: `Unknown action type: ${unknownAction}`
+        };
       };
       try {
         const resultsBuffer = new Array(payload.commands.length);
@@ -4682,9 +4998,27 @@ function useTourPlayback({
             pendingUIActions.length = 0;
           }
           const executionPromise = (async () => {
+            const beforeSnapshot = captureDebugSnapshot();
+            const startedAt = Date.now();
             const execution = await executeOne(command);
             await execution.settlePromise;
-            resultsBuffer[commandIndex] = { type: command.type, success: true, result: execution.result };
+            const success = execution.success !== false;
+            const error = typeof execution.error === "string" ? execution.error : null;
+            recordLastActionEffect({
+              actionId: command.type,
+              success,
+              error,
+              startedAt,
+              finishedAt: Date.now(),
+              before: beforeSnapshot,
+              after: captureDebugSnapshot()
+            });
+            resultsBuffer[commandIndex] = {
+              type: command.type,
+              success,
+              result: execution.result,
+              ...error ? { error } : {}
+            };
           })();
           if (isTerminal) {
             await executionPromise;

package/dist/index.mjs

@@ -305,6 +305,157 @@ function serializeContexts(contexts) {
   return Array.from(contexts.values());
 }
 
+// src/utils/debug-tools.ts
+var lastActionEffect = null;
+function normalizeText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+function isElementVisible(el) {
+  if (!(el instanceof HTMLElement)) return false;
+  const style = window.getComputedStyle(el);
+  if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+    return false;
+  }
+  const rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+function safeQueryAll2(selector) {
+  try {
+    return Array.from(document.querySelectorAll(selector)).filter(
+      (el) => el instanceof HTMLElement
+    );
+  } catch {
+    return [];
+  }
+}
+function classifyLevel(el, text) {
+  const levelHint = `${el.getAttribute("data-variant") || ""} ${el.className || ""} ${text}`.toLowerCase();
+  if (/\berror|danger|invalid|failed|required\b/.test(levelHint)) return "error";
+  if (/\bwarn|warning|caution\b/.test(levelHint)) return "warning";
+  return "info";
+}
+function classifySource(el) {
+  const role = (el.getAttribute("role") || "").toLowerCase();
+  if (role === "alert") return "alert";
+  if (role === "status") return "status";
+  if (el.hasAttribute("aria-live")) return "aria-live";
+  const classHint = String(el.className || "").toLowerCase();
+  if (/\bbanner\b/.test(classHint)) return "banner";
+  return "inline";
+}
+function selectorHintFor(el) {
+  if (el.id) return `#${el.id}`;
+  if (el.getAttribute("data-testid")) return `[data-testid="${el.getAttribute("data-testid")}"]`;
+  const role = el.getAttribute("role");
+  return role ? `${el.tagName.toLowerCase()}[role="${role}"]` : el.tagName.toLowerCase();
+}
+function collectUiMessages(options) {
+  const includeHidden = Boolean(options?.includeHidden);
+  const maxItems = Math.max(1, Math.min(Number(options?.maxItems || 10), 20));
+  const selectors = [
+    '[role="alert"]',
+    '[role="status"]',
+    "[aria-live]",
+    '[aria-invalid="true"]',
+    "[data-error]",
+    "[data-warning]",
+    ".error",
+    ".warning",
+    ".alert",
+    ".toast",
+    ".banner"
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const selector of selectors) {
+    for (const el of safeQueryAll2(selector)) {
+      const visible = isElementVisible(el);
+      if (!includeHidden && !visible) continue;
+      const text = normalizeText(el.textContent);
+      if (!text || text.length < 2) continue;
+      const key = `${selector}:${text.toLowerCase()}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      results.push({
+        id: `ui_${results.length + 1}`,
+        level: classifyLevel(el, text),
+        text,
+        source: classifySource(el),
+        visible,
+        selectorHint: selectorHintFor(el)
+      });
+      if (results.length >= maxItems) return results;
+    }
+  }
+  return results;
+}
+function captureDebugSnapshot() {
+  return {
+    route: `${window.location.pathname}${window.location.search}${window.location.hash}`,
+    title: document.title || "",
+    uiMessages: collectUiMessages({ maxItems: 6 }),
+    timestamp: Date.now()
+  };
+}
+function diffUiMessages(before, after) {
+  const beforeKeys = new Set(before.map((entry) => `${entry.level}:${entry.text}`));
+  return after.filter((entry) => !beforeKeys.has(`${entry.level}:${entry.text}`));
+}
+function summarizeEffect(record) {
+  const routeChanged = record.before.route !== record.after.route;
+  const titleChanged = record.before.title !== record.after.title;
+  const newMessages = diffUiMessages(record.before.uiMessages, record.after.uiMessages);
+  const changed = routeChanged || titleChanged || newMessages.length > 0 || !record.success || record.before.timestamp !== record.after.timestamp;
+  const parts = [];
+  if (routeChanged) parts.push(`route changed from ${record.before.route} to ${record.after.route}`);
+  if (titleChanged) parts.push("page title changed");
+  if (newMessages.length > 0) parts.push(`new UI messages: ${newMessages.map((entry) => entry.text).join(" | ")}`);
+  if (!record.success && record.error) parts.push(`action failed: ${record.error}`);
+  if (parts.length === 0) parts.push("no obvious route/title/message change detected");
+  return {
+    summary: parts.join("; "),
+    changed
+  };
+}
+function recordLastActionEffect(record) {
+  const summary = summarizeEffect(record);
+  lastActionEffect = {
+    ...record,
+    ...summary
+  };
+  return lastActionEffect;
+}
+function getLastActionEffectRecord() {
+  return lastActionEffect;
+}
+function inspectDomElementState(el) {
+  const rect = el.getBoundingClientRect();
+  const describedByIds = normalizeText(el.getAttribute("aria-describedby")).split(/\s+/).filter(Boolean);
+  const describedByText = describedByIds.map((id) => normalizeText(document.getElementById(id)?.textContent)).filter(Boolean).join(" | ");
+  const labelText = normalizeText(
+    el.labels?.[0]?.textContent || el.getAttribute("aria-label") || el.getAttribute("name") || el.getAttribute("id") || el.textContent
+  );
+  return {
+    tag: el.tagName.toLowerCase(),
+    label: labelText || null,
+    text: normalizeText(el.textContent).slice(0, 300) || null,
+    value: "value" in el ? normalizeText(String(el.value || "")) || null : null,
+    visible: isElementVisible(el),
+    enabled: !el.hasAttribute("disabled") && el.getAttribute("aria-disabled") !== "true",
+    focused: document.activeElement === el,
+    ariaInvalid: el.getAttribute("aria-invalid") === "true",
+    describedByText: describedByText || null,
+    role: el.getAttribute("role") || null,
+    selectorHint: selectorHintFor(el),
+    rect: {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height)
+    }
+  };
+}
+
 // src/hooks/useModelNexSocket.ts
 function useModelNexSocket({
   serverUrl,
@@ -403,11 +554,22 @@ function useModelNexSocket({
         const NAV_ACTION_IDS = ["navigate_to_documents", "navigate_to_templates", "navigate_to_inbox", "navigate_to_settings", "navigate_to_template", "navigate_to_document", "navigate_to_folder", "navigate_editor_step"];
         const action = currentActions.get(actionId);
         if (action) {
+          const beforeSnapshot = captureDebugSnapshot();
+          const startedAt = Date.now();
           try {
             const validatedParams = action.schema.parse(params);
             log("[SDK] Executing action", { actionId });
             const execResult = await action.execute(validatedParams);
             log("[SDK] Action completed", { actionId });
+            recordLastActionEffect({
+              actionId,
+              success: true,
+              error: null,
+              startedAt,
+              finishedAt: Date.now(),
+              before: beforeSnapshot,
+              after: captureDebugSnapshot()
+            });
             sendResult(true, execResult);
             if (NAV_ACTION_IDS.includes(actionId)) {
               requestAnimationFrame(() => {
@@ -432,6 +594,15 @@ function useModelNexSocket({
           } catch (err) {
             const errMsg = err instanceof Error ? err.message : String(err);
             console.error(`[ModelNex SDK] Execution failed for ${actionId}: ${errMsg}`);
+            recordLastActionEffect({
+              actionId,
+              success: false,
+              error: errMsg,
+              startedAt,
+              finishedAt: Date.now(),
+              before: beforeSnapshot,
+              after: captureDebugSnapshot()
+            });
             if (isSdkDebugEnabled(devMode)) {
               window.dispatchEvent(
                 new CustomEvent("modelnex-debug", {
@@ -1471,7 +1642,7 @@ function isTourEligible(tour, userProfile) {
 var resolutionCache = /* @__PURE__ */ new Map();
 var DEFAULT_WORKFLOW_SEARCH_LIMIT = 5;
 var WORKFLOW_TYPES = ["onboarding", "tour"];
-function safeQueryAll2(selector) {
+function safeQueryAll3(selector) {
   try {
     return Array.from(document.querySelectorAll(selector)).filter(
       (el) => el instanceof HTMLElement
@@ -1480,6 +1651,9 @@ function safeQueryAll2(selector) {
     return [];
   }
 }
+function safeQueryOne(selector) {
+  return safeQueryAll3(selector)[0] || null;
+}
 var ROW_SELECTORS = 'tr, [role="row"], [role="listitem"], li, [data-row], [class*="row"], [class*="card"], article, section';
 function getRowText(el) {
   const row = el.closest(ROW_SELECTORS);
@@ -1511,6 +1685,20 @@ function makeTarget(el, via) {
     resolvedVia: via
   };
 }
+function resolveInspectableElement(params, getTagStore) {
+  if (params.selector) {
+    const bySelector = safeQueryOne(params.selector);
+    if (bySelector) return makeTarget(bySelector, "single-selector");
+  }
+  if (params.fingerprint) {
+    return resolveTargetElement(
+      params.fingerprint,
+      { patternId: params.patternId, textContaining: params.textContaining },
+      getTagStore()
+    );
+  }
+  return null;
+}
 function resolveTargetElement(fingerprint, options, tagStore) {
   const elements = extractInteractiveElements();
   const byFp = elements.find((e) => e.fingerprint === fingerprint);
@@ -1519,7 +1707,7 @@ function resolveTargetElement(fingerprint, options, tagStore) {
   if (cached) {
     const cachedEl = elements.find((e) => e.fingerprint === cached.resolvedFingerprint);
     if (cachedEl?.element) return makeTarget(cachedEl.element, "cache");
-    const selectorMatches = safeQueryAll2(cached.selector);
+    const selectorMatches = safeQueryAll3(cached.selector);
     if (selectorMatches.length === 1) {
       return makeTarget(selectorMatches[0], "cache");
     }
@@ -1538,7 +1726,7 @@ function resolveTargetElement(fingerprint, options, tagStore) {
   const fallbackTags = patternId ? selectorTags.filter((t) => t.patternId !== patternId) : [];
   for (const tagSet of [candidateTags, fallbackTags]) {
     for (const tag of tagSet) {
-      const matched = safeQueryAll2(tag.selector);
+      const matched = safeQueryAll3(tag.selector);
       if (matched.length === 0) continue;
       for (const el of matched) {
         const fp = generateFingerprint(el);
@@ -1624,7 +1812,7 @@ function lastResortScan(fingerprint, options, elements) {
   }
   if (bestEl) return makeTarget(bestEl, "fuzzy");
   if (fpTextHint) {
-    const ariaMatches = safeQueryAll2(`[aria-label*="${CSS.escape(fpTextHint)}"], [data-testid*="${CSS.escape(fpTextHint)}"]`);
+    const ariaMatches = safeQueryAll3(`[aria-label*="${CSS.escape(fpTextHint)}"], [data-testid*="${CSS.escape(fpTextHint)}"]`);
     if (textContaining && ariaMatches.length > 1) {
       let best = null;
       let bestS = 0;
@@ -1966,6 +2154,68 @@ function createWaitAction(getTagStore) {
     }
   };
 }
+var getUiMessagesSchema = z2.object({
+  includeHidden: z2.boolean().optional().describe("Include currently hidden UI messages when true. Defaults to false."),
+  maxItems: z2.number().int().min(1).max(20).optional().describe("Maximum number of messages to return. Defaults to 10.")
+});
+function createGetUiMessagesAction() {
+  return {
+    id: "get_ui_messages",
+    description: "Return current UI-facing messages such as alerts, warnings, toasts, banners, and inline validation text.",
+    schema: getUiMessagesSchema,
+    execute: async (params) => {
+      const messages = collectUiMessages(params);
+      return {
+        messages,
+        total: messages.length,
+        capturedAt: Date.now()
+      };
+    }
+  };
+}
+var getLastActionEffectSchema = z2.object({});
+function createGetLastActionEffectAction() {
+  return {
+    id: "get_last_action_effect",
+    description: "Return a compact summary of what changed after the most recent agent action.",
+    schema: getLastActionEffectSchema,
+    execute: async () => {
+      return {
+        effect: getLastActionEffectRecord()
+      };
+    }
+  };
+}
+var inspectElementStateSchema = z2.object({
+  fingerprint: z2.string().optional().describe("Fingerprint of the target element to inspect."),
+  selector: z2.string().optional().describe("Optional CSS selector for direct inspection when a fingerprint is unavailable."),
+  patternId: z2.string().optional().describe("Optional patternId from tagged elements for disambiguation."),
+  textContaining: z2.string().optional().describe("Optional row or label text used to disambiguate similar elements.")
+});
+function createInspectElementStateAction(getTagStore) {
+  return {
+    id: "inspect_element_state",
+    description: "Inspect one specific element and return its current visibility, enabled state, value/text, aria state, and associated error/help text.",
+    schema: inspectElementStateSchema,
+    execute: async (params) => {
+      const target = resolveInspectableElement(params, getTagStore);
+      if (!target) {
+        return {
+          found: false,
+          reason: "Element not found from the provided fingerprint or selector."
+        };
+      }
+      return {
+        found: true,
+        target: {
+          fingerprint: target.fingerprint,
+          resolvedVia: target.resolvedVia
+        },
+        element: inspectDomElementState(target.element)
+      };
+    }
+  };
+}
 var searchDocsSchema = z2.object({
   query: z2.string().describe("The search query to find relevant documentation."),
   limit: z2.number().optional().describe("Maximum number of results to return (default: 5).")
@@ -2135,6 +2385,9 @@ var BUILTIN_ACTION_IDS = {
   click: "click_element",
   fill: "fill_input",
   wait: "request_user_action",
+  getUiMessages: "get_ui_messages",
+  getLastActionEffect: "get_last_action_effect",
+  inspectElementState: "inspect_element_state",
   searchDocs: "search_docs",
   searchTaggedElements: "search_tagged_elements",
   searchWorkflows: "search_workflows",
@@ -2171,6 +2424,9 @@ function useBuiltinActions(registerAction, unregisterAction, tagStore, serverUrl
     registerAction(createClickAction(getTagStore));
     registerAction(createFillAction(getTagStore));
     registerAction(createWaitAction(getTagStore));
+    registerAction(createGetUiMessagesAction());
+    registerAction(createGetLastActionEffectAction());
+    registerAction(createInspectElementStateAction(getTagStore));
     registerAction(createSearchDocsAction(getServerUrl, getWebsiteId));
     registerAction(createSearchTaggedElementsAction(getTagStore));
     registerAction(createSearchWorkflowsAction(workflowToolGetters));
@@ -2181,6 +2437,9 @@ function useBuiltinActions(registerAction, unregisterAction, tagStore, serverUrl
       unregisterAction(BUILTIN_ACTION_IDS.click);
       unregisterAction(BUILTIN_ACTION_IDS.fill);
       unregisterAction(BUILTIN_ACTION_IDS.wait);
+      unregisterAction(BUILTIN_ACTION_IDS.getUiMessages);
+      unregisterAction(BUILTIN_ACTION_IDS.getLastActionEffect);
+      unregisterAction(BUILTIN_ACTION_IDS.inspectElementState);
       unregisterAction(BUILTIN_ACTION_IDS.searchDocs);
       unregisterAction(BUILTIN_ACTION_IDS.searchTaggedElements);
       unregisterAction(BUILTIN_ACTION_IDS.searchWorkflows);
@@ -3644,6 +3903,13 @@ function useTourPlayback({
           },
           resolve: async () => {
             let targetEl = null;
+            if (typeof params.selector === "string" && params.selector.trim()) {
+              try {
+                targetEl = document.querySelector(params.selector.trim());
+              } catch {
+                targetEl = null;
+              }
+            }
             if (params.uid) {
               const { getElementByUid } = await import("./aom-SP2LMWQI.mjs");
               targetEl = getElementByUid(params.uid);
@@ -3788,6 +4054,49 @@ function useTourPlayback({
           const resolution = typeof action.params?.resolution === "string" ? action.params.resolution : void 0;
           return { result: await captureScreenshot(selector, resolution) };
         }
+        if (action.type === "get_ui_messages") {
+          const includeHidden = action.params?.includeHidden === true;
+          const maxItems = Number.isFinite(action.params?.maxItems) ? Number(action.params.maxItems) : void 0;
+          const messages = collectUiMessages({ includeHidden, maxItems });
+          return {
+            result: {
+              messages,
+              total: messages.length,
+              capturedAt: Date.now()
+            }
+          };
+        }
+        if (action.type === "get_last_action_effect") {
+          return {
+            result: {
+              effect: getLastActionEffectRecord()
+            }
+          };
+        }
+        if (action.type === "inspect_element_state") {
+          const targetEl = await resolveTargetElement2(action.params, currentStep);
+          if (!targetEl) {
+            return {
+              success: false,
+              result: {
+                found: false,
+                reason: "Element not found from the provided fingerprint, selector, uid, or text hint."
+              },
+              error: "inspect_element_not_found"
+            };
+          }
+          const resolvedVia = typeof action.params?.selector === "string" && action.params.selector.trim() ? "selector" : action.params?.uid ? "uid" : action.params?.fingerprint ? "fingerprint" : action.params?.textContaining ? "textContaining" : "fallback";
+          return {
+            result: {
+              found: true,
+              target: {
+                fingerprint: targetEl.getAttribute("data-modelnex-fp") || null,
+                resolvedVia
+              },
+              element: inspectDomElementState(targetEl)
+            }
+          };
+        }
         if (action.type === "navigate_to_url") {
           const nextUrl = typeof action.params?.url === "string" ? action.params.url : "";
           if (!nextUrl) {
@@ -3840,8 +4149,13 @@ function useTourPlayback({
           handleTourEnd();
           return { result: "ended" };
         }
-        console.warn(`[TourClient] Unknown action type: ${String(action?.type ?? "unknown")}. Skipping.`);
-        return { result: "unknown_action_skipped" };
+        const unknownAction = String(action?.type ?? "unknown");
+        console.warn(`[TourClient] Unknown action type: ${unknownAction}. Skipping.`);
+        return {
+          success: false,
+          result: "unknown_action_skipped",
+          error: `Unknown action type: ${unknownAction}`
+        };
       };
       try {
         const resultsBuffer = new Array(payload.commands.length);
@@ -3855,9 +4169,27 @@ function useTourPlayback({
             pendingUIActions.length = 0;
           }
           const executionPromise = (async () => {
+            const beforeSnapshot = captureDebugSnapshot();
+            const startedAt = Date.now();
             const execution = await executeOne(command);
             await execution.settlePromise;
-            resultsBuffer[commandIndex] = { type: command.type, success: true, result: execution.result };
+            const success = execution.success !== false;
+            const error = typeof execution.error === "string" ? execution.error : null;
+            recordLastActionEffect({
+              actionId: command.type,
+              success,
+              error,
+              startedAt,
+              finishedAt: Date.now(),
+              before: beforeSnapshot,
+              after: captureDebugSnapshot()
+            });
+            resultsBuffer[commandIndex] = {
+              type: command.type,
+              success,
+              result: execution.result,
+              ...error ? { error } : {}
+            };
           })();
           if (isTerminal) {
             await executionPromise;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelnex/sdk",
-  "version": "0.5.45",
+  "version": "0.5.47",
   "description": "React SDK for natural language control of web apps via AI agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",