auto-webmcp 0.3.16 → 0.3.18

package/README.md

@@ -57,6 +57,21 @@ await autoWebMCP({
   // Auto-submit when agent invokes (default: false — human must click submit)
   autoSubmit: false,
 
+  // Handling for forms already using native declarative WebMCP attributes:
+  // 'skip' (default), 'augment' (currently same as skip), or 'force'
+  declarativeMode: 'skip',
+
+  // Parameter binding behavior for execute payload keys
+  paramBinding: {
+    enableAliasResolution: true, // default
+    strict: false,               // if true, exact schema keys only
+  },
+
+  // Deterministic execute timeout state
+  execution: {
+    timeoutMs: 15000, // default
+  },
+
   // Per-form name / description overrides
   overrides: {
     '#checkout-form': {

package/dist/auto-webmcp.cjs.js

@@ -26,10 +26,21 @@ module.exports = __toCommonJS(src_exports);
 
 // src/config.ts
 function resolveConfig(userConfig) {
+  const strict = userConfig?.paramBinding?.strict ?? false;
+  const enableAliasResolution = strict ? false : userConfig?.paramBinding?.enableAliasResolution ?? true;
   return {
     exclude: userConfig?.exclude ?? [],
     autoSubmit: userConfig?.autoSubmit ?? false,
+    declarativeMode: userConfig?.declarativeMode ?? "skip",
+    paramBinding: {
+      strict,
+      enableAliasResolution
+    },
+    execution: {
+      timeoutMs: Math.max(100, userConfig?.execution?.timeoutMs ?? 15e3)
+    },
     overrides: userConfig?.overrides ?? {},
+    preserveExisting: userConfig?.preserveExisting ?? false,
     debug: userConfig?.debug ?? false
   };
 }
@@ -989,6 +1000,53 @@ function buildSchemaFromInputs(inputs) {
 }
 
 // src/registry.ts
+var EXECUTE_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: {
+      type: "string",
+      enum: ["success", "partial", "error", "awaiting_user_action", "timed_out", "blocked_invalid"],
+      description: "Outcome of the form execution."
+    },
+    filled_fields: {
+      type: "object",
+      description: "Field name to submitted value map."
+    },
+    skipped_fields: {
+      type: "array",
+      items: { type: "string" },
+      description: "Fields the agent provided but that could not be filled."
+    },
+    missing_required: {
+      type: "array",
+      items: { type: "string" },
+      description: "Required fields not supplied by the agent."
+    },
+    validation_errors: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          field: { type: "string" },
+          constraint: { type: "string", description: "HTML ValidityState key that failed." },
+          message: { type: "string" }
+        },
+        required: ["field", "constraint", "message"]
+      },
+      description: "Per-field HTML5 validation failures (present when status is blocked_invalid)."
+    },
+    existing_values: {
+      type: "object",
+      description: "Field values present in the form before the agent filled it."
+    },
+    warnings: {
+      type: "array",
+      items: { type: "object" },
+      description: "Non-fatal fill warnings (alias_resolved, clamped, not_filled, etc.)."
+    }
+  },
+  required: ["status", "filled_fields", "skipped_fields", "missing_required", "warnings"]
+};
 var registeredTools = /* @__PURE__ */ new Map();
 var registrationControllers = /* @__PURE__ */ new Map();
 function isWebMCPSupported() {
@@ -1005,6 +1063,7 @@ async function registerFormTool(form, metadata, execute) {
     name: metadata.name,
     description: metadata.description,
     inputSchema: metadata.inputSchema,
+    outputSchema: EXECUTE_OUTPUT_SCHEMA,
     execute
   };
   if (metadata.annotations && Object.keys(metadata.annotations).length > 0) {
@@ -1058,9 +1117,128 @@ var formFieldElements = /* @__PURE__ */ new WeakMap();
 var pendingWarnings = /* @__PURE__ */ new WeakMap();
 var pendingFillWarnings = /* @__PURE__ */ new WeakMap();
 var lastFilledSnapshot = /* @__PURE__ */ new WeakMap();
+var preFillValues = /* @__PURE__ */ new WeakMap();
 var _inputValueSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
 var _textareaValueSetter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set;
 var _checkedSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "checked")?.set;
+function normalizeAliasKey(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function addAlias(index, alias, schemaKey) {
+  if (!alias)
+    return;
+  const normalized = normalizeAliasKey(alias);
+  if (!normalized)
+    return;
+  if (!index.has(normalized))
+    index.set(normalized, /* @__PURE__ */ new Set());
+  index.get(normalized).add(schemaKey);
+}
+function buildAliasIndex(form, metadata) {
+  const index = /* @__PURE__ */ new Map();
+  const properties = metadata?.inputSchema?.properties ?? {};
+  for (const [schemaKey, prop] of Object.entries(properties)) {
+    addAlias(index, schemaKey, schemaKey);
+    addAlias(index, schemaKey.replace(/_/g, " "), schemaKey);
+    addAlias(index, prop.title, schemaKey);
+    const nativeEl = findNativeField(form, schemaKey);
+    const mappedEl = metadata?.fieldElements?.get(schemaKey);
+    const el = nativeEl ?? mappedEl ?? null;
+    if (!el)
+      continue;
+    const htmlEl = el;
+    addAlias(index, htmlEl.getAttribute("id"), schemaKey);
+    addAlias(index, htmlEl.getAttribute("name"), schemaKey);
+    addAlias(index, htmlEl.getAttribute("aria-label"), schemaKey);
+    addAlias(index, htmlEl.getAttribute("placeholder"), schemaKey);
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+      for (const label of Array.from(el.labels ?? [])) {
+        addAlias(index, label.textContent?.trim(), schemaKey);
+      }
+    }
+  }
+  return index;
+}
+function resolveParamsForSchema(form, params, metadata, config) {
+  const resolved = {};
+  const warnings = [];
+  const properties = metadata?.inputSchema?.properties ?? {};
+  const aliasEnabled = config.paramBinding.enableAliasResolution;
+  for (const [key, value] of Object.entries(params)) {
+    if (key in properties)
+      resolved[key] = value;
+  }
+  if (!aliasEnabled)
+    return { resolved, warnings };
+  const aliasIndex = buildAliasIndex(form, metadata);
+  for (const [rawKey, value] of Object.entries(params)) {
+    if (rawKey in properties)
+      continue;
+    const candidates = aliasIndex.get(normalizeAliasKey(rawKey));
+    if (!candidates || candidates.size !== 1)
+      continue;
+    const target = Array.from(candidates)[0];
+    if (!target || target in resolved)
+      continue;
+    resolved[target] = value;
+    warnings.push({
+      field: target,
+      type: "alias_resolved",
+      original: rawKey,
+      message: `resolved "${rawKey}" to schema field "${target}"`
+    });
+  }
+  return { resolved, warnings };
+}
+function collectInvalidFieldWarnings(form) {
+  const warnings = [];
+  const controls = Array.from(form.elements).filter(
+    (el) => el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement
+  );
+  for (const control of controls) {
+    if (!control.willValidate)
+      continue;
+    if (control.checkValidity())
+      continue;
+    const field = control.name || control.id || control.getAttribute("aria-label") || "unknown_field";
+    warnings.push({
+      field,
+      type: "blocked_submit",
+      message: control.validationMessage || `field "${field}" failed validation`
+    });
+  }
+  return warnings;
+}
+function captureCurrentValues(form) {
+  const result = {};
+  try {
+    const data = new FormData(form);
+    for (const [key, val] of data.entries()) {
+      if (result[key] !== void 0) {
+        const existing = result[key];
+        result[key] = Array.isArray(existing) ? [...existing, val] : [existing, val];
+      } else {
+        result[key] = val;
+      }
+    }
+  } catch {
+  }
+  return result;
+}
+function collectValidationErrors(form) {
+  const errors = [];
+  for (const control of Array.from(form.elements)) {
+    if (!(control instanceof HTMLInputElement) && !(control instanceof HTMLTextAreaElement) && !(control instanceof HTMLSelectElement))
+      continue;
+    if (!control.willValidate || control.checkValidity())
+      continue;
+    const field = control.name || control.id || control.getAttribute("aria-label") || "unknown_field";
+    const v = control.validity;
+    const constraint = v.valueMissing ? "valueMissing" : v.typeMismatch ? "typeMismatch" : v.patternMismatch ? "patternMismatch" : v.tooLong ? "tooLong" : v.tooShort ? "tooShort" : v.rangeUnderflow ? "rangeUnderflow" : v.rangeOverflow ? "rangeOverflow" : v.stepMismatch ? "stepMismatch" : v.customError ? "customError" : "badInput";
+    errors.push({ field, constraint, message: control.validationMessage || `field "${field}" failed validation` });
+  }
+  return errors;
+}
 function buildExecuteHandler(form, config, toolName, metadata) {
   if (metadata?.fieldElements) {
     formFieldElements.set(form, metadata.fieldElements);
@@ -1082,22 +1260,86 @@ function buildExecuteHandler(form, config, toolName, metadata) {
     }
     pendingFillWarnings.set(form, []);
     pendingWarnings.delete(form);
-    fillFormFields(form, params);
-    const missingNow = getMissingRequired(metadata, params);
+    const existingSnapshot = captureCurrentValues(form);
+    preFillValues.set(form, existingSnapshot);
+    const { resolved: resolvedParams, warnings: aliasWarnings } = resolveParamsForSchema(
+      form,
+      params,
+      metadata,
+      config
+    );
+    if (aliasWarnings.length > 0) {
+      pendingFillWarnings.set(form, [...pendingFillWarnings.get(form) ?? [], ...aliasWarnings]);
+    }
+    let paramsToFill = resolvedParams;
+    if (config.preserveExisting) {
+      const preserved = [];
+      paramsToFill = Object.fromEntries(
+        Object.entries(resolvedParams).filter(([key]) => {
+          const current = existingSnapshot[key];
+          const hasValue = current !== void 0 && current !== "" && current !== null;
+          if (hasValue) {
+            preserved.push({
+              field: key,
+              type: "not_filled",
+              message: `field "${key}" already has a value and preserveExisting is enabled`
+            });
+          }
+          return !hasValue;
+        })
+      );
+      if (preserved.length > 0) {
+        pendingFillWarnings.set(form, [...pendingFillWarnings.get(form) ?? [], ...preserved]);
+      }
+    }
+    fillFormFields(form, paramsToFill);
+    const missingNow = getMissingRequired(metadata, resolvedParams);
     if (missingNow.length > 0)
       pendingWarnings.set(form, missingNow);
     window.dispatchEvent(new CustomEvent("toolactivated", { detail: { toolName } }));
     return new Promise((resolve, reject) => {
-      pendingExecutions.set(form, { resolve, reject });
+      const timeoutMs = config.execution.timeoutMs;
+      const timeoutId = setTimeout(() => {
+        const pending = pendingExecutions.get(form);
+        if (!pending)
+          return;
+        pendingExecutions.delete(form);
+        const timedOutState = config.autoSubmit || form.hasAttribute("toolautosubmit") || form.dataset["webmcpAutosubmit"] !== void 0 ? "timed_out" : "awaiting_user_action";
+        const warn = {
+          field: "__form__",
+          type: "timeout",
+          message: timedOutState === "timed_out" ? `tool execution timed out after ${timeoutMs}ms` : `waiting for user submit (timed out after ${timeoutMs}ms)`
+        };
+        const _existingValsTimeout = preFillValues.get(form);
+        const structured = {
+          status: timedOutState,
+          filled_fields: serializeFormData(form, lastParams.get(form), formFieldElements.get(form)),
+          skipped_fields: [],
+          missing_required: pendingWarnings.get(form) ?? [],
+          warnings: [...pendingFillWarnings.get(form) ?? [], warn],
+          ..._existingValsTimeout !== void 0 && { existing_values: _existingValsTimeout }
+        };
+        pendingWarnings.delete(form);
+        pendingFillWarnings.delete(form);
+        lastFilledSnapshot.delete(form);
+        preFillValues.delete(form);
+        resolve({
+          content: [
+            { type: "text", text: warn.message },
+            { type: "text", text: JSON.stringify(structured) }
+          ]
+        });
+      }, timeoutMs);
+      pendingExecutions.set(form, { resolve, reject, timeoutId });
       if (config.autoSubmit || form.hasAttribute("toolautosubmit") || form.dataset["webmcpAutosubmit"] !== void 0) {
         waitForDomStable(form).then(async () => {
           try {
-            fillFormFields(form, params);
+            fillFormFields(form, resolvedParams);
             for (let attempt = 0; attempt < 2; attempt++) {
-              const reset = getResetFields(form, params, formFieldElements.get(form));
+              const reset = getResetFields(form, resolvedParams, formFieldElements.get(form));
               if (reset.length === 0)
                 break;
-              fillFormFields(form, params);
+              fillFormFields(form, resolvedParams);
               await waitForDomStable(form, 400, 100);
             }
             let submitForm = form;
@@ -1108,7 +1350,9 @@ function buildExecuteHandler(form, config, toolName, metadata) {
               const found = liveBtn?.closest("form");
               if (found) {
                 submitForm = found;
-                pendingExecutions.set(submitForm, { resolve, reject });
+                const pending = pendingExecutions.get(form);
+                const nextPending = pending?.timeoutId ? { resolve, reject, timeoutId: pending.timeoutId } : { resolve, reject };
+                pendingExecutions.set(submitForm, nextPending);
                 attachSubmitInterceptor(submitForm, toolName);
               }
             }
@@ -1116,6 +1360,43 @@ function buildExecuteHandler(form, config, toolName, metadata) {
               pendingWarnings.set(submitForm, pendingWarnings.get(form));
               pendingWarnings.delete(form);
             }
+            if (!submitForm.checkValidity()) {
+              const pending = pendingExecutions.get(submitForm) ?? pendingExecutions.get(form);
+              if (pending) {
+                if (pending.timeoutId)
+                  clearTimeout(pending.timeoutId);
+                pendingExecutions.delete(submitForm);
+                pendingExecutions.delete(form);
+                const warnings = [
+                  ...pendingFillWarnings.get(submitForm) ?? pendingFillWarnings.get(form) ?? [],
+                  ...collectInvalidFieldWarnings(submitForm)
+                ];
+                pendingFillWarnings.delete(submitForm);
+                pendingFillWarnings.delete(form);
+                const _existingValsBlocked = preFillValues.get(form);
+                const structured = {
+                  status: "blocked_invalid",
+                  filled_fields: serializeFormData(submitForm, lastParams.get(submitForm) ?? lastParams.get(form), formFieldElements.get(submitForm) ?? formFieldElements.get(form)),
+                  skipped_fields: [],
+                  missing_required: pendingWarnings.get(submitForm) ?? pendingWarnings.get(form) ?? [],
+                  warnings,
+                  validation_errors: collectValidationErrors(submitForm),
+                  ..._existingValsBlocked !== void 0 && { existing_values: _existingValsBlocked }
+                };
+                pendingWarnings.delete(submitForm);
+                pendingWarnings.delete(form);
+                lastFilledSnapshot.delete(submitForm);
+                lastFilledSnapshot.delete(form);
+                preFillValues.delete(form);
+                resolve({
+                  content: [
+                    { type: "text", text: "Form submission blocked by native validation." },
+                    { type: "text", text: JSON.stringify(structured) }
+                  ]
+                });
+              }
+              return;
+            }
             submitForm.requestSubmit();
           } catch (err) {
             reject(err instanceof Error ? err : new Error(String(err)));
@@ -1134,9 +1415,13 @@ function attachSubmitInterceptor(form, toolName) {
     if (!pending)
       return;
     const { resolve } = pending;
+    if (pending.timeoutId)
+      clearTimeout(pending.timeoutId);
     pendingExecutions.delete(form);
     const formData = serializeFormData(form, lastParams.get(form), formFieldElements.get(form));
+    const existingVals = preFillValues.get(form);
     lastFilledSnapshot.delete(form);
+    preFillValues.delete(form);
     const missingRequired = pendingWarnings.get(form) ?? [];
     pendingWarnings.delete(form);
     const fillWarnings = pendingFillWarnings.get(form) ?? [];
@@ -1154,7 +1439,8 @@ function attachSubmitInterceptor(form, toolName) {
           message: `required field "${f}" was not provided`
         })),
         ...fillWarnings
-      ]
+      ],
+      ...existingVals !== void 0 && { existing_values: existingVals }
     };
     const allWarnMessages = [
       ...missingRequired.length ? [`required fields were not filled: ${missingRequired.join(", ")}`] : [],
@@ -1176,6 +1462,7 @@ function attachSubmitInterceptor(form, toolName) {
   });
   form.addEventListener("reset", () => {
     lastFilledSnapshot.delete(form);
+    preFillValues.delete(form);
     window.dispatchEvent(new CustomEvent("toolcancel", { detail: { toolName } }));
   });
 }
@@ -1690,10 +1977,23 @@ function ensureUniqueToolName(baseName, excludeForm) {
   }
   return candidate;
 }
+function hasNativeDeclarativeTool(form) {
+  return form.getAttribute("toolname")?.trim().length ? true : false;
+}
 async function registerForm(form, config) {
   if (isExcluded(form, config))
     return;
   const previousName = getRegisteredToolName(form);
+  if (hasNativeDeclarativeTool(form) && config.declarativeMode !== "force") {
+    if (previousName) {
+      await unregisterFormTool(form);
+    }
+    if (config.debug) {
+      const mode = config.declarativeMode;
+      console.log(`[auto-webmcp] Skipping imperative registration for native declarative form (mode=${mode})`);
+    }
+    return;
+  }
   let override;
   for (const [selector, ovr] of Object.entries(config.overrides)) {
     try {