@nxisai/nxis 2.1.2 → 2.2.1

package/src/webmcp/execute.ts

@@ -0,0 +1,514 @@
+/**
+ * Execute — fills a located form with the provided arguments and submits it.
+ *
+ * Dispatches `input` and `change` events to trigger framework reactivity,
+ * then submits the form via `requestSubmit()` (respects validation and
+ * submit event handlers).
+ *
+ * Returns a structured JSON result with a `success` flag and actionable
+ * `message` so the agent can self-correct on failure.
+ *
+ * @internal
+ */
+
+import { NxisAction } from './contract';
+import { locateForm } from './locate';
+import { reconcileFields, ReconciledField } from './reconcile';
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+/** Result of executing an action fill. */
+interface FillResult {
+  /** Whether the fill was meaningful (at least one field filled, no fatal errors). */
+  success: boolean;
+  /** Whether the form was submitted after filling. */
+  submitted: boolean;
+  /** Human-readable summary for agent self-correction. */
+  message: string;
+  /** Fields that were successfully filled. */
+  filled: string[];
+  /** Fields that were skipped (with actionable reasons). */
+  skipped: Array<{ field: string; reason: string }>;
+  /** True when the action was extracted from a different page than the current one. */
+  stale?: boolean;
+}
+
+/** Internal fill outcome for a single field. */
+type FieldFillOutcome =
+  | { ok: true }
+  | { ok: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a form fill action.
+ *
+ * Locates the form, reconciles fields, fills values, dispatches events,
+ * waits for framework reactivity to settle, then verifies values persisted.
+ *
+ * @param action - The NxisAction describing the form.
+ * @param args - The argument values to fill, keyed by valueName.
+ * @returns A JSON string describing the fill result.
+ */
+export async function executeAction(
+  action: NxisAction,
+  args: Record<string, unknown>
+): Promise<string> {
+  // Step 0: Staleness — the action records the page it was extracted from.
+  // If the live page differs, the form may have moved or changed; surface a
+  // non-fatal warning so the agent can weigh the result.
+  const staleWarning = checkStaleness(action);
+
+  // Step 1: Locate the form
+  const form = locateForm(action);
+
+  if (!form) {
+    const base = `Form not found for action "${action.name}". The page may have changed since the tool was registered.`;
+    const result: FillResult = {
+      success: false,
+      submitted: false,
+      message: staleWarning ? `Warning: ${staleWarning} ${base}` : base,
+      filled: [],
+      skipped: [],
+    };
+    if (staleWarning) {
+      result.stale = true;
+    }
+    return JSON.stringify(result);
+  }
+
+  // Step 2: Reconcile fields
+  const reconciled = reconcileFields(action, form);
+  const specs = action.input ?? [];
+
+  // Step 3: Check for missing required fields
+  const filled: string[] = [];
+  const skipped: Array<{ field: string; reason: string }> = [];
+  // Tracks whether a required field went unfilled — drives the submit gate
+  // below. Kept as structured state rather than re-parsing skip messages.
+  let requiredMissing = false;
+
+  for (const pvs of specs) {
+    if (pvs.valueRequired && (args[pvs.valueName] === undefined || args[pvs.valueName] === null)) {
+      requiredMissing = true;
+      skipped.push({
+        field: pvs.valueName,
+        reason: `Required field '${pvs.valueName}' was not provided. Expected type: ${pvs['nxis:valueType']}.`,
+      });
+    }
+  }
+
+  // Step 4: Fill each reconciled field
+  for (const field of reconciled) {
+    const argValue = args[field.valueName];
+
+    if (argValue === undefined || argValue === null) {
+      // Already reported in required-field check above if required;
+      // for optional fields, note it but don't treat as error
+      if (!skipped.some(s => s.field === field.valueName)) {
+        skipped.push({ field: field.valueName, reason: 'No value provided (optional field).' });
+      }
+      continue;
+    }
+
+    const outcome = fillField(field, argValue);
+    if (outcome.ok === false) {
+      skipped.push({ field: field.valueName, reason: outcome.reason });
+    } else {
+      filled.push(field.valueName);
+    }
+  }
+
+  // Step 5: Settle — yield to the microtask queue so frameworks (React, Vue,
+  // Angular) can process the dispatched input/change events before we verify.
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // Step 6: Verify — spot-check that filled values actually persisted.
+  // Frameworks may revert values (e.g., controlled components in React).
+  // Only the single-value text path is verifiable this way; radio/checkbox/
+  // select strategies resolve to a DOM-constrained value and aren't compared.
+  for (const field of reconciled) {
+    if (field.strategy.kind === 'value' && filled.includes(field.valueName)) {
+      const el = field.strategy.element;
+      const expected = valueToString(args[field.valueName] ?? '');
+      if (el.value !== expected) {
+        skipped.push({
+          field: field.valueName,
+          reason: `Value was set to "${expected}" but the DOM now shows "${el.value}". A framework may have reverted it.`,
+        });
+        filled.splice(filled.indexOf(field.valueName), 1);
+      }
+    }
+  }
+
+  // Step 7: Submit the form if fill was successful
+  const canSubmit = filled.length > 0 && !requiredMissing;
+  let submitted = false;
+
+  if (canSubmit) {
+    submitted = submitForm(form);
+  }
+
+  // Step 8: Build result
+  const result: FillResult = {
+    success: canSubmit,
+    submitted,
+    message: buildResultMessage(filled, skipped, submitted, staleWarning),
+    filled,
+    skipped,
+  };
+  if (staleWarning) {
+    result.stale = true;
+  }
+
+  return JSON.stringify(result);
+}
+
+// ---------------------------------------------------------------------------
+// Internal — result message
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a human-readable result message from the fill/skip arrays.
+ */
+function buildResultMessage(
+  filled: string[],
+  skipped: Array<{ field: string; reason: string }>,
+  submitted: boolean,
+  staleWarning: string | null
+): string {
+  const parts: string[] = [];
+  if (staleWarning) {
+    parts.push(`Warning: ${staleWarning}`);
+  }
+
+  if (filled.length === 0 && skipped.length === 0) {
+    parts.push('No fields were filled. Verify field names match the input schema.');
+    return parts.join(' ');
+  }
+
+  if (filled.length > 0) {
+    parts.push(`Filled ${filled.length} field(s): ${filled.join(', ')}.`);
+  }
+
+  if (skipped.length > 0) {
+    const skipDetails = skipped
+      .map(s => `${s.field} (${s.reason})`)
+      .join('; ');
+    parts.push(`Skipped ${skipped.length}: ${skipDetails}`);
+  }
+
+  if (submitted) {
+    parts.push('Form submitted.');
+  } else if (filled.length > 0) {
+    parts.push('Form was NOT submitted due to missing required fields or fill errors.');
+  }
+
+  return parts.join(' ');
+}
+
+// ---------------------------------------------------------------------------
+// Internal — form submission
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit the form using requestSubmit() which, unlike form.submit():
+ * - Fires the 'submit' event (so JS handlers run)
+ * - Runs HTML5 constraint validation
+ * - Respects the form's action/method attributes
+ *
+ * Falls back to form.submit() if requestSubmit is unavailable.
+ *
+ * @returns `true` if submission was triggered without error.
+ */
+function submitForm(form: HTMLFormElement): boolean {
+  try {
+    if (typeof form.requestSubmit === 'function') {
+      form.requestSubmit();
+    } else {
+      form.submit();
+    }
+    return true;
+  } catch (err) {
+    console.warn('[nxis/webmcp] Form submission failed:', err);
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal — fill logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Fill a single reconciled field with a value.
+ * Returns an outcome with an actionable reason on failure.
+ */
+function fillField(field: ReconciledField, value: unknown): FieldFillOutcome {
+  const { strategy } = field;
+
+  switch (strategy.kind) {
+    case 'skip':
+      return { ok: false, reason: strategy.reason };
+
+    case 'value':
+      return fillValue(strategy.element, valueToString(value));
+
+    case 'checked':
+      return fillChecked(strategy.element, value);
+
+    case 'radio':
+      return fillRadio(strategy.elements, value);
+
+    case 'checkboxGroup':
+      return fillCheckboxGroup(strategy.elements, value);
+
+    case 'select':
+      return fillSelect(strategy.element, String(value), strategy.allowedValues);
+
+    case 'multiSelect':
+      return fillMultiSelect(strategy.element, value, strategy.allowedValues);
+
+    default:
+      return { ok: false, reason: `Unsupported fill strategy for field "${field.valueName}".` };
+  }
+}
+
+/**
+ * Stringify a fill value. Arrays (from `multipleValues` fields backed by a
+ * plain control, e.g. `<input type="email" multiple>`) join comma-separated.
+ */
+function valueToString(value: unknown): string {
+  if (Array.isArray(value)) {
+    return value.map(v => String(v)).join(',');
+  }
+  return String(value);
+}
+
+/**
+ * Set .value on an input/textarea and dispatch events.
+ */
+function fillValue(element: HTMLInputElement | HTMLTextAreaElement, value: string): FieldFillOutcome {
+  // Use the native setter to bypass framework interceptors
+  const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+    element instanceof HTMLTextAreaElement
+      ? HTMLTextAreaElement.prototype
+      : HTMLInputElement.prototype,
+    'value'
+  )?.set;
+
+  if (nativeInputValueSetter) {
+    nativeInputValueSetter.call(element, value);
+  } else {
+    element.value = value;
+  }
+
+  element.dispatchEvent(new Event('input', { bubbles: true }));
+  element.dispatchEvent(new Event('change', { bubbles: true }));
+  return { ok: true };
+}
+
+/**
+ * Toggle a single checkbox and dispatch change event.
+ */
+function fillChecked(element: HTMLInputElement, value: unknown): FieldFillOutcome {
+  element.checked = toBoolean(value);
+  element.dispatchEvent(new Event('change', { bubbles: true }));
+  return { ok: true };
+}
+
+/**
+ * Select the member of a radio group whose value matches. Matching tries the
+ * exact value, then case-insensitive value, then the visible label — LLMs
+ * often send the human-readable label instead of the machine value.
+ */
+function fillRadio(elements: HTMLInputElement[], value: unknown): FieldFillOutcome {
+  const target = String(value);
+  const match =
+    elements.find(el => el.value === target) ??
+    elements.find(el => el.value.toLowerCase() === target.toLowerCase()) ??
+    elements.find(el => radioLabel(el).toLowerCase() === target.toLowerCase());
+
+  if (!match) {
+    const allowed = elements.map(el => el.value).join(', ');
+    return {
+      ok: false,
+      reason: `Value "${target}" is not an allowed option for radio "${elements[0].name}". Allowed: [${allowed}].`,
+    };
+  }
+
+  match.checked = true;
+  match.dispatchEvent(new Event('input', { bubbles: true }));
+  match.dispatchEvent(new Event('change', { bubbles: true }));
+  return { ok: true };
+}
+
+/**
+ * Check the members of a checkbox group named by the given value(s); uncheck
+ * the rest. Accepts a single value or an array of values.
+ */
+function fillCheckboxGroup(elements: HTMLInputElement[], value: unknown): FieldFillOutcome {
+  const wanted = (Array.isArray(value) ? value : [value]).map(v => String(v));
+  const wantedLower = wanted.map(w => w.toLowerCase());
+
+  let matchedAny = false;
+  for (const el of elements) {
+    const selected =
+      wanted.includes(el.value) || wantedLower.includes(el.value.toLowerCase());
+    el.checked = selected;
+    if (selected) matchedAny = true;
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+
+  if (!matchedAny) {
+    const allowed = elements.map(el => el.value).join(', ');
+    return {
+      ok: false,
+      reason: `None of [${wanted.join(', ')}] match checkbox group "${elements[0].name}". Allowed: [${allowed}].`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Set .value on a single-select <select> from allowed options.
+ * Constrains to actual <option> values regardless of what the Action claimed.
+ */
+function fillSelect(
+  element: HTMLSelectElement,
+  value: string,
+  allowedValues: string[]
+): FieldFillOutcome {
+  const resolved = resolveOption(element, value, allowedValues);
+  if (resolved === null) {
+    return {
+      ok: false,
+      reason: `Value "${value}" is not an allowed option for "${element.name}". Allowed: [${allowedValues.join(', ')}].`,
+    };
+  }
+
+  element.value = resolved;
+  element.dispatchEvent(new Event('input', { bubbles: true }));
+  element.dispatchEvent(new Event('change', { bubbles: true }));
+  return { ok: true };
+}
+
+/**
+ * Select one or more options on a <select multiple>. Accepts a single value or
+ * an array; succeeds if at least one value resolves to a real option.
+ */
+function fillMultiSelect(
+  element: HTMLSelectElement,
+  value: unknown,
+  allowedValues: string[]
+): FieldFillOutcome {
+  const requested = (Array.isArray(value) ? value : [value]).map(v => String(v));
+  const resolved = new Set<string>();
+  const unmatched: string[] = [];
+
+  for (const v of requested) {
+    const match = resolveOption(element, v, allowedValues);
+    if (match === null) {
+      unmatched.push(v);
+    } else {
+      resolved.add(match);
+    }
+  }
+
+  if (resolved.size === 0) {
+    return {
+      ok: false,
+      reason: `None of [${requested.join(', ')}] are allowed options for "${element.name}". Allowed: [${allowedValues.join(', ')}].`,
+    };
+  }
+
+  for (const option of Array.from(element.options)) {
+    option.selected = resolved.has(option.value);
+  }
+  element.dispatchEvent(new Event('input', { bubbles: true }));
+  element.dispatchEvent(new Event('change', { bubbles: true }));
+
+  if (unmatched.length > 0) {
+    return {
+      ok: false,
+      reason: `Selected [${Array.from(resolved).join(', ')}] but [${unmatched.join(', ')}] are not allowed options for "${element.name}". Allowed: [${allowedValues.join(', ')}].`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Resolve a requested value to a real <option> value: exact, then
+ * case-insensitive, then by visible option text. Returns null if no match.
+ */
+function resolveOption(
+  element: HTMLSelectElement,
+  value: string,
+  allowedValues: string[]
+): string | null {
+  if (allowedValues.includes(value)) return value;
+
+  const ci = allowedValues.find(v => v.toLowerCase() === value.toLowerCase());
+  if (ci) return ci;
+
+  // LLMs often send the human-readable label instead of the machine value,
+  // e.g. "AI Summit 2026" instead of "ai-summit-2026".
+  for (const option of Array.from(element.options)) {
+    if (option.text.toLowerCase() === value.toLowerCase()) {
+      return option.value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Coerce a JSON value to a checkbox boolean. Mirrors how an agent might encode
+ * "off": false, "false", "0", "" and null/undefined all read as unchecked.
+ */
+function toBoolean(value: unknown): boolean {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  if (typeof value === 'string') {
+    const v = value.trim().toLowerCase();
+    return v !== '' && v !== 'false' && v !== '0' && v !== 'off' && v !== 'no';
+  }
+  return Boolean(value);
+}
+
+/**
+ * Best-effort visible label for a radio input — its associated <label> text,
+ * falling back to the value. Used to match agent-supplied human labels.
+ */
+function radioLabel(el: HTMLInputElement): string {
+  if (el.labels && el.labels.length > 0) {
+    return (el.labels[0].textContent ?? '').trim();
+  }
+  return el.value;
+}
+
+/**
+ * Compare the action's recorded extraction page against the live location.
+ * Returns a warning string when they differ (origin or path), else null.
+ */
+function checkStaleness(action: NxisAction): string | null {
+  const pageUrl = action.target['nxis:pageUrl'];
+  if (!pageUrl) return null;
+
+  try {
+    const recorded = new URL(pageUrl);
+    const current = new URL(window.location.href);
+    if (recorded.origin !== current.origin || recorded.pathname !== current.pathname) {
+      return (
+        `Action "${action.name}" was extracted from ${recorded.origin}${recorded.pathname} ` +
+        `but the current page is ${current.origin}${current.pathname}. ` +
+        `The form may have moved or changed.`
+      );
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}

package/src/webmcp/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @packageDocumentation
+ *
+ * `nxis/webmcp` — WebMCP tool registration for NxisAI structured data.
+ *
+ * @remarks
+ * This subpath export reads Action + EntryPoint JSON-LD injected by the
+ * NxisAI backend and registers each Action as a WebMCP tool via
+ * `document.modelContext.registerTool`. Each tool's `execute` locates the
+ * real `<form>` on the live page and fills it.
+ *
+ * **Browser-only.** This module requires `document.modelContext` (Chrome 149+).
+ * It gracefully no-ops in environments where WebMCP is unavailable.
+ *
+ * @example
+ * ```typescript
+ * import { registerActions } from 'nxis/webmcp';
+ *
+ * // Auto-register all Action tools found in the page's JSON-LD
+ * const cleanup = registerActions();
+ *
+ * // Later, to unregister all tools:
+ * cleanup();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Opt-out of MutationObserver re-scan for SPAs
+ * const cleanup = registerActions({ observe: false });
+ * ```
+ */
+
+export { registerActions } from './register';
+export type { RegisterOptions } from './register';
+
+// Re-export contract types for consumers who need them
+export type {
+  NxisAction,
+  NxisEntryPoint,
+  NxisPropertyValueSpecification,
+  NxisValueOption,
+  NxisValueType,
+  ActionSubtype,
+} from './contract';
+export { isActionType, ACTION_SUBTYPES } from './contract';
+
+// Re-export parse for advanced usage
+export { readActions } from './parse';
+
+// Re-export schema for testing / advanced usage
+export { buildInputSchema } from './schema';