simple-webmcp 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,8 +1,65 @@
-import { W as WebMCPOptions, a as WebMCPTool, M as ModelContextLike, R as RegistrationStatus, T as ToolContract, J as JsonSchema, F as FieldDefOrSchema, S as StandardSchemaV1 } from './types-D-cwSfEU.js';
-export { b as FieldDef, c as WebMCPAnnotations } from './types-D-cwSfEU.js';
+import { b as WebMCPHooks, a as WebMCPOptions, W as WebMCPTool, T as ToolContract, M as ModelContextLike, J as JsonSchema, F as FieldDefOrSchema, S as StandardSchemaV1 } from './types-CF8kTj5O.js';
+export { A as AfterContext, c as AfterHook, B as BeforeContext, d as BeforeHook, D as DeniedContext, e as DeniedHook, E as ErrorContext, f as ErrorHook, g as FieldDef, R as RegistrationStatus, h as WebMCPAnnotations } from './types-CF8kTj5O.js';
+export { g as getRegistry, r as registry } from './registry-Dscedahn.js';
+
+declare function getGlobalHooks(): WebMCPHooks<any>;
+declare function configureWebMCP(opts: {
+    hooks?: WebMCPHooks<any>;
+    replace?: boolean;
+}): void;
+declare function resetGlobalHooks(): void;
+declare function mergeHooks<F extends (...args: any) => any>(a: WebMCPHooks<any> | undefined, b: WebMCPHooks<F> | undefined): WebMCPHooks<F>;
+/**
+ * Merge with correct ordering semantics:
+ * before: global → scoped → tool
+ * after:  tool → scoped → global (onion)
+ * error/denied: tool → scoped → global
+ */
+declare function mergeHooksOrdered<F extends (...args: any) => any>(opts: {
+    globalHooks?: WebMCPHooks<any>;
+    scopedHooks?: WebMCPHooks<any>;
+    toolHooks?: WebMCPHooks<F>;
+}): WebMCPHooks<F>;
 
 declare function webmcp<F extends (...args: any) => any>(fn: F, options?: WebMCPOptions<F>): WebMCPTool<F>;
 
+/**
+ * Normalize execute return values per WebMCP spec.
+ * WebMCP expects { content: [{type:'text', text: ...}], isError? }
+ * We allow fn to return string, object, or already-normalized shape.
+ */
+type NormalizedResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: string;
+        [k: string]: unknown;
+    }>;
+    isError?: boolean;
+    [k: string]: unknown;
+};
+declare function normalizeResult(value: unknown): NormalizedResult;
+declare function normalizeError(err: unknown): NormalizedResult;
+/**
+ * Wrap an execute fn to handle:
+ * - args: object (WebMCP passes single object) vs spread
+ * - async errors
+ * - result normalization
+ * For 0.1 we assume fn expects single object param (preferred).
+ * For multi-arg legacy, user should use webmcp.bind (deferred) — here we provide auto-spread fallback heuristic.
+ */
+declare function wrapExecute<F extends (...args: any) => any>(fn: F, opts?: {
+    argMode?: 'object' | 'spread';
+}): (args: unknown, ctx?: unknown) => Promise<NormalizedResult>;
+
+declare function genInvocationId(): string;
+type CreateHookedExecuteOptions<F extends (...args: any) => any> = {
+    getHooks: () => WebMCPHooks<F>;
+    validate?: (input: unknown) => void;
+};
+declare function createHookedExecute<F extends (...args: any) => any>(fn: F, tool: WebMCPTool<F>, contract: ToolContract, options: CreateHookedExecuteOptions<F>): (args: unknown, ctx?: unknown) => Promise<NormalizedResult>;
+
 /**
  * Base error for simple-webmcp
  */
@@ -55,54 +112,6 @@ declare function toSnakeCase(name: string): string;
 declare function isWebMCPSupported(): boolean;
 declare function getModelContext(): ModelContextLike | null;
 
