fix: address PR feedback - make ShadowRealm usage correct

- Add TypeScript type declaration for ShadowRealm (Stage 3 proposal)
- Make safeEvaluateMath synchronous (evaluate() is sync per TC39 spec)
- Add input validation regex to only allow safe math characters
- Remove unnecessary parentheses wrapping around expression
- Add note about DoS vectors not being prevented by ShadowRealm

Co-Authored-By: Tom Aylott <thomas.42@gmail.com>

Author: devin-ai-integration[bot]

examples/tools-example.ts

@@ -23,6 +23,14 @@ import * as dotenv from 'dotenv';
 import { z } from 'zod/v4';
 import { OpenRouter, ToolType } from '../src/index.js';
 
+// Type declaration for ShadowRealm (TC39 Stage 3 proposal)
+// See: https://tc39.es/proposal-shadowrealm/
+declare class ShadowRealm {
+  constructor();
+  evaluate(sourceText: string): unknown;
+  importValue(specifier: string, bindingName: string): Promise<unknown>;
+}
+
 dotenv.config();
 
 const client = new OpenRouter({
@@ -168,21 +176,28 @@ async function generatorToolExample() {
  *
  * ShadowRealm provides a secure, isolated JavaScript execution environment
  * that prevents access to the host realm's globals (no access to DOM, fetch,
- * filesystem, etc.). This makes it safe for evaluating untrusted expressions.
+ * filesystem, etc.). Combined with input validation, this makes it safe for
+ * evaluating untrusted math expressions.
+ *
+ * Note: ShadowRealm isolates from host APIs but does not prevent DoS vectors
+ * like infinite loops. For production use, consider additional safeguards.
  *
  * Browser support: Chrome 124+, Edge 124+, Firefox 128+, Safari 18+
  * Node.js support: Available behind --experimental-shadow-realm flag (v19+)
  * See: https://tc39.es/proposal-shadowrealm/
  */
-async function safeEvaluateMath(expression: string): Promise<number> {
-  // ShadowRealm is a TC39 Stage 3 proposal for isolated JavaScript execution
-  // It creates a separate realm with its own global object, preventing access
-  // to the host environment's APIs (no DOM, no Node.js APIs, no fetch, etc.)
+function safeEvaluateMath(expression: string): number {
+  // Only allow digits, whitespace, basic operators, decimal point, and parentheses
+  if (!/^[\d\s+\-*/.()]+$/.test(expression)) {
+    throw new Error('Expression contains invalid characters');
+  }
+
+  // ShadowRealm creates a separate realm with its own global object, preventing
+  // access to the host environment's APIs (no DOM, no Node.js APIs, no fetch, etc.)
   const realm = new ShadowRealm();
 
-  // The expression is evaluated in complete isolation - even if malicious code
-  // is injected, it cannot access anything outside the shadow realm
-  const result = await realm.evaluate(`(${expression})`);
+  // The expression is evaluated in complete isolation
+  const result = realm.evaluate(expression);
 
   if (typeof result !== 'number' || !Number.isFinite(result)) {
     throw new Error('Expression did not evaluate to a finite number');
@@ -233,7 +248,7 @@ async function manualToolExample() {
 
       // Safely evaluate the math expression using ShadowRealm
       try {
-        const _result = await safeEvaluateMath(expression);
+        const _result = safeEvaluateMath(expression);
       } catch (_error) {}
     }
   }