@nxisai/nxis 2.1.2 → 2.2.2

package/src/webmcp/contract.ts

@@ -0,0 +1,168 @@
+/**
+ * Wire-shape types matching the backend JsonLdEmitter output.
+ *
+ * These types describe the JSON-LD that NxisAI's Action Specialist emits
+ * into `<script type="application/ld+json">` blocks. They are the single
+ * source of truth for the frontend consumer — any change here is a
+ * versioned contract change.
+ *
+ * @see JsonLdEmitter.scala in nxis-autofill-runner
+ * @internal
+ */
+
+// ---------------------------------------------------------------------------
+// Value types — closed set derived from HTML input[type]
+// ---------------------------------------------------------------------------
+
+/** The closed set of inferred value types emitted by the backend. */
+export type NxisValueType =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "date"
+  | "file";
+
+// ---------------------------------------------------------------------------
+// PropertyValueSpecification
+// ---------------------------------------------------------------------------
+
+/** A single option value for select/radio fields. */
+export interface NxisValueOption {
+  "@type": "nxis:ValueOption";
+  value: string;
+  /** Human-readable label. Absent when label === value. */
+  name?: string;
+}
+
+/**
+ * Mirrors schema.org PropertyValueSpecification + nxis extensions.
+ *
+ * Every field is an inferred descriptor — the consumer verifies
+ * against the live DOM control.
+ */
+export interface NxisPropertyValueSpecification {
+  "@type": "PropertyValueSpecification";
+  /** REQUIRED — property key, maps to form control `name`. */
+  valueName: string;
+  /** REQUIRED — inferred from HTML input[type]; consumer verifies against DOM. */
+  "nxis:valueType": NxisValueType;
+  /** Human-readable description (from label or placeholder). */
+  description?: string;
+  /** Inferred from HTML `required` attribute. */
+  valueRequired?: boolean;
+  /** Inferred from HTML `value` attribute. */
+  defaultValue?: string;
+  /** Inferred from HTML `minlength`. */
+  valueMinLength?: number;
+  /** Inferred from HTML `maxlength`. */
+  valueMaxLength?: number;
+  /** Inferred from HTML `min`. */
+  minValue?: number;
+  /** Inferred from HTML `max`. */
+  maxValue?: number;
+  /** Inferred from HTML `step`. */
+  stepValue?: number;
+  /** Inferred from HTML `pattern` — emitted UNANCHORED; consumer anchors with ^…$. */
+  valuePattern?: string;
+  /** Inferred from HTML `multiple`. */
+  multipleValues?: boolean;
+  /** Inferred from HTML `readonly`. */
+  readonlyValue?: boolean;
+  /** REQUIRED for select/radio — actual option values from DOM. */
+  "nxis:valueOption"?: NxisValueOption[];
+}
+
+// ---------------------------------------------------------------------------
+// EntryPoint — carries the SubmitTarget discriminator in the JSON-LD shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirrors schema.org EntryPoint + nxis extensions.
+ *
+ * The backend's `SubmitTarget` discriminator is expressed as:
+ * - `urlTemplate` present → Url target (real server endpoint)
+ * - `nxis:targetKind` present → endpointless (SelfPage or ClientSide)
+ *
+ * These are mutually exclusive in the emitted JSON-LD.
+ */
+export interface NxisEntryPoint {
+  "@type": "EntryPoint";
+  /** Form method (GET or POST), uppercase. */
+  httpMethod: string;
+  /** Form enctype (e.g., "application/x-www-form-urlencoded"). */
+  encodingType?: string;
+
+  // --- URL target (SubmitTarget.Url) ---
+  /** Real, resolvable server endpoint. May include RFC 6570 template vars for GET. */
+  urlTemplate?: string;
+
+  // --- Endpointless target (SubmitTarget.SelfPage / ClientSide) ---
+  /** Discriminator for endpointless forms. */
+  "nxis:targetKind"?: "selfPage" | "clientSide";
+  /** Page URL for staleness checking. */
+  "nxis:pageUrl"?: string;
+  /** Evidence that a JS submit/click listener exists on the form. */
+  "nxis:jsHandled"?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Action — the top-level entity
+// ---------------------------------------------------------------------------
+
+/**
+ * A schema.org Action node as emitted by the backend JsonLdEmitter.
+ *
+ * Found in `<script type="application/ld+json">` blocks, either standalone
+ * or nested within a `@graph` array alongside other schema.org types.
+ */
+export interface NxisAction {
+  "@context": unknown;
+  /** Action or a subtype (e.g., "SearchAction", "CommunicateAction"). */
+  "@type": string;
+  /** Provenance/identity URN. NOT a DOM locator. */
+  "@id": string;
+  /** Human-readable action name (becomes the tool name). */
+  name: string;
+  /** Human-readable action description (becomes the tool description). */
+  description: string;
+  /** EntryPoint describing how to invoke the action. */
+  target: NxisEntryPoint;
+  /** Inferred field descriptors (may be empty for actions with no inputs). */
+  input?: NxisPropertyValueSpecification[];
+  /** Crawl timestamp — consumer uses to assess staleness. */
+  "nxis:extractedAt"?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Known Action subtypes
+// ---------------------------------------------------------------------------
+
+/** The set of Action subtypes the backend classifier emits. */
+export const ACTION_SUBTYPES = [
+  "AskAction",
+  "SearchAction",
+  "SubscribeAction",
+  "RegisterAction",
+  "BuyAction",
+  "OrderAction",
+  "AddAction",
+  "ScheduleAction",
+  "ReserveAction",
+  "RsvpAction",
+  "ApplyAction",
+  "QuoteAction",
+  "DownloadAction",
+  "ReviewAction",
+  "CommentAction",
+  "TrackAction",
+  "CommunicateAction",
+  "InteractAction",
+] as const;
+
+export type ActionSubtype = typeof ACTION_SUBTYPES[number];
+
+/** Check if a string is a known Action subtype. */
+export function isActionType(type: string): type is ActionSubtype {
+  return (ACTION_SUBTYPES as readonly string[]).includes(type);
+}

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;
+}