simple-webmcp 0.2.0 → 0.3.0

package/README.md

@@ -30,7 +30,7 @@ function CustomersPage() {
 }
 ```
 
-**Framework-agnostic core. React adapter included. More adapters coming.** Works with vanilla JS, TypeScript, Vite — Next.js `server()` is experimental until the `fixtures/next-app` spike proves the Server Action bridge.
+**Framework-agnostic core. React adapter included.** Works with vanilla JS, TypeScript, Vite — Next.js support remains experimental until proven.
 
 > **One function. Two interfaces.** Human code `search(input)` and agent `search(input)` — same capability.
 >
@@ -152,6 +152,27 @@ Verbose 2-line still works: `const t = webmcp(fn); useWebMCP(t)`. Layout-level:
 
 `register()` is `async` (`Promise<() => void>`) per current `webmcp-types`; hook maps to `AbortSignal` and dedupes StrictMode. `status` is `'unregistered'|'registering'|'registered'|'unsupported'|'error'` — `supported` and `registered` are mutually exclusive (unsupported never claims registered).
 
+### Hooks — before / after / error / denied (HITL)
+
+```ts
+const tool = webmcp(checkout, {
+  description: 'Checkout cart',
+  hooks: {
+    before: [async ({input}) => {
+      const ok = await confirm(`Checkout £${total}?`);
+      if (!ok) return { action: 'deny', message: 'User declined' };
+    }],
+    after:  [({output}) => ({ output: redact(output) })],
+    error:  [({error}) => console.warn(error)],
+    denied: [({reason}) => analytics.track('denied', {reason})],
+  }
+});
+webmcp.configure({ hooks:{ before:[trackInvocation], after:[trackResult] }});
+<WebMCPProvider hooks={{ before:[addTenant] }}><Scope tools={[tool]}>{children}</Scope></WebMCPProvider>
+```
+
+Hooks wrap only the agent `execute` path — `tool({input})` stays pure. Ordering: `before` `global→scoped→tool`, `after` `tool→scoped→global`. Direct + `console` + UI logs in the [demo](/demo) **Hooks & HITL** card. See [Guide — Hooks](https://emingure.github.io/simple-webmcp/guide/hooks) and [Analytics](https://emingure.github.io/simple-webmcp/guide/analytics) (PostHog, Mixpanel, GA4, Sentry, etc.).
+
 ## Customize only what you need
 
 ```ts
@@ -178,9 +199,9 @@ webmcp(fn, { fields: { query: z.string().describe('Name') } });
 
 **Infer what JavaScript can know at runtime. Get richer TypeScript/JSDoc inference with the optional build plugin.**
 
-*Runtime (0.1)* — best-effort, `confidence:'low'`: parameter names, defaults, destructured keys (`{query, limit=20}` → `query` required, `limit` optional `default:20`), some primitives from literal defaults. `function search(query: string)` alone becomes `{properties:{query:{}}}` — we warn and need `fields`/`schema` or `strict:true` throws.
+*Runtime* — best-effort, `confidence:'low'`: parameter names, defaults, destructured keys (`{query, limit=20}` → `query` required, `limit` optional `default:20`), some primitives from literal defaults. `function search(query: string)` alone becomes `{properties:{query:{}}}` — we warn and need `fields`/`schema` or `strict:true` throws.
 
-*Build (0.2 `simple-webmcp/unplugin`)* — Vite/Webpack plugin reads TypeScript types + JSDoc before erasure (same approach `webmcp-nexus` validates with `ts-morph`). Same `webmcp(fn)` call, richer `inputSchema`, no code change.
+*Build* — optional `simple-webmcp/unplugin` (Vite/Webpack) reads TypeScript types + JSDoc before erasure. Same `webmcp(fn)` call, richer `inputSchema`, no code change.
 
 Progressive:
 
@@ -223,9 +244,11 @@ Start with one function.
 
 See `.agents/skills/webmcp-simple/references/api.md`.
 
-**Core:** `webmcp(fn, opts)` → `WebMCPTool` (callable + `tool`/`definition`/`register`/`status`), `webmcp.global`, `isWebMCPSupported()`, `registry.list()`. Errors: `NotSupportedError` (`unsupported` status, mutually exclusive with `registered`), `NotAllowedError`, `RegistrationError`, `ConfigurationError`.
+**Core:** `webmcp(fn, opts)` → `WebMCPTool` (callable + `tool`/`definition`/`register`/`status`), `webmcp.global`, `webmcp.configure({hooks})`, `isWebMCPSupported()`, `registry.list()`. Errors: `NotSupportedError` (`unsupported` status, mutually exclusive with `registered`), `NotAllowedError`, `RegistrationError`, `ConfigurationError`.
 
