@nevescloud/pip 3.3.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevescloud/pip",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Floating assistant bubble + panel + chat runtime. ESM, no build.",
   "type": "module",
   "main": "pip-core.esm.js",
@@ -8,6 +8,8 @@
     ".": "./pip-core.esm.js",
     "./pip-core.esm.js": "./pip-core.esm.js",
     "./runtime.esm.js": "./runtime.esm.js",
+    "./webmcp": "./webmcp.esm.js",
+    "./webmcp.esm.js": "./webmcp.esm.js",
     "./bundle": "./bundle/anthropic.esm.js",
     "./bundle/anthropic": "./bundle/anthropic.esm.js",
     "./bundle/anthropic.esm.js": "./bundle/anthropic.esm.js",
@@ -22,6 +24,7 @@
   "files": [
     "pip-core.esm.js",
     "runtime.esm.js",
+    "webmcp.esm.js",
     "bundle/",
     "providers/",
     "README.md",

package/webmcp.esm.js

@@ -0,0 +1,211 @@
+// WebMCP adapter for pip-runtime.
+//
+// Discovers tools registered via the standard `navigator.modelContext`
+// surface (W3C Community Group Report, 23 April 2026) and wires each one
+// into pip's runtime tool registry. Tools registered on the host page
+// become tools the runtime's provider can call.
+//
+// Usage:
+//   import { createRuntime } from '@nevescloud/pip/runtime.esm.js';
+//   import { attachWebmcp }  from '@nevescloud/pip/webmcp.esm.js';
+//
+//   const rt = createRuntime({ provider });
+//   const webmcp = attachWebmcp(rt);
+//
+//   // Page code (somewhere) calls:
+//   navigator.modelContext.registerTool({
+//     name: 'get_greeting',
+//     description: 'Returns a fresh greeting from this tab.',
+//     inputSchema: { type: 'object', properties: {}, required: [] },
+//     async execute() { return 'Hello!'; },
+//   });
+//
+//   // The runtime's provider now sees `get_greeting` as a callable tool.
+//
+//   // Clean up (reverses the patch, unregisters mirrored tools):
+//   webmcp.stop();
+//
+// Discovery strategy:
+//
+//  1. **Snapshot at attach time.** If `navigator.modelContext` exposes an
+//     iterable of currently-registered tools (`mc.tools`, `mc.getTools()`,
+//     or similar), we read it and mirror each entry into runtime. This
+//     covers tools registered before the adapter started.
+//  2. **Intercept future calls.** `registerTool` / `unregisterTool` on
+//     `navigator.modelContext` are patched so any later call from the
+//     same realm propagates to runtime automatically.
+//
+// Limitations:
+//
+//  - Tools registered from a *different* JavaScript realm (e.g. a separate
+//    extension's content script with its own `navigator` reference) are
+//    invisible to the patch. Snapshot covers them only if `mc` exposes
+//    introspection.
+//  - The WebMCP draft is still in flux; the field names tools may use
+//    (`execute` vs `handler`, `inputSchema` vs `schema`, etc.) are
+//    normalized below — both shapes are accepted.
+
+const DEFAULT_SCHEMA = { type: 'object', properties: {}, required: [] };
+
+// Pull a callable executor off the WebMCP tool def under any of the names
+// the spec/implementations currently use. Returning null lets the caller
+// emit a clearer error than "undefined is not a function".
+function pickExecutor(toolDef) {
+  return (
+    toolDef.execute ||
+    toolDef.handler ||
+    toolDef.run ||
+    null
+  );
+}
+
+// Some WebMCP impls hand the input through under `input`, others as a
+// positional argument. The runtime always calls handler(input, ctx), so
+// pass input through positionally and trust the executor's own shape.
+function makeRuntimeHandler(toolDef) {
+  const exec = pickExecutor(toolDef);
+  if (!exec) {
+    return async () => ({
+      error: `[webmcp] tool "${toolDef.name}" has no execute()/handler()`,
+    });
+  }
+  return async (input, ctx) => {
+    // ctx.signal exists on runtime tools but WebMCP execute() may not
+    // expect a signal in its signature — pass through only if the
+    // executor declares ≥2 parameters. Conservative: forward signal as
+    // a sibling property on the input where possible.
+    try {
+      return await exec(input, ctx);
+    } catch (err) {
+      return { error: String(err?.message || err) };
+    }
+  };
+}
+
+function toRuntimeToolDef(toolDef) {
+  return {
+    name: toolDef.name,
+    description: toolDef.description || '',
+    schema: toolDef.inputSchema || toolDef.schema || DEFAULT_SCHEMA,
+    handler: makeRuntimeHandler(toolDef),
+  };
+}
+
+// Try to read the current WebMCP tool registry without committing to a
+// single shape — different impls expose this differently.
+function snapshotExisting(mc) {
+  if (Array.isArray(mc.tools)) return [...mc.tools];
+  if (typeof mc.getTools === 'function') {
+    try {
+      const t = mc.getTools();
+      if (Array.isArray(t)) return t;
+    } catch { /* swallow */ }
+  }
+  // No introspection available — best we can do is empty. Subsequent
+  // registerTool calls will be caught by the patch.
+  return [];
+}
+
+export function attachWebmcp(runtime, options = {}) {
+  if (!runtime || typeof runtime.registerTool !== 'function') {
+    throw new Error('[webmcp] attachWebmcp(runtime): runtime must expose registerTool/unregisterTool (createRuntime() handle).');
+  }
+  if (typeof navigator === 'undefined' || !navigator.modelContext) {
+    throw new Error('[webmcp] navigator.modelContext is not available. Requires a supporting browser (Chrome 146+ with the WebMCP flag, or a polyfill such as hatch).');
+  }
+
+  const {
+    autoRegisterExisting = true,
+    namePrefix = '',
+    onWire = null,
+    onUnwire = null,
+  } = options;
+
+  const mc = navigator.modelContext;
+  // wired: webmcp tool name (as seen by mc) → runtime tool name (post-prefix).
+  const wired = new Map();
+  const originalRegister = typeof mc.registerTool === 'function' ? mc.registerTool.bind(mc) : null;
+  const originalUnregister = typeof mc.unregisterTool === 'function' ? mc.unregisterTool.bind(mc) : null;
+  let patched = false;
+  let stopped = false;
+
+  function runtimeName(webmcpName) {
+    return namePrefix ? `${namePrefix}${webmcpName}` : webmcpName;
+  }
+
+  function wireOne(toolDef) {
+    if (!toolDef || !toolDef.name) return;
+    if (wired.has(toolDef.name)) return;            // already mirrored
+    const rtDef = toRuntimeToolDef(toolDef);
+    rtDef.name = runtimeName(toolDef.name);
+    try {
+      runtime.registerTool(rtDef);
+      wired.set(toolDef.name, rtDef.name);
+      onWire?.(rtDef.name, toolDef);
+    } catch (err) {
+      // Surface but don't throw — one bad tool shouldn't break the rest.
+      console.warn(`[webmcp] could not mirror tool "${toolDef.name}":`, err?.message || err);
+    }
+  }
+
+  function unwireOne(webmcpName) {
+    const rtName = wired.get(webmcpName);
+    if (!rtName) return;
+    try { runtime.unregisterTool(rtName); } catch {}
+    wired.delete(webmcpName);
+    onUnwire?.(rtName, webmcpName);
+  }
+
+  function patchModelContext() {
+    if (patched || !originalRegister) return;
+    mc.registerTool = function patchedRegisterTool(toolDef) {
+      const result = originalRegister(toolDef);
+      try { wireOne(toolDef); } catch (err) {
+        console.warn('[webmcp] wireOne failed:', err?.message || err);
+      }
+      return result;
+    };
+    if (originalUnregister) {
+      mc.unregisterTool = function patchedUnregisterTool(name) {
+        const result = originalUnregister(name);
+        try { unwireOne(name); } catch {}
+        return result;
+      };
+    }
+    patched = true;
+  }
+
+  function unpatchModelContext() {
+    if (!patched) return;
+    if (originalRegister) mc.registerTool = originalRegister;
+    if (originalUnregister) mc.unregisterTool = originalUnregister;
+    patched = false;
+  }
+
+  if (autoRegisterExisting) {
+    for (const t of snapshotExisting(mc)) wireOne(t);
+  }
+  patchModelContext();
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    unpatchModelContext();
+    for (const webmcpName of [...wired.keys()]) unwireOne(webmcpName);
+  }
+
+  return {
+    stop,
+    /** Re-snapshot — useful if the host added tools through a different
+     *  realm or before the polyfill installed itself. Idempotent: tools
+     *  already mirrored are skipped. */
+    refresh() {
+      if (stopped) return;
+      for (const t of snapshotExisting(mc)) wireOne(t);
+    },
+    /** Names actually mirrored into the runtime (post-prefix). */
+    get wired() { return [...wired.values()]; },
+    /** Original WebMCP-side names (pre-prefix). */
+    get webmcpNames() { return [...wired.keys()]; },
+  };
+}