@robinbraemer/codemode 0.1.0 → 0.1.1

package/README.md

@@ -9,20 +9,33 @@ Instead of defining individual MCP tools for every API endpoint (`list-pods`, `c
 
 This is the same pattern [Cloudflare uses](https://blog.cloudflare.com/code-mode-mcp/) to expose 2,500+ API endpoints through just two MCP tools, reducing context window usage by 99.9%.
 
+## Try It
+
+Requires [mise](https://mise.jdx.dev/) for tooling (Node.js, pnpm, Task):
+
+```bash
+git clone https://github.com/cnap-tech/codemode.git
+cd codemode
+mise install   # installs Node 24, pnpm 10, Task
+task install   # installs dependencies
+task example   # runs the Petstore demo
+```
+
+Fetches the real Petstore OpenAPI spec from the web, then runs search + execute against a local Hono mock — no API keys needed.
+
 ## Install
 
 ```bash
-pnpm add codemode
+pnpm add @robinbraemer/codemode
 
-# Install a sandbox runtime (pick one):
-pnpm add isolated-vm       # V8 isolates — fastest, recommended
-pnpm add quickjs-emscripten # WASM — portable fallback
+# Install the sandbox runtime:
+pnpm add isolated-vm       # V8 isolates
 ```
 
 ## Quick Start
 
 ```typescript
-import { CodeMode } from 'codemode';
+import { CodeMode } from '@robinbraemer/codemode';
 import { Hono } from 'hono';
 
 const app = new Hono();
@@ -40,13 +53,15 @@ const codemode = new CodeMode({
 // The agent searches the spec to discover endpoints...
 const search = await codemode.callTool('search', {
   code: `async () => {
-    return Object.entries(spec.paths)
-      .filter(([p]) => p.includes('/clusters'))
-      .flatMap(([path, methods]) =>
-        Object.entries(methods)
-          .filter(([m]) => ['get','post','put','delete'].includes(m))
-          .map(([method, op]) => ({ method: method.toUpperCase(), path, summary: op.summary }))
-      );
+    const results = [];
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      for (const [method, op] of Object.entries(methods)) {
+        if (op.tags?.some(t => t.toLowerCase() === 'clusters')) {
+          results.push({ method: method.toUpperCase(), path, summary: op.summary });
+        }
+      }
+    }
+    return results;
   }`
 });
 
@@ -64,8 +79,8 @@ const result = await codemode.callTool('execute', {
 ```typescript
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CodeMode } from 'codemode';
-import { registerTools } from 'codemode/mcp';
+import { CodeMode } from '@robinbraemer/codemode';
+import { registerTools } from '@robinbraemer/codemode/mcp';
 
 const codemode = new CodeMode({
   spec: () => fetchOpenAPISpec(),
@@ -87,7 +102,8 @@ AI Agent
   ▼
 CodeMode MCP Server
   │
-  ├─ search(code) → runs JS with OpenAPI spec as a global
+  ├─ search(code) → runs JS with preprocessed OpenAPI spec
+  │   → all $refs resolved inline, only essential fields kept
   │   → agent discovers endpoints, schemas, parameters
   │
   └─ execute(code) → runs JS with injected request client
@@ -95,7 +111,7 @@ CodeMode MCP Server
       → no network hop, auth handled automatically
 ```
 
-All code runs in an isolated sandbox (V8 isolate or QuickJS WASM). The sandbox has zero I/O by default — no `require`, no `process`, no `fetch`, no filesystem. The only way to interact with the outside world is through the injected globals (`spec` for search, `{namespace}.request()` for execute).
+All code runs in an isolated V8 sandbox. The sandbox has zero I/O by default — no `require`, no `process`, no `fetch`, no filesystem. The only way to interact with the outside world is through the injected globals (`spec` for search, `{namespace}.request()` for execute).
 
 Each tool call gets a fresh sandbox with no state carried over between calls.
 
@@ -107,10 +123,23 @@ Each tool call gets a fresh sandbox with no state carried over between calls.
 |--------|------|---------|-------------|
 | `spec` | `OpenAPISpec \| () => OpenAPISpec \| Promise<OpenAPISpec>` | required | OpenAPI 3.x spec or async getter |
 | `request` | `(input, init?) => Response` | required | Fetch-compatible handler (`app.request.bind(app)` for Hono) |
-| `namespace` | `string` | `"api"` | Client name in sandbox (`api.request(...)`) |
+| `namespace` | `string` | `"api"` | Client name in sandbox (`api.request(...)`). Must be a valid JS identifier, not a reserved name. |
 | `baseUrl` | `string` | `"http://localhost"` | Base URL for relative paths |
-| `sandbox` | `{ memoryMB?, timeoutMs? }` | `{ 64, 30000 }` | Sandbox resource limits |
-| `executor` | `Executor` | auto-detect | Custom sandbox executor |
+| `sandbox` | `SandboxOptions` | see below | Sandbox resource limits |
+| `executor` | `Executor` | `IsolatedVMExecutor` | Custom sandbox executor |
+| `maxResponseTokens` | `number` | `25000` | Token limit for response truncation (0 to disable) |
+| `maxRequests` | `number` | `50` | Max requests per `execute()` call |
+| `maxResponseBytes` | `number` | `10485760` | Max response body size in bytes (10MB) |
+| `allowedHeaders` | `string[]` | `undefined` | Header whitelist. When unset, a blocklist strips `Authorization`, `Cookie`, `Host`, `X-Forwarded-*`, `Proxy-*`. |
+| `maxRefDepth` | `number` | `50` | Max `$ref` resolution depth |
+
+#### `SandboxOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `memoryMB` | `number` | `64` | V8 isolate memory limit |
+| `timeoutMs` | `number` | `30000` | CPU timeout in ms (caps pure compute) |
+| `wallTimeMs` | `number` | `60000` | Wall-clock timeout in ms (caps total elapsed time including async I/O) |
 
 ### Methods
 
@@ -142,24 +171,27 @@ Clean up sandbox resources.
 
 ### Inside `search`
 
-The `spec` global is the full OpenAPI 3.x document:
+The `spec` global is the preprocessed OpenAPI spec with all `$ref` pointers resolved inline:
 
 ```javascript
-// Find endpoints by keyword
+// Find endpoints by tag
 async () => {
-  return Object.entries(spec.paths)
-    .filter(([p]) => p.includes('/clusters'))
-    .flatMap(([path, methods]) =>
-      Object.entries(methods)
-        .filter(([m]) => ['get','post','put','delete','patch'].includes(m))
-        .map(([method, op]) => ({
-          method: method.toUpperCase(), path, summary: op.summary
-        }))
-    );
+  const results = [];
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const [method, op] of Object.entries(methods)) {
+      if (op.tags?.some(t => t.toLowerCase() === 'clusters')) {
+        results.push({ method: method.toUpperCase(), path, summary: op.summary });
+      }
+    }
+  }
+  return results;
 }
 
-// Get a specific schema
-async () => spec.components?.schemas?.Product
+// Get endpoint with requestBody schema (refs are already resolved)
+async () => {
+  const op = spec.paths['/v1/products']?.post;
+  return { summary: op?.summary, requestBody: op?.requestBody };
+}
 
 // Spec metadata
 async () => ({
@@ -186,11 +218,12 @@ async () => {
 
 // POST with body
 async () => {
-  return api.request({
+  const res = await api.request({
     method: "POST",
     path: "/v1/products",
     body: { name: "Redis", chart: "bitnami/redis" },
   });
+  return { status: res.status, body: res.body };
 }
 
 // Chain calls
@@ -217,33 +250,51 @@ async () => {
 
 **Response:** `{ status: number, headers: Record<string, string>, body: unknown }`
 
+## Spec Preprocessing
+
+CodeMode automatically preprocesses your OpenAPI spec before passing it to the search sandbox:
+
+- **`$ref` resolution** — all `$ref` pointers are resolved inline (circular refs become `{ $circular: ref }`)
+- **Field extraction** — only essential fields kept per operation: `summary`, `description`, `tags`, `operationId`, `parameters`, `requestBody`, `responses`
+- **Metadata preserved** — `info`, `servers`, and `components.schemas` are kept alongside processed paths
+
+You can also use the preprocessing utilities directly:
+
+```typescript
+import { resolveRefs, processSpec, extractTags } from '@robinbraemer/codemode';
+
+const processed = processSpec(rawSpec);
+const tags = extractTags(rawSpec);
+```
+
 ## Executors
 
-CodeMode auto-detects your installed sandbox runtime. You can also pass one explicitly:
+CodeMode uses `isolated-vm` (V8 isolates) for sandboxed execution. You can pass a custom instance:
 
 ```typescript
-import { CodeMode, IsolatedVMExecutor } from 'codemode';
+import { CodeMode, IsolatedVMExecutor } from '@robinbraemer/codemode';
 
 const codemode = new CodeMode({
   spec,
   request: handler,
-  executor: new IsolatedVMExecutor({ memoryMB: 128, timeoutMs: 60_000 }),
+  executor: new IsolatedVMExecutor({
+    memoryMB: 128,
+    timeoutMs: 60_000,   // CPU time limit
+    wallTimeMs: 120_000, // total elapsed time limit
+  }),
 });
 ```
 
 | Executor | Package | Performance | Portability |
 |----------|---------|-------------|-------------|
 | `IsolatedVMExecutor` | `isolated-vm` | Native V8 speed | Node.js |
-| `QuickJSExecutor` | `quickjs-emscripten` | ~3-5x slower (still fast) | Node.js, Bun, browsers |
-
-Both are optional peer dependencies. Install at least one.
 
 ### Custom Executor
 
 Implement the `Executor` interface to use your own sandbox:
 
 ```typescript
-import { CodeMode, type Executor, type ExecuteResult } from 'codemode';
+import { CodeMode, type Executor, type ExecuteResult } from '@robinbraemer/codemode';
 
 class MyExecutor implements Executor {
   async execute(code: string, globals: Record<string, unknown>): Promise<ExecuteResult> {

package/dist/{chunk-NSUQUO7S.js → chunk-M4AL5G4U.js}

@@ -2,31 +2,25 @@
 var IsolatedVMExecutor = class {
   memoryMB;
   timeoutMs;
+  wallTimeMs;
   constructor(options = {}) {
     this.memoryMB = options.memoryMB ?? 64;
     this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.wallTimeMs = options.wallTimeMs ?? 6e4;
   }
   async execute(code, globals) {
     const ivm = (await import("isolated-vm")).default ?? await import("isolated-vm");
     const isolate = new ivm.Isolate({ memoryLimit: this.memoryMB });
-    const logs = [];
+    let context;
     try {
-      const context = await isolate.createContext();
+      context = await isolate.createContext();
       const jail = context.global;
       await jail.set("global", jail.derefInto());
-      jail.setSync(
-        "__log",
-        new ivm.Callback((...args) => {
-          logs.push(
-            args.map((a) => typeof a === "string" ? a : stringify(a)).join(" ")
-          );
-        })
-      );
       await context.eval(`
         globalThis.console = {
-          log: (...args) => __log(...args),
-          warn: (...args) => __log(...args),
-          error: (...args) => __log(...args),
+          log: () => {},
+          warn: () => {},
+          error: () => {},
         };
       `);
       let refCounter = 0;
@@ -75,20 +69,31 @@ var IsolatedVMExecutor = class {
       }
       const wrappedCode = `(${code})()`;
       const script = await isolate.compileScript(wrappedCode);
-      const result = await script.run(context, {
-        timeout: this.timeoutMs,
-        promise: true,
-        copy: true
-      });
-      context.release();
-      return { result, logs };
+      let wallTimer;
+      const result = await Promise.race([
+        script.run(context, {
+          timeout: this.timeoutMs,
+          promise: true,
+          copy: true
+        }).finally(() => clearTimeout(wallTimer)),
+        new Promise((_, reject) => {
+          wallTimer = setTimeout(
+            () => reject(new Error("Wall-clock timeout exceeded")),
+            this.wallTimeMs
+          );
+          if (typeof wallTimer === "object" && wallTimer !== null && "unref" in wallTimer) {
+            wallTimer.unref();
+          }
+        })
+      ]);
+      return { result };
     } catch (err) {
       return {
         result: void 0,
-        error: err instanceof Error ? err.message : String(err),
-        logs
+        error: err instanceof Error ? err.message : String(err)
       };
     } finally {
+      context?.release();
       if (!isolate.isDisposed) {
         isolate.dispose();
       }
@@ -100,16 +105,8 @@ function isNamespaceWithMethods(value) {
     (v) => typeof v === "function"
   );
 }
-function stringify(value) {
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}
 
 export {
   IsolatedVMExecutor
 };
-//# sourceMappingURL=chunk-NSUQUO7S.js.map
+//# sourceMappingURL=chunk-M4AL5G4U.js.map

package/dist/chunk-M4AL5G4U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/executor/isolated-vm.ts"],"sourcesContent":["import type { Executor, ExecuteResult, SandboxOptions } from \"../types.js\";\n\n/**\n * Executor implementation using isolated-vm (V8 isolates).\n * Requires `isolated-vm` v6+ as a peer dependency.\n *\n * Each execute() call creates a fresh V8 isolate with its own heap — no state\n * leaks between calls. The sandbox has zero I/O capabilities by default (no\n * fetch, no fs, no require). The only way out is through injected host functions.\n */\nexport class IsolatedVMExecutor implements Executor {\n  private memoryMB: number;\n  private timeoutMs: number;\n  private wallTimeMs: number;\n\n  constructor(options: SandboxOptions = {}) {\n    this.memoryMB = options.memoryMB ?? 64;\n    this.timeoutMs = options.timeoutMs ?? 30_000;\n    this.wallTimeMs = options.wallTimeMs ?? 60_000;\n  }\n\n  async execute(\n    code: string,\n    globals: Record<string, unknown>,\n  ): Promise<ExecuteResult> {\n    // @ts-ignore — optional peer dependency\n    const ivm = (await import(\"isolated-vm\")).default ?? (await import(\"isolated-vm\"));\n    const isolate = new ivm.Isolate({ memoryLimit: this.memoryMB });\n\n    let context: Awaited<ReturnType<typeof isolate.createContext>> | undefined;\n    try {\n      context = await isolate.createContext();\n      const jail = context.global;\n      await jail.set(\"global\", jail.derefInto());\n\n      // No-op console — sandbox code should return data, not log it.\n      // Injecting a real console would create an OOM vector since logs\n      // accumulate in the host process outside the isolate memory limit.\n      await context.eval(`\n        globalThis.console = {\n          log: () => {},\n          warn: () => {},\n          error: () => {},\n        };\n      `);\n\n      // Inject globals — sequential awaits required: each jail.set/context.eval\n      // depends on prior state (ref counters, globalThis assignments).\n      /* oxlint-disable no-await-in-loop */\n      let refCounter = 0;\n      for (const [name, value] of Object.entries(globals)) {\n        if (typeof value === \"function\") {\n          // Async host function: set Reference, wrap with .apply() in isolate\n          const refName = `__ref${refCounter++}`;\n          await jail.set(refName, new ivm.Reference(value));\n          await context.eval(`\n            globalThis[${JSON.stringify(name)}] = function(...args) {\n              return ${refName}.apply(undefined, args, {\n                arguments: { copy: true },\n                result: { promise: true, copy: true },\n              });\n            };\n          `);\n        } else if (isNamespaceWithMethods(value)) {\n          // Namespace object with methods (e.g. { request: fn })\n          const ns = value as Record<string, unknown>;\n          let nsSetup = `globalThis[${JSON.stringify(name)}] = {};\\n`;\n\n          for (const [key, val] of Object.entries(ns)) {\n            if (typeof val === \"function\") {\n              const refName = `__ref${refCounter++}`;\n              await jail.set(refName, new ivm.Reference(val));\n              nsSetup += `\n                globalThis[${JSON.stringify(name)}][${JSON.stringify(key)}] = function(...args) {\n                  return ${refName}.apply(undefined, args, {\n                    arguments: { copy: true },\n                    result: { promise: true, copy: true },\n                  });\n                };\n              `;\n            }\n          }\n\n          // Inject non-function properties as JSON\n          const dataProps = Object.entries(ns).filter(([, v]) => typeof v !== \"function\");\n          if (dataProps.length > 0) {\n            const dataObj = Object.fromEntries(dataProps);\n            nsSetup += `Object.assign(globalThis[${JSON.stringify(name)}], ${JSON.stringify(dataObj)});\\n`;\n          }\n\n          await context.eval(nsSetup);\n        } else {\n          // Plain data: inject as JSON\n          await context.eval(\n            `globalThis[${JSON.stringify(name)}] = ${JSON.stringify(value)};`,\n          );\n        }\n      }\n      /* oxlint-enable no-await-in-loop */\n\n      // Execute the code with both CPU timeout and wall-clock timeout.\n      // The ivm timeout only covers CPU time; async host calls (request bridge)\n      // can stall indefinitely without a wall-clock guard.\n      const wrappedCode = `(${code})()`;\n      const script = await isolate.compileScript(wrappedCode);\n\n      let wallTimer: ReturnType<typeof setTimeout> | undefined;\n      const result = await Promise.race([\n        script.run(context, {\n          timeout: this.timeoutMs,\n          promise: true,\n          copy: true,\n        }).finally(() => clearTimeout(wallTimer)),\n        new Promise<never>((_, reject) => {\n          wallTimer = setTimeout(\n            () => reject(new Error(\"Wall-clock timeout exceeded\")),\n            this.wallTimeMs,\n          );\n          // Don't prevent process exit\n          if (typeof wallTimer === \"object\" && wallTimer !== null && \"unref\" in wallTimer) {\n            (wallTimer as { unref(): void }).unref();\n          }\n        }),\n      ]);\n\n      return { result };\n    } catch (err) {\n      return {\n        result: undefined,\n        error: err instanceof Error ? err.message : String(err),\n      };\n    } finally {\n      context?.release();\n      if (!isolate.isDisposed) {\n        isolate.dispose();\n      }\n    }\n  }\n}\n\nfunction isNamespaceWithMethods(value: unknown): boolean {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    !Array.isArray(value) &&\n    Object.values(value as Record<string, unknown>).some(\n      (v) => typeof v === \"function\",\n    )\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/{codemode-DbXujxeq.d.ts → codemode-C8y0tnb7.d.ts}

@@ -4,14 +4,12 @@
 interface ExecuteResult {
     result: unknown;
     error?: string;
-    logs: string[];
 }
 /**
  * Sandbox executor interface. Implement this to use a custom sandbox runtime.
  *
- * Built-in implementations:
+ * Built-in implementation:
  * - `IsolatedVMExecutor` (requires `isolated-vm` peer dependency)
- * - `QuickJSExecutor` (requires `quickjs-emscripten` peer dependency)
  */
 interface Executor {
     /**
@@ -33,8 +31,10 @@ interface Executor {
 interface SandboxOptions {
     /** Memory limit in MB (default: 64) */
     memoryMB?: number;
-    /** Execution timeout in ms (default: 30000) */
+    /** CPU timeout in ms — caps pure compute time (default: 30000) */
     timeoutMs?: number;
+    /** Wall-clock timeout in ms — caps total elapsed time including async I/O (default: 60000) */
+    wallTimeMs?: number;
 }
 /**
  * A fetch-compatible request handler.
@@ -95,10 +95,35 @@ interface CodeModeOptions {
      */
     sandbox?: SandboxOptions;
     /**
-     * Custom executor instance. If not provided, auto-detects
-     * isolated-vm or quickjs-emscripten from installed peer dependencies.
+     * Custom executor instance. If not provided, uses isolated-vm.
      */
     executor?: Executor;
+    /**
+     * Maximum tokens for response truncation.
+     * Default: 25000 (~100KB). Set to 0 to disable truncation.
+     */
+    maxResponseTokens?: number;
+    /**
+     * Maximum number of requests per execution.
+     * Default: 50.
+     */
+    maxRequests?: number;
+    /**
+     * Maximum response body size in bytes.
+     * Default: 10MB (10_485_760).
+     */
+    maxResponseBytes?: number;
+    /**
+     * Allowed headers whitelist. When set, only these headers are forwarded.
+     * When undefined, a default blocklist strips dangerous headers
+     * (Authorization, Cookie, Host, X-Forwarded-*, Proxy-*).
+     */
+    allowedHeaders?: string[];
+    /**
+     * Maximum $ref resolution depth.
+     * Default: 50.
+     */
+    maxRefDepth?: number;
 }
 /**
  * MCP tool definition (compatible with @modelcontextprotocol/sdk).
@@ -155,13 +180,18 @@ interface ToolCallResult {
  */
 declare class CodeMode {
     private specProvider;
-    private requestBridge;
     private namespace;
     private executor;
     private executorPromise;
     private options;
     private searchToolName;
     private executeToolName;
+    private maxResponseTokens;
+    private bridgeHandler;
+    private bridgeBaseUrl;
+    private bridgeOptions;
+    private processedSpec;
+    private specContext;
     constructor(options: CodeModeOptions);
     /**
      * Override the default tool names.
@@ -180,6 +210,7 @@ declare class CodeMode {
     /**
      * Execute a search against the OpenAPI spec.
      * The code runs in a sandbox with `spec` available as a global.
+     * All $refs are pre-resolved inline.
      */
     search(code: string): Promise<ToolCallResult>;
     /**
@@ -192,7 +223,13 @@ declare class CodeMode {
      */
     dispose(): void;
     private resolveSpec;
+    /**
+     * Get the processed spec (refs resolved, fields extracted).
+     * Caches the result after first call.
+     */
+    private getProcessedSpec;
     private getExecutor;
+    private formatResult;
 }
 
 export { CodeMode as C, type Executor as E, type OpenAPISpec as O, type RequestHandler as R, type SandboxOptions as S, type ToolCallResult as T, type ExecuteResult as a, type CodeModeOptions as b, type SpecProvider as c, type ToolDefinition as d };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as Executor, S as SandboxOptions, a as ExecuteResult, R as RequestHandler } from './codemode-DbXujxeq.js';
-export { C as CodeMode, b as CodeModeOptions, O as OpenAPISpec, c as SpecProvider, T as ToolCallResult, d as ToolDefinition } from './codemode-DbXujxeq.js';
+import { E as Executor, S as SandboxOptions, a as ExecuteResult, R as RequestHandler, O as OpenAPISpec } from './codemode-C8y0tnb7.js';
+export { C as CodeMode, b as CodeModeOptions, c as SpecProvider, T as ToolCallResult, d as ToolDefinition } from './codemode-C8y0tnb7.js';
 
 /**
  * Executor implementation using isolated-vm (V8 isolates).
@@ -12,32 +12,13 @@ export { C as CodeMode, b as CodeModeOptions, O as OpenAPISpec, c as SpecProvide
 declare class IsolatedVMExecutor implements Executor {
     private memoryMB;
     private timeoutMs;
+    private wallTimeMs;
     constructor(options?: SandboxOptions);
     execute(code: string, globals: Record<string, unknown>): Promise<ExecuteResult>;
 }
 
 /**
- * Executor implementation using quickjs-emscripten (QuickJS compiled to WASM).
- * Requires `quickjs-emscripten` as a peer dependency.
- *
- * Advantages over isolated-vm:
- * - Pure WASM, no native dependencies (works everywhere including Bun)
- * - WASM-level sandbox isolation
- *
- * Tradeoffs:
- * - ~3-5x slower than V8 for compute (negligible for API orchestration)
- * - Only one async suspension at a time per module
- */
-declare class QuickJSExecutor implements Executor {
-    private memoryBytes;
-    private timeoutMs;
-    constructor(options?: SandboxOptions);
-    execute(code: string, globals: Record<string, unknown>): Promise<ExecuteResult>;
-}
-
-/**
- * Auto-detect and create an executor from available peer dependencies.
- * Tries isolated-vm first, then quickjs-emscripten.
+ * Create an executor using the isolated-vm peer dependency.
  */
 declare function createExecutor(options?: SandboxOptions): Promise<Executor>;
 
@@ -60,10 +41,59 @@ interface SandboxResponse {
     headers: Record<string, string>;
     body: unknown;
 }
+/**
+ * Options for configuring the request bridge.
+ */
+interface RequestBridgeOptions {
+    /** Maximum number of requests per bridge instance. Default: 50. */
+    maxRequests?: number;
+    /** Maximum response body size in bytes. Default: 10MB. */
+    maxResponseBytes?: number;
+    /** Allowed headers whitelist. When undefined, uses default blocklist. */
+    allowedHeaders?: string[];
+}
 /**
  * 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.).
  */
-declare function createRequestBridge(handler: RequestHandler, baseUrl: string): (options: SandboxRequestOptions) => Promise<SandboxResponse>;
+declare function createRequestBridge(handler: RequestHandler, baseUrl: string, options?: RequestBridgeOptions): (options: SandboxRequestOptions) => Promise<SandboxResponse>;
+
+/**
+ * Recursively resolve all `$ref` pointers in an OpenAPI spec inline.
+ * Circular references are replaced with `{ $circular: ref }`.
+ *
+ * The `seen` set tracks the current ancestor chain only (not globally),
+ * so the same $ref used in sibling positions resolves correctly.
+ * A memoization cache avoids re-resolving the same $ref multiple times.
+ *
+ * @param maxDepth - Maximum $ref resolution depth (default: 50)
+ */
+declare function resolveRefs(obj: unknown, root: Record<string, unknown>, seen?: Set<string>, maxDepth?: number, _cache?: Map<string, unknown>): unknown;
+/**
+ * Extract the base path from the first server URL in the spec.
+ * e.g. "https://petstore.io/api/v3" → "/api/v3"
+ * e.g. "/api/v3" → "/api/v3"
+ * e.g. "https://api.example.com" → ""
+ */
+declare function extractServerBasePath(spec: OpenAPISpec): string;
+/**
+ * Process an OpenAPI spec into a simplified format for the search tool.
+ * Resolves all $refs inline and extracts only the fields needed for search.
+ * Prepends the server base path to all path keys so they're directly usable.
+ * Preserves info and components.schemas alongside processed paths.
+ *
+ * @param maxRefDepth - Maximum $ref resolution depth (default: 50)
+ */
+declare function processSpec(spec: OpenAPISpec, maxRefDepth?: number): Record<string, unknown>;
+/**
+ * Extract unique tags from the spec, sorted by frequency (most common first).
+ */
+declare function extractTags(spec: OpenAPISpec): string[];
+
+/**
+ * Truncate a response to fit within a token budget.
+ * Uses a ~4 chars/token estimate.
+ */
+declare function truncateResponse(content: unknown, maxTokens?: number): string;
 
-export { ExecuteResult, Executor, IsolatedVMExecutor, QuickJSExecutor, RequestHandler, SandboxOptions, type SandboxRequestOptions, type SandboxResponse, createExecutor, createRequestBridge };
+export { ExecuteResult, Executor, IsolatedVMExecutor, OpenAPISpec, RequestHandler, SandboxOptions, type SandboxRequestOptions, type SandboxResponse, createExecutor, createRequestBridge, extractServerBasePath, extractTags, processSpec, resolveRefs, truncateResponse };