-**React:** `useWebMCP(fn, opts)` / `useWebMCP(tool)` → `WebMCPTool & status` / `status`, `useTool` alias, `<Scope tools>`.
+**Hooks:** `hooks:{ before:[], after:[], error:[], denied:[] }` on `webmcp(fn,{hooks})`, `webmcp.configure`, and `<WebMCPProvider hooks>`. See [Guide — Hooks](https://emingure.github.io/simple-webmcp/guide/hooks) and [Analytics](https://emingure.github.io/simple-webmcp/guide/analytics) for PostHog/Mixpanel/GA4/Sentry examples. Demo shows live hook log + HITL approval modal.
+
+**React:** `useWebMCP(fn, opts)` / `useWebMCP(tool)` → `WebMCPTool & status` / `status`, `useTool` alias, `<Scope tools>`, `<WebMCPProvider hooks>`.
 
 **Zod:** `import 'simple-webmcp/zod'` then `schema`/`fields` accept Zod/StandardSchema.
 
@@ -235,19 +258,14 @@ WebMCP today is `document.modelContext` (Chrome canary, origin trial). This pack
 
 ```bash
 npm run build      # tsup ESM+CJS+DTS (core 6.26KB gz, zod 1.40KB separate)
-npm test           # vitest jsdom — 43 tests
+npm test           # vitest jsdom — 47 tests
 npm run typecheck
 npm run docs:dev   # VitePress
 ```
 
 ## Versioning
 
-* **0.1** — `webmcp()` + `useWebMCP`/`useTool` + `Scope` + runtime best-effort fallback + dev shim + 43 tests (this release)
-* **0.2** — `simple-webmcp/unplugin` TS/JSDoc inference (Vite/Webpack)
-* **0.3** — `simple-webmcp/next` `webmcp.server()` — experimental, gated behind `fixtures/next-app` spike. Next 16 defaults to Turbopack, so no Webpack plugin in 0.1.
-* **0.4** — `webmcp.bind()`, DevTools, CLI — deferred
-
-`outputSchema` is kept internally but not marketed in 0.1 — current browser API does not enforce it like `usewebmcp` notes.
+Follows [Semantic Versioning](https://semver.org/). See [`CHANGELOG.md`](./CHANGELOG.md) for the current `0.2.0` notes and [`RELEASING.md`](./RELEASING.md) for the release process. No future roadmap is promised here — track GitHub issues/discussions for what's next.
 
 ## Skills (Agent)
 

package/dist/devtools.d.cts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { InspectedTool } from './inspect.cjs';
-import './types-DH78HDAE.cjs';
-import './registry-BcPw1qCf.cjs';
+import './types-CF8kTj5O.cjs';
+import './registry-A4DdpmDn.cjs';
 
 type Props = {
     /** If true, panel is expanded by default */

package/dist/devtools.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { InspectedTool } from './inspect.js';
-import './types-DH78HDAE.js';
-import './registry-C6Pz_Rja.js';
+import './types-CF8kTj5O.js';
+import './registry-Dscedahn.js';
 
 type Props = {
     /** If true, panel is expanded by default */

package/dist/index.cjs

@@ -594,7 +594,12 @@ function normalizeResult(value) {
   }
 }
 function normalizeError(err) {
-  const message = err instanceof Error ? err.message : typeof err === "string" ? err : (() => {
+  const message = (() => {
+    if (err instanceof Error) return err.message;
+    if (typeof err === "string") return err;
+    if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
+      return err.message;
+    }
     try {
       return JSON.stringify(err);
     } catch {
@@ -624,6 +629,247 @@ function wrapExecute(fn, opts) {
   };
 }
 
+// src/hooks/engine.ts
+var fallbackCounter = 0;
+function genInvocationId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return fallbackInvocationId();
+}
+function fallbackInvocationId() {
+  fallbackCounter = (fallbackCounter + 1) % Number.MAX_SAFE_INTEGER;
+  return `webmcp_${Date.now().toString(36)}_${fallbackCounter}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function isDenyResult(r) {
+  return !!r && typeof r === "object" && r.action === "deny";
+}
+async function runErrorHooks(hooks, ctx) {
+  if (!hooks || hooks.length === 0) return;
+  for (const h of hooks) {
+    try {
+      await h(ctx);
+    } catch {
+    }
+  }
+}
+async function runDeniedHooks(hooks, ctx) {
+  if (!hooks || hooks.length === 0) return;
+  for (const h of hooks) {
+    try {
+      await h(ctx);
+    } catch {
+    }
+  }
+}
+function createHookedExecute(fn, tool, contract, options) {
+  return async (args, _ctx) => {
+    const invocationId = genInvocationId();
+    const metadata = {};
+    const signal = tool.__activeSignal ?? createNeverAbortedSignal();
+    const merged = options.getHooks();
+    let currentInput = args;
+    const base = { invocationId, tool, contract, signal, metadata };
+    const beforeHooks = merged.before ?? [];
+    for (const hook of beforeHooks) {
+      if (signal.aborted) {
+        const abortErr = new DOMException("Aborted", "AbortError");
+        await runErrorHooks(merged.error, {
+          ...base,
+          input: currentInput,
+          error: abortErr
+        });
+        return normalizeError(abortErr);
+      }
+      let res;
+      try {
+        const ctx = { ...base, input: currentInput };
+        res = await hook(ctx);
+      } catch (hookErr) {
+        await runErrorHooks(merged.error, {
+          ...base,
+          input: currentInput,
+          error: hookErr
+        });
+        return normalizeError(hookErr);
+      }
+      if (res != null && typeof res === "object") {
+        if (isDenyResult(res)) {
+          const reason = res.message;
+          const code = res.code;
+          await runDeniedHooks(merged.denied, {
+            ...base,
+            input: currentInput,
+            reason,
+            code
+          });
+          const msg = reason ?? "Tool execution denied";
+          return {
+            content: [{ type: "text", text: `Denied: ${msg}` }],
+            isError: true,
+            ...code ? { code } : {}
+          };
+        }
+        if ("input" in res && res.input !== void 0) {
+          currentInput = res.input;
+        }
+      }
+    }
+    if (signal.aborted) {
+      const abortErr = new DOMException("Aborted", "AbortError");
+      await runErrorHooks(merged.error, {
+        ...base,
+        input: currentInput,
+        error: abortErr
+      });
+      return normalizeError(abortErr);
+    }
+    if (options.validate) {
+      try {
+        options.validate(currentInput);
+      } catch (valErr) {
+        await runErrorHooks(merged.error, {
+          ...base,
+          input: currentInput,
+          error: valErr
+        });
+        return normalizeError(valErr);
+      }
+    }
+    let rawOutput;
+    try {
+      rawOutput = await fn(currentInput);
+    } catch (fnErr) {
+      await runErrorHooks(merged.error, {
+        ...base,
+        input: currentInput,
+        error: fnErr
+      });
+      return normalizeError(fnErr);
+    }
+    let currentOutput = rawOutput;
+    const afterHooks = merged.after ?? [];
+    for (const hook of afterHooks) {
+      if (signal.aborted) ;
+      try {
+        const ctx = {
+          ...base,
+          input: currentInput,
+          output: currentOutput
+        };
+        const res = await hook(ctx);
+        if (res != null && typeof res === "object" && "output" in res && res.output !== void 0) {
+          currentOutput = res.output;
+        }
+      } catch (hookErr) {
+        await runErrorHooks(merged.error, {
+          ...base,
+          input: currentInput,
+          error: hookErr
+        });
+        return normalizeError(hookErr);
+      }
+    }
+    return normalizeResult(currentOutput);
+  };
+}
+function createNeverAbortedSignal() {
+  try {
+    return new AbortController().signal;
+  } catch {
+    return {
+      aborted: false,
+      addEventListener() {
+      },
+      removeEventListener() {
+      },
+      dispatchEvent() {
+        return false;
+      },
+      onabort: null,
+      reason: void 0,
+      throwIfAborted() {
+      }
+    };
+  }
+}
+
+// src/hooks/config.ts
+var GLOBAL_KEY = "__simpleWebmcp_hooks";
+function getStore() {
+  const g = globalThis;
+  if (!g[GLOBAL_KEY]) {
+    g[GLOBAL_KEY] = { hooks: {} };
+  }
+  return g[GLOBAL_KEY];
+}
+function getGlobalHooks() {
+  return getStore().hooks ?? {};
+}
+function configureWebMCP(opts) {
+  const store = getStore();
+  if (!opts.hooks) return;
+  if (opts.replace) {
+    store.hooks = normalizeHooks(opts.hooks);
+    return;
+  }
+  store.hooks = mergeHooks(store.hooks, opts.hooks);
+}
+function resetGlobalHooks() {
+  const store = getStore();
+  store.hooks = {};
+}
+function normalizeHooks(hooks) {
+  return {
+    before: hooks.before ? [...hooks.before] : void 0,
+    after: hooks.after ? [...hooks.after] : void 0,
+    error: hooks.error ? [...hooks.error] : void 0,
+    denied: hooks.denied ? [...hooks.denied] : void 0
+  };
+}
+function mergeHooks(a, b) {
+  if (!a && !b) return {};
+  if (!a) return normalizeHooks(b);
+  if (!b) return a;
+  return {
+    before: [...a.before ?? [], ...b.before ?? []],
+    after: [...a.after ?? [], ...b.after ?? []],
+    error: [...a.error ?? [], ...b.error ?? []],
+    denied: [...a.denied ?? [], ...b.denied ?? []]
+  };
+}
+function mergeHooksOrdered(opts) {
+  const globalHooks = opts.globalHooks ?? {};
+  const scopedHooks = opts.scopedHooks ?? {};
+  const toolHooks = opts.toolHooks ?? {};
+  const before = [
+    ...globalHooks.before ?? [],
+    ...scopedHooks.before ?? [],
+    ...toolHooks.before ?? []
+  ];
+  const after = [
+    ...toolHooks.after ?? [],
+    ...scopedHooks.after ?? [],
+    ...globalHooks.after ?? []
+  ];
+  const error = [
+    ...toolHooks.error ?? [],
+    ...scopedHooks.error ?? [],
+    ...globalHooks.error ?? []
+  ];
+  const denied = [
+    ...toolHooks.denied ?? [],
+    ...scopedHooks.denied ?? [],
+    ...globalHooks.denied ?? []
+  ];
+  const out = {};
+  if (before.length) out.before = before;
+  if (after.length) out.after = after;
+  if (error.length) out.error = error;
+  if (denied.length) out.denied = denied;
+  return out;
+}
+
 // src/webmcp.ts
 function resolveScope(opts) {
   if (opts?.scope) return opts.scope;
@@ -637,8 +883,24 @@ function webmcp(fn, options) {
   const anyFn = fn;
   if (anyFn.__webmcpBrand === true && anyFn.definition) {
     if (!options || Object.keys(options).length === 0) return anyFn;
+    const prevOpts = anyFn.__webmcpOptions || {};
+    const mergedOpts = { ...prevOpts, ...options };
+    if (prevOpts.hooks || options?.hooks) {
+      const prevHooks = prevOpts.hooks ?? {};
+      const nextHooks = options.hooks ?? {};
+      mergedOpts.hooks = {
+        before: [...prevHooks.before ?? [], ...nextHooks.before ?? []],
+        after: [...prevHooks.after ?? [], ...nextHooks.after ?? []],
+        error: [...prevHooks.error ?? [], ...nextHooks.error ?? []],
+        denied: [...prevHooks.denied ?? [], ...nextHooks.denied ?? []]
+      };
+      for (const k of ["before", "after", "error", "denied"]) {
+        if (mergedOpts.hooks[k]?.length === 0) delete mergedOpts.hooks[k];
+      }
+      if (mergedOpts.hooks && Object.keys(mergedOpts.hooks).length === 0) delete mergedOpts.hooks;
+    }
     const original = anyFn.__fn ?? fn;
-    return webmcp(original, { ...anyFn.__webmcpOptions || {}, ...options });
+    return webmcp(original, mergedOpts);
   }
   const name = options?.name ?? toSnakeCase(getFunctionName(fn));
   if (!name) throw new ConfigurationError('Tool name could not be inferred \u2014 pass {name:"my_tool"}');
@@ -691,15 +953,30 @@ function webmcp(fn, options) {
   let registrationPromise = null;
   let unregisterFn = null;
   let activeController = null;
-  const wrappedExec = wrapExecute(fn);
+  const toolHooks = options?.hooks ? { ...options.hooks } : void 0;
   const toolWrapper = wrapper;
   toolWrapper.__webmcpBrand = true;
   toolWrapper.__fn = fn;
   toolWrapper.__webmcpOptions = options;
   if (standard) toolWrapper.__standardSchema = standard;
   if (outNorm.standard) toolWrapper.__outputStandardSchema = outNorm.standard;
+  if (toolHooks) toolWrapper.__hooks = toolHooks;
   toolWrapper.tool = contract;
   toolWrapper.definition = contract;
+  const hookedExec = createHookedExecute(fn, toolWrapper, contract, {
+    getHooks: () => {
+      const globalHooks = getGlobalHooks();
+      const scopeHooks = toolWrapper.__scopeHooks;
+      return mergeHooksOrdered({ globalHooks, scopedHooks: scopeHooks, toolHooks });
+    },
+    validate: standard ? (input) => {
+      const res = standard["~standard"].validate(input);
+      if ("issues" in res && res.issues && res.issues.length > 0) {
+        const msg = res.issues.map((i) => i.message).join("; ");
+        throw new ValidationError(`Validation failed: ${msg}`);
+      }
+    } : void 0
+  });
   Object.defineProperty(toolWrapper, "status", {
     get() {
       return status;
@@ -732,11 +1009,16 @@ function webmcp(fn, options) {
     status = "registering";
     const controller = new AbortController();
     activeController = controller;
+    toolWrapper.__activeSignal = controller.signal;
     if (opts?.signal) {
       if (opts.signal.aborted) {
         controller.abort();
         status = "unregistered";
         activeController = null;
+        try {
+          delete toolWrapper.__activeSignal;
+        } catch {
+        }
         return () => {
         };
       }
@@ -751,11 +1033,15 @@ function webmcp(fn, options) {
     controller.signal.addEventListener("abort", () => {
       if (status !== "unregistered") status = "unregistered";
       activeController = null;
+      try {
+        delete toolWrapper.__activeSignal;
+      } catch {
+      }
     }, { once: true });
     try {
       const unregister = await registry.register(contract, {
         signal: controller.signal,
-        execute: wrappedExec
+        execute: hookedExec
       });
       unregisterFn = unregister;
       registrationPromise = Promise.resolve();
@@ -773,6 +1059,10 @@ function webmcp(fn, options) {
         }
         status = "unregistered";
         activeController = null;
+        try {
+          delete toolWrapper.__activeSignal;
+        } catch {
+        }
         unregisterFn = null;
       };
     } catch (err) {
@@ -781,6 +1071,11 @@ function webmcp(fn, options) {
       } else {
         status = "error";
       }
+      activeController = null;
+      try {
+        delete toolWrapper.__activeSignal;
+      } catch {
+      }
       registrationPromise = Promise.reject(err);
       if (err instanceof SimpleWebMCPError) throw err;
       throw err;
@@ -799,6 +1094,10 @@ function webmcp(fn, options) {
     }
     status = "unregistered";
     activeController = null;
+    try {
+      delete toolWrapper.__activeSignal;
+    } catch {
+    }
     unregisterFn = null;
     registrationPromise = null;
   };
@@ -817,6 +1116,9 @@ function webmcp(fn, options) {
 webmcp.global = function global(fn, opts) {
   return webmcp(fn, { ...opts, global: true });
 };
+webmcp.configure = configureWebMCP;
+webmcp.getGlobalHooks = getGlobalHooks;
+webmcp.resetGlobalHooks = resetGlobalHooks;
 webmcp.isWebMCPTool = function isWebMCPTool(v) {
   return !!v?.__webmcpBrand;
 };
@@ -834,14 +1136,21 @@ exports.SimpleWebMCPError = SimpleWebMCPError;
 exports.ValidationError = ValidationError;
 exports.applyFieldsPatch = applyFieldsPatch;
 exports.buildFinalInputSchema = buildFinalInputSchema;
+exports.configureWebMCP = configureWebMCP;
+exports.createHookedExecute = createHookedExecute;
 exports.default = webmcp_default;
+exports.genInvocationId = genInvocationId;
+exports.getGlobalHooks = getGlobalHooks;
 exports.getModelContext = getModelContext;
 exports.getRegistry = getRegistry;
 exports.inferRuntime = inferRuntime;
 exports.isWebMCPSupported = isWebMCPSupported;
+exports.mergeHooks = mergeHooks;
+exports.mergeHooksOrdered = mergeHooksOrdered;
 exports.normalizeError = normalizeError;
 exports.normalizeResult = normalizeResult;
 exports.registry = registry;
+exports.resetGlobalHooks = resetGlobalHooks;
 exports.toSnakeCase = toSnakeCase;
 exports.webmcp = webmcp;
 exports.wrapExecute = wrapExecute;