@nxisai/nxis 2.1.2 → 2.2.2

package/src/webmcp/register.ts

@@ -0,0 +1,285 @@
+/**
+ * Tool registration — registers NxisActions as WebMCP tools.
+ *
+ * Ensures WebMCP availability via @nxisai/webmcp polyfill (no-ops when
+ * a native implementation exists, e.g. Chrome 149+).
+ *
+ * Uses `document.modelContext` (canonical, Chrome 150+) with
+ * `navigator.modelContext` fallback for older builds.
+ *
+ * @internal
+ */
+
+import './types'; // Augment Document/Navigator with modelContext
+import { installWebMCPPolyfill } from '@nxisai/webmcp';
+import { NxisAction } from './contract';
+import { readActions } from './parse';
+import { buildInputSchema } from './schema';
+import { executeAction } from './execute';
+import type { ModelContext } from './types';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RegisterOptions {
+  /** Document to scan for JSON-LD blocks. Defaults to `document`. */
+  doc?: Document;
+  /** AbortSignal to externally cancel all registrations. */
+  signal?: AbortSignal;
+  /** Enable MutationObserver re-scan for SPAs. Defaults to `true` (opt-out). */
+  observe?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse all Action JSON-LD from the page and register each as a WebMCP tool.
+ *
+ * Automatically installs the @nxisai/webmcp polyfill on browsers without
+ * native WebMCP support. The polyfill is a no-op when `document.modelContext`
+ * already exists (Chrome 149+).
+ *
+ * @param options - Configuration options.
+ * @returns A cleanup function that unregisters all tools and disconnects observers.
+ */
+export function registerActions(options?: RegisterOptions): () => void {
+  const observe = options?.observe !== false; // opt-out: default true
+
+  // Browser-only — no-op gracefully when there's no DOM (SSR, Node, workers).
+  const doc = options?.doc ?? (typeof document !== 'undefined' ? document : undefined);
+  if (!doc) {
+    console.warn(
+      '[nxis/webmcp] No document available (not running in a browser). ' +
+      'Tools will not be registered.'
+    );
+    return () => { };
+  }
+
+  // Ensure WebMCP API is available — polyfill no-ops on Chrome 149+
+  installWebMCPPolyfill();
+
+  // Resolve the ModelContext from the SAME document we parse, so a custom
+  // `doc` (e.g. an iframe) registers its tools on the right context.
+  const modelContext = getModelContext(doc);
+  if (!modelContext) {
+    console.warn(
+      '[nxis/webmcp] WebMCP API not available — document.modelContext is undefined. ' +
+      'Tools will not be registered.'
+    );
+    return () => { };
+  }
+
+  const controller = new AbortController();
+
+  // Link external signal to our controller
+  if (options?.signal) {
+    if (options.signal.aborted) {
+      controller.abort();
+    } else {
+      options.signal.addEventListener('abort', () => controller.abort());
+    }
+  }
+
+  // Registry shared across the initial scan and observer re-scans.
+  const registry: Registry = {
+    ids: new Set<string>(),
+    names: new Set<string>(),
+  };
+
+  // Initial registration
+  registerFromDocument(doc, modelContext, controller, registry);
+
+  // SPA re-scan via MutationObserver (always-on, opt-out via observe: false)
+  let observer: MutationObserver | null = null;
+  if (observe) {
+    observer = createObserver(doc, modelContext, controller, registry);
+  }
+
+  // Return cleanup function
+  return () => {
+    controller.abort();
+    if (observer) {
+      observer.disconnect();
+      observer = null;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+/** De-dupe state shared across the initial scan and observer re-scans. */
+interface Registry {
+  /** Action @ids already registered — prevents re-registering the same action. */
+  ids: Set<string>;
+  /** Tool names already taken — prevents distinct actions colliding on a name. */
+  names: Set<string>;
+}
+
+/**
+ * Resolve the ModelContext for a given document using Chrome team's
+ * recommended feature-detection. `doc.modelContext` is canonical (Chrome 150+);
+ * `navigator.modelContext` (from the document's own window) is the deprecated
+ * fallback.
+ */
+function getModelContext(doc: Document): ModelContext | null {
+  const nav = doc.defaultView?.navigator ??
+    (typeof navigator !== 'undefined' ? navigator : undefined);
+  return doc.modelContext || nav?.modelContext || null;
+}
+
+/**
+ * Register tools for all Action specs found in the document.
+ */
+function registerFromDocument(
+  doc: Document,
+  modelContext: ModelContext,
+  controller: AbortController,
+  registry: Registry
+): void {
+  const actions = readActions(doc);
+
+  let registeredThisPass = 0;
+  for (const action of actions) {
+    // De-dupe by @id
+    if (registry.ids.has(action['@id'])) continue;
+
+    try {
+      registerSingleAction(action, modelContext, controller, registry);
+      registry.ids.add(action['@id']);
+      registeredThisPass++;
+    } catch (err) {
+      console.warn(
+        `[nxis/webmcp] Failed to register tool for action "${action.name}":`,
+        err
+      );
+    }
+  }
+
+  if (registeredThisPass > 0) {
+    console.info(
+      `[nxis/webmcp] Registered ${registeredThisPass} tool(s) ` +
+      `(${registry.ids.size} total) from ${actions.length} action(s).`
+    );
+  }
+}
+
+/**
+ * Register a single NxisAction as a WebMCP tool.
+ */
+function registerSingleAction(
+  action: NxisAction,
+  modelContext: ModelContext,
+  controller: AbortController,
+  registry: Registry
+): void {
+  const inputSchema = buildInputSchema(action);
+  const name = uniqueToolName(sanitizeToolName(action.name), registry.names);
+
+  modelContext.registerTool(
+    {
+      name,
+      description: action.description,
+      inputSchema,
+      annotations: {
+        readOnlyHint: false,
+        untrustedContentHint: true,
+      },
+      execute: async (args: Record<string, unknown>) => {
+        return executeAction(action, args);
+      },
+    },
+    { signal: controller.signal },
+  );
+
+  // Reserve the name only after a successful registration, so a failed
+  // registerTool doesn't consume the base name and push the next action to a suffix.
+  registry.names.add(name);
+}
+
+/**
+ * Create a MutationObserver that watches the whole document for new JSON-LD
+ * insertions. SPAs inject structured data into <body>, framework roots, or
+ * inside wrapper elements — not just <head> — so we observe the document
+ * subtree and detect scripts added either directly or as descendants.
+ * On mutation, re-registers any new actions (de-duped by @id).
+ */
+function createObserver(
+  doc: Document,
+  modelContext: ModelContext,
+  controller: AbortController,
+  registry: Registry
+): MutationObserver {
+  const observer = new MutationObserver((mutations) => {
+    if (mutationsAddJsonLd(mutations)) {
+      registerFromDocument(doc, modelContext, controller, registry);
+    }
+  });
+
+  // Stop observing when the registration is torn down.
+  controller.signal.addEventListener('abort', () => observer.disconnect());
+
+  observer.observe(doc.documentElement, {
+    childList: true,
+    subtree: true,
+  });
+
+  return observer;
+}
+
+/** True if any mutation added a JSON-LD script, directly or nested. */
+function mutationsAddJsonLd(mutations: MutationRecord[]): boolean {
+  for (const mutation of mutations) {
+    for (const node of Array.from(mutation.addedNodes)) {
+      if (isJsonLdScript(node)) return true;
+      // A wrapper element may carry JSON-LD scripts as descendants.
+      if (
+        node instanceof Element &&
+        node.querySelector('script[type="application/ld+json"]')
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** True if the node is itself a JSON-LD script element. */
+function isJsonLdScript(node: Node): boolean {
+  return node instanceof HTMLScriptElement && node.type === 'application/ld+json';
+}
+
+/**
+ * Sanitize an action name to a valid snake_case tool name.
+ * Converts hyphens and spaces to underscores, strips invalid chars.
+ * WebMCP tool names: [a-z0-9_], max 64 chars.
+ */
+function sanitizeToolName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[\s-]+/g, '_')
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '')
+    .slice(0, 64) || 'unnamed_action';
+}
+
+/**
+ * Ensure a tool name is unique within the document. Distinct actions whose
+ * names sanitize to the same string get a numeric suffix (`_2`, `_3`, …)
+ * rather than silently overwriting one another. The suffix is kept within the
+ * 64-char tool-name limit.
+ */
+function uniqueToolName(base: string, taken: Set<string>): string {
+  if (!taken.has(base)) return base;
+
+  for (let i = 2; ; i++) {
+    const suffix = `_${i}`;
+    const candidate = base.slice(0, 64 - suffix.length) + suffix;
+    if (!taken.has(candidate)) return candidate;
+  }
+}

package/src/webmcp/schema.ts

@@ -0,0 +1,201 @@
+/**
+ * Schema transform — converts NxisAction PVS descriptors to JSON Schema
+ * for the WebMCP `registerTool` inputSchema.
+ *
+ * Pure function, no DOM access.
+ *
+ * Mapping rules (from implementation plan):
+ *   - valueName → property key
+ *   - nxis:valueType → JSON Schema "type" (date/file → "string")
+ *   - valueRequired → sibling "required" array (not per-property keyword)
+ *   - valuePattern → anchored with ^…$ (emitted unanchored by producer)
+ *   - multipleValues → nests into { type: "array", items: { ... } }
+ *   - nxis:valueOption → "enum" or "oneOf" with { const, title }
+ *   - defaultValue → "default"
+ *   - description → "description"
+ *   - valueMinLength/valueMaxLength → minLength/maxLength
+ *   - minValue/maxValue → minimum/maximum
+ *   - stepValue → multipleOf
+ *   - readonlyValue → readOnly: true
+ *
+ * @internal
+ */
+
+import { NxisAction, NxisPropertyValueSpecification, NxisValueType } from './contract';
+
+/** JSON Schema type mapping from nxis:valueType. */
+function jsonSchemaType(vt: NxisValueType): string {
+  switch (vt) {
+    case 'string':  return 'string';
+    case 'number':  return 'number';
+    case 'integer': return 'integer';
+    case 'boolean': return 'boolean';
+    case 'date':    return 'string'; // ISO date string
+    case 'file':    return 'string'; // file path/name as string
+    default:        return 'string';
+  }
+}
+
+/** JSON Schema format for types that have standard formats. */
+function jsonSchemaFormat(vt: NxisValueType): string | undefined {
+  switch (vt) {
+    case 'date': return 'date'; // ISO 8601 (YYYY-MM-DD)
+    default:     return undefined;
+  }
+}
+
+/**
+ * Build a JSON Schema object for the Action's input parameters.
+ *
+ * @param action - The parsed Action to transform.
+ * @returns A JSON Schema `{ type: "object", properties: { ... }, required: [...] }`.
+ */
+export function buildInputSchema(action: NxisAction): Record<string, unknown> {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required: string[] = [];
+  const specs = action.input ?? [];
+
+  for (const pvs of specs) {
+    const prop = buildPropertySchema(pvs);
+
+    if (pvs.multipleValues) {
+      // Wrap in array schema
+      const arrayProp: Record<string, unknown> = {
+        type: 'array',
+        items: prop,
+      };
+      // Move minLength/maxLength to minItems/maxItems on the array
+      if (pvs.valueMinLength !== undefined) {
+        arrayProp.minItems = pvs.valueMinLength;
+        delete prop.minLength;
+      }
+      if (pvs.valueMaxLength !== undefined) {
+        arrayProp.maxItems = pvs.valueMaxLength;
+        delete prop.maxLength;
+      }
+      // Preserve description on the array level only (avoid duplicating it on
+      // both the array and its items).
+      if (pvs.description) {
+        arrayProp.description = pvs.description;
+        delete prop.description;
+      }
+      properties[pvs.valueName] = arrayProp;
+    } else {
+      properties[pvs.valueName] = prop;
+    }
+
+    // valueRequired relocates to the sibling required array
+    if (pvs.valueRequired) {
+      required.push(pvs.valueName);
+    }
+  }
+
+  const schema: Record<string, unknown> = {
+    type: 'object',
+    properties,
+  };
+
+  if (required.length > 0) {
+    schema.required = required;
+  }
+
+  return schema;
+}
+
+/**
+ * Build a single property schema from a PVS descriptor.
+ */
+function buildPropertySchema(pvs: NxisPropertyValueSpecification): Record<string, unknown> {
+  const prop: Record<string, unknown> = {
+    type: jsonSchemaType(pvs['nxis:valueType']),
+  };
+
+  // Format hint for date/email fields
+  const format = jsonSchemaFormat(pvs['nxis:valueType']);
+  if (format) {
+    prop.format = format;
+  }
+
+  // Description
+  if (pvs.description) {
+    prop.description = pvs.description;
+  }
+
+  // Default value
+  if (pvs.defaultValue !== undefined) {
+    prop.default = coerceDefault(pvs.defaultValue, pvs['nxis:valueType']);
+  }
+
+  // String constraints
+  if (pvs.valueMinLength !== undefined) {
+    prop.minLength = pvs.valueMinLength;
+  }
+  if (pvs.valueMaxLength !== undefined) {
+    prop.maxLength = pvs.valueMaxLength;
+  }
+
+  // Pattern — anchor with ^…$ (producer emits unanchored)
+  if (pvs.valuePattern) {
+    const pattern = pvs.valuePattern;
+    const anchored = pattern.startsWith('^') && pattern.endsWith('$')
+      ? pattern
+      : `^${pattern}$`;
+    prop.pattern = anchored;
+  }
+
+  // Numeric constraints
+  if (pvs.minValue !== undefined) {
+    prop.minimum = pvs.minValue;
+  }
+  if (pvs.maxValue !== undefined) {
+    prop.maximum = pvs.maxValue;
+  }
+  if (pvs.stepValue !== undefined) {
+    prop.multipleOf = pvs.stepValue;
+  }
+
+  // Read-only
+  if (pvs.readonlyValue) {
+    prop.readOnly = true;
+  }
+
+  // Options → always emit enum (LLMs handle enum + description far more
+  // reliably than oneOf with { const, title } — they anchor on the human
+  // title and send that instead of the machine const value).
+  const options = pvs['nxis:valueOption'];
+  if (options && options.length > 0) {
+    prop.enum = options.map(o => o.value);
+
+    // When labels differ from values, append a human-readable mapping
+    // to the description so the LLM can understand what each value means
+    // while still sending the correct enum value.
+    const hasLabels = options.some(o => o.name !== undefined && o.name !== o.value);
+    if (hasLabels) {
+      const labelMap = options
+        .filter(o => o.name && o.name !== o.value)
+        .map(o => `${o.value} = "${o.name}"`)
+        .join(', ');
+      const existing = prop.description ? `${prop.description}. ` : '';
+      prop.description = `${existing}Values: ${labelMap}`;
+    }
+  }
+
+  return prop;
+}
+
+/**
+ * Coerce a string default value to the appropriate type.
+ */
+function coerceDefault(value: string, valueType: NxisValueType): unknown {
+  switch (valueType) {
+    case 'number':
+    case 'integer': {
+      const n = Number(value);
+      return isNaN(n) ? value : n;
+    }
+    case 'boolean':
+      return value === 'true' || value === '1';
+    default:
+      return value;
+  }
+}

package/src/webmcp/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Type declarations for the WebMCP imperative API.
+ *
+ * Augments the global `Document` and `Navigator` interfaces with
+ * `modelContext` so TypeScript recognizes the WebMCP surface.
+ *
+ * `document.modelContext` is canonical (Chrome 150+).
+ * `navigator.modelContext` is deprecated but supported as fallback.
+ *
+ * @see https://developer.chrome.com/docs/ai/webmcp/imperative-api
+ * @internal
+ */
+
+// ---------------------------------------------------------------------------
+// Tool registration types
+// ---------------------------------------------------------------------------
+
+/** Annotations that hint to the agent how to treat a tool. */
+export interface ToolAnnotations {
+  /**
+   * If true, the tool only reads data and does not mutate the page.
+   * Set to `false` for form-filling tools (we mutate input values).
+   */
+  readOnlyHint?: boolean;
+  /**
+   * If true, the tool's output contains untrusted content from the page.
+   * Always `true` for NxisAI tools — we infer from content we don't control.
+   */
+  untrustedContentHint?: boolean;
+}
+
+/** The shape passed to `modelContext.registerTool()`. */
+export interface ModelContextTool {
+  /** Tool name — unique within the document. */
+  name: string;
+  /** Human-readable description of what the tool does. */
+  description: string;
+  /**
+   * JSON Schema describing the tool's input parameters.
+   * Passed as a plain object (type: "object" with properties).
+   */
+  inputSchema: Record<string, unknown>;
+  /** Behavioral hints for the agent. */
+  annotations?: ToolAnnotations;
+  /**
+   * Called by the agent to execute the tool.
+   * Must return a string (JSON-serialized result).
+   */
+  execute: (args: Record<string, unknown>) => string | Promise<string>;
+}
+
+/** Options for `modelContext.registerTool()`. */
+export interface RegisterToolOptions {
+  /** AbortSignal to unregister the tool when aborted. */
+  signal?: AbortSignal;
+}
+
+/** The ModelContext interface exposed on `document.modelContext`. */
+export interface ModelContext extends EventTarget {
+  /** Register a tool for agents to discover and invoke. */
+  registerTool(tool: ModelContextTool, options?: RegisterToolOptions): void;
+  /** Get all currently registered tools. */
+  getTools(): ModelContextTool[];
+}
+
+// ---------------------------------------------------------------------------
+// Global augmentation
+// ---------------------------------------------------------------------------
+
+declare global {
+  interface Document {
+    /**
+     * The WebMCP model context (canonical, Chrome 150+).
+     * Tools are per-Document, not per-Navigator.
+     */
+    modelContext?: ModelContext;
+  }
+
+  interface Navigator {
+    /**
+     * @deprecated Use `document.modelContext` instead.
+     * Deprecated as of Chrome 150.0.7861.0.
+     */
+    modelContext?: ModelContext;
+  }
+}