-declare class Registry {
-    private entries;
-    list(): Array<{
-        name: string;
-        status: RegistrationStatus;
-    }>;
-    clear(): void;
-    isRegistered(name: string): boolean;
-    getStatus(name: string): RegistrationStatus;
-    register(contract: ToolContract, opts?: {
-        signal?: AbortSignal;
-        execute?: (args: unknown, ctx?: unknown) => Promise<any>;
-    }): Promise<() => void>;
-    unregister(name: string): void;
-}
-declare const registry: Registry;
-declare function getRegistry(): Registry;
-
-/**
- * Normalize execute return values per WebMCP spec.
- * WebMCP expects { content: [{type:'text', text: ...}], isError? }
- * We allow fn to return string, object, or already-normalized shape.
- */
-type NormalizedResult = {
-    content: Array<{
-        type: 'text';
-        text: string;
-    } | {
-        type: string;
-        [k: string]: unknown;
-    }>;
-    isError?: boolean;
-    [k: string]: unknown;
-};
-declare function normalizeResult(value: unknown): NormalizedResult;
-declare function normalizeError(err: unknown): NormalizedResult;
-/**
- * Wrap an execute fn to handle:
- * - args: object (WebMCP passes single object) vs spread
- * - async errors
- * - result normalization
- * For 0.1 we assume fn expects single object param (preferred).
- * For multi-arg legacy, user should use webmcp.bind (deferred) — here we provide auto-spread fallback heuristic.
- */
-declare function wrapExecute<F extends (...args: any) => any>(fn: F, opts?: {
-    argMode?: 'object' | 'spread';
-}): (args: unknown, ctx?: unknown) => Promise<NormalizedResult>;
-
 /**
  * Runtime inference — best-effort, confidence: low (§11).
  * We cannot know types from JS alone. We return placeholders and defaults detection.
@@ -150,4 +159,4 @@ declare function buildFinalInputSchema(opts: {
 
 declare const SDK_VERSION = "0.1.0";
 
-export { ConfigurationError, FieldDefOrSchema, JsonSchema, NotAllowedError, NotSupportedError, RegistrationError, RegistrationStatus, SDK_VERSION, SimpleWebMCPError, StandardSchemaV1, ToolContract, ValidationError, WebMCPOptions, WebMCPTool, applyFieldsPatch, buildFinalInputSchema, webmcp as default, getModelContext, getRegistry, inferRuntime, isWebMCPSupported, normalizeError, normalizeResult, registry, toSnakeCase, webmcp, wrapExecute };
+export { ConfigurationError, FieldDefOrSchema, JsonSchema, NotAllowedError, NotSupportedError, RegistrationError, SDK_VERSION, SimpleWebMCPError, StandardSchemaV1, ToolContract, ValidationError, WebMCPHooks, WebMCPOptions, WebMCPTool, applyFieldsPatch, buildFinalInputSchema, configureWebMCP, createHookedExecute, webmcp as default, genInvocationId, getGlobalHooks, getModelContext, inferRuntime, isWebMCPSupported, mergeHooks, mergeHooksOrdered, normalizeError, normalizeResult, resetGlobalHooks, toSnakeCase, webmcp, wrapExecute };

package/dist/index.js

@@ -433,9 +433,15 @@ var Registry = class {
   constructor() {
     this.entries = /* @__PURE__ */ new Map();
   }
-  // expose for devtools/tests
+  // expose for devtools/tests — now includes contract for inspect
   list() {
-    return Array.from(this.entries.values()).map((e) => ({ name: e.name, status: e.status }));
+    return Array.from(this.entries.values()).map((e) => ({ name: e.name, status: e.status, contract: e.contract }));
+  }
+  get(name) {
+    return this.entries.get(name);
+  }
+  getContract(name) {
+    return this.entries.get(name)?.contract;
   }
   clear() {
     for (const e of this.entries.values()) {
@@ -459,37 +465,10 @@ var Registry = class {
       return existing.unregister;
     }
     if (!isWebMCPSupported()) {
-      const controller2 = new AbortController();
-      const entry2 = {
-        name,
-        controller: controller2,
-        status: "registered",
-        promise: Promise.resolve(),
-        unregister: () => {
-          try {
-            controller2.abort();
-          } catch {
-          }
-          this.entries.delete(name);
-        }
+      if (opts?.signal?.aborted) return () => {
+      };
+      return () => {
       };
-      if (opts?.signal) {
-        if (opts.signal.aborted) {
-          controller2.abort();
-          this.entries.delete(name);
-          return () => {
-          };
-        }
-        opts.signal.addEventListener("abort", () => {
-          try {
-            controller2.abort();
-          } catch {
-          }
-          this.entries.delete(name);
-        }, { once: true });
-      }
-      this.entries.set(name, entry2);
-      return entry2.unregister;
     }
     const modelContext = getModelContext();
     if (!modelContext) throw new NotSupportedError();
@@ -525,7 +504,9 @@ var Registry = class {
           entry.status = "unregistered";
           this.entries.delete(name);
         }
-      }
+      },
+      contract,
+      execute: opts?.execute
     };
     this.entries.set(name, entry);
     const wrappedExecute = opts?.execute ?? (async (args) => ({ content: [{ type: "text", text: `no execute for ${name}` }] }));
