feat: expose execution stats from V8 isolates

Return cpuTime, wallTime, and heap statistics from isolated-vm in
ExecuteResult.stats so consumers can record OTel metrics without the
library depending on OTel itself. Also expose requestCount on the
bridge function for per-execution request counting.

Author: robinbraemer

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robinbraemer/codemode",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Code Mode MCP tools from OpenAPI specs. Two tools (search + execute) replace hundreds of individual MCP tools.",
   "type": "module",
   "main": "./dist/index.js",

src/executor/isolated-vm.ts

@@ -1,4 +1,4 @@
-import type { Executor, ExecuteResult, SandboxOptions } from "../types.js";
+import type { Executor, ExecuteResult, ExecuteStats, SandboxOptions } from "../types.js";
 
 /**
  * Executor implementation using isolated-vm (V8 isolates).
@@ -123,11 +123,14 @@ export class IsolatedVMExecutor implements Executor {
         }),
       ]);
 
-      return { result };
+      const stats = captureStats(isolate);
+      return { result, stats };
     } catch (err) {
+      const stats = captureStats(isolate);
       return {
         result: undefined,
         error: err instanceof Error ? err.message : String(err),
+        stats,
       };
     } finally {
       context?.release();
@@ -138,6 +141,42 @@ export class IsolatedVMExecutor implements Executor {
   }
 }
 
+/**
+ * Capture execution stats from an isolate before it is disposed.
+ * Safe to call even if the isolate is already disposed (returns zeroed stats).
+ */
+function captureStats(isolate: { isDisposed: boolean; cpuTime: bigint; wallTime: bigint; getHeapStatisticsSync(): Record<string, number> }): ExecuteStats {
+  if (isolate.isDisposed) {
+    return {
+      cpuTimeMs: 0,
+      wallTimeMs: 0,
+      heapUsedBytes: 0,
+      heapTotalBytes: 0,
+      externalBytes: 0,
+      heapSizeLimitBytes: 0,
+      totalPhysicalBytes: 0,
+      availableBytes: 0,
+      executableBytes: 0,
+      mallocedBytes: 0,
+      peakMallocedBytes: 0,
+    };
+  }
+  const heap = isolate.getHeapStatisticsSync();
+  return {
+    cpuTimeMs: Number(isolate.cpuTime) / 1e6,
+    wallTimeMs: Number(isolate.wallTime) / 1e6,
+    heapUsedBytes: heap.used_heap_size ?? 0,
+    heapTotalBytes: heap.total_heap_size ?? 0,
+    externalBytes: heap.externally_allocated_size ?? 0,
+    heapSizeLimitBytes: heap.heap_size_limit ?? 0,
+    totalPhysicalBytes: heap.total_physical_size ?? 0,
+    availableBytes: heap.total_available_size ?? 0,
+    executableBytes: heap.total_heap_size_executable ?? 0,
+    mallocedBytes: heap.malloced_memory ?? 0,
+    peakMallocedBytes: heap.peak_malloced_memory ?? 0,
+  };
+}
+
 function isNamespaceWithMethods(value: unknown): boolean {
   return (
     typeof value === "object" &&

src/index.ts

@@ -6,6 +6,7 @@ export type {
   CodeModeOptions,
   Executor,
   ExecuteResult,
+  ExecuteStats,
   OpenAPISpec,
   RequestHandler,
   SandboxOptions,
@@ -20,7 +21,7 @@ export { createExecutor } from "./executor/auto.js";
 
 // Request bridge (for advanced usage / custom request handling)
 export { createRequestBridge } from "./request-bridge.js";
-export type { SandboxRequestOptions, SandboxResponse } from "./request-bridge.js";
+export type { SandboxRequestOptions, SandboxResponse, RequestBridgeFn } from "./request-bridge.js";
 
 // Spec processing
 export { resolveRefs, processSpec, extractTags, extractServerBasePath } from "./spec.js";

src/request-bridge.ts

@@ -170,18 +170,24 @@ function filterHeaders(
  * Creates the `request()` function that gets injected into the execute sandbox.
  * Bridges sandbox API calls to the host request handler (Hono app.request, fetch, etc.).
  */
+/** Bridge function with an exposed request count. */
+export type RequestBridgeFn = ((options: SandboxRequestOptions) => Promise<SandboxResponse>) & {
+  /** Number of requests made through this bridge instance. */
+  readonly requestCount: number;
+};
+
 export function createRequestBridge(
   handler: RequestHandler,
   baseUrl: string,
   options: RequestBridgeOptions = {},
-): (options: SandboxRequestOptions) => Promise<SandboxResponse> {
+): RequestBridgeFn {
   const maxRequests = options.maxRequests ?? DEFAULT_MAX_REQUESTS;
   const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
   const allowedHeaders = options.allowedHeaders;
 
   let requestCount = 0;
 
-  return async (opts: SandboxRequestOptions): Promise<SandboxResponse> => {
+  const bridge = async (opts: SandboxRequestOptions): Promise<SandboxResponse> => {
     const { method, path, query, body, headers } = opts;
 
     // Validate request count
@@ -256,4 +262,11 @@ export function createRequestBridge(
       body: responseBody,
     };
   };
+
+  Object.defineProperty(bridge, 'requestCount', {
+    get: () => requestCount,
+    enumerable: true,
+  });
+
+  return bridge as RequestBridgeFn;
 }

src/types.ts

@@ -1,9 +1,39 @@
+/**
+ * Execution statistics captured from the V8 isolate.
+ */
+export interface ExecuteStats {
+  /** CPU time consumed by the isolate in milliseconds */
+  cpuTimeMs: number;
+  /** Wall-clock time of the execution in milliseconds */
+  wallTimeMs: number;
+  /** V8 heap used by the isolate in bytes (at end of execution) */
+  heapUsedBytes: number;
+  /** V8 heap total allocated by the isolate in bytes */
+  heapTotalBytes: number;
+  /** Memory allocated outside V8 heap (ArrayBuffers etc.) that counts against memoryLimit */
+  externalBytes: number;
+  /** The configured memory limit in bytes — useful for "% of limit used" dashboards */
+  heapSizeLimitBytes: number;
+  /** OS-level committed memory in bytes */
+  totalPhysicalBytes: number;
+  /** Remaining bytes before OOM */
+  availableBytes: number;
+  /** Size of JIT-compiled code in bytes */
+  executableBytes: number;
+  /** V8 internal malloc'd memory in bytes */
+  mallocedBytes: number;
+  /** Peak V8 internal malloc'd memory in bytes */
+  peakMallocedBytes: number;
+}
+
 /**
  * Result from executing sandboxed code.
  */
 export interface ExecuteResult {
   result: unknown;
   error?: string;
+  /** Execution statistics from the isolate. Always present, even on error. */
+  stats: ExecuteStats;
 }
 
 /**