@@ -574,7 +555,12 @@ var Registry = class {
     this.entries.delete(name);
   }
 };
-var registry = new Registry();
+var REGISTRY_KEY = "__simpleWebmcpRegistry";
+var globalAny = globalThis;
+var registry = globalAny[REGISTRY_KEY] ?? new Registry();
+if (!globalAny[REGISTRY_KEY]) {
+  globalAny[REGISTRY_KEY] = registry;
+}
 function getRegistry() {
   return registry;
 }
@@ -604,7 +590,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 {
@@ -634,6 +625,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;
@@ -647,8 +879,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"}');
@@ -701,26 +949,43 @@ 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;
     },
-    enumerable: true
+    enumerable: true,
+    configurable: true
   });
   Object.defineProperty(toolWrapper, "registration", {
     get() {
       return registrationPromise;
     },
-    enumerable: true
+    enumerable: true,
+    configurable: true
   });
   toolWrapper.isRegistered = () => status === "registered";
   toolWrapper.register = async (opts) => {
@@ -731,14 +996,25 @@ function webmcp(fn, options) {
       return () => {
       };
     }
+    if (!isWebMCPSupported()) {
+      status = "unsupported";
+      return () => {
+        status = "unregistered";
+      };
+    }
     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 () => {
         };
       }
@@ -753,16 +1029,22 @@ 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();
       if (controller.signal.aborted) {
         status = "unregistered";
+      } else if (!isWebMCPSupported()) {
+        status = "unsupported";
       } else {
         status = "registered";
       }
@@ -773,10 +1055,23 @@ function webmcp(fn, options) {
         }
         status = "unregistered";
         activeController = null;
+        try {
+          delete toolWrapper.__activeSignal;
+        } catch {
+        }
         unregisterFn = null;
       };
     } catch (err) {
-      status = "error";
+      if (err instanceof NotSupportedError || err?.code === "NOT_SUPPORTED" || err?.name === "NotSupportedError") {
+        status = "unsupported";
+      } else {
+        status = "error";
+      }
+      activeController = null;
+      try {
+        delete toolWrapper.__activeSignal;
+      } catch {
+      }
       registrationPromise = Promise.reject(err);
       if (err instanceof SimpleWebMCPError) throw err;
       throw err;
@@ -795,6 +1090,10 @@ function webmcp(fn, options) {
     }
     status = "unregistered";
     activeController = null;
+    try {
+      delete toolWrapper.__activeSignal;
+    } catch {
+    }
     unregisterFn = null;
     registrationPromise = null;
   };
@@ -813,6 +1112,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;
 };
@@ -821,6 +1123,6 @@ var webmcp_default = webmcp;
 // src/constants.ts
 var SDK_VERSION = "0.1.0";
 
-export { ConfigurationError, NotAllowedError, NotSupportedError, RegistrationError, SDK_VERSION, SimpleWebMCPError, ValidationError, applyFieldsPatch, buildFinalInputSchema, webmcp_default as default, getModelContext, getRegistry, inferRuntime, isWebMCPSupported, normalizeError, normalizeResult, registry, toSnakeCase, webmcp, wrapExecute };
+export { ConfigurationError, NotAllowedError, NotSupportedError, RegistrationError, SDK_VERSION, SimpleWebMCPError, ValidationError, applyFieldsPatch, buildFinalInputSchema, configureWebMCP, createHookedExecute, webmcp_default as default, genInvocationId, getGlobalHooks, getModelContext, getRegistry, inferRuntime, isWebMCPSupported, mergeHooks, mergeHooksOrdered, normalizeError, normalizeResult, registry, resetGlobalHooks, toSnakeCase, webmcp, wrapExecute };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map