From fe4e8862d6c25e91161a7e432e6a954dd9158f2a Mon Sep 17 00:00:00 2001
From: Aadarsh Mahesh K <aadarshmahk@gmail.com>
Date: Wed, 28 Oct 2026 10:45:00 +0530
Subject: [PATCH 1/2] feat(transforms): implement code-mode transform and
 quickjs worker pool

---
 nitrostack/transforms/__init__.py             |   2 +
 nitrostack/transforms/code_mode/__init__.py   |  35 ++
 .../transforms/code_mode/destructive_guard.py |  46 +++
 .../transforms/code_mode/guest_evaluator.py   | 190 +++++++++
 .../transforms/code_mode/legible_error.py     |  43 ++
 .../transforms/code_mode/sandbox_interface.py |  22 +
 .../transforms/code_mode/synthetic_tools.py   | 147 +++++++
 nitrostack/transforms/code_mode/transform.py  | 141 +++++++
 nitrostack/transforms/code_mode/types.py      |  69 ++++
 .../transforms/code_mode/worker_pool.py       | 240 +++++++++++
 pyproject.toml                                |   4 +
 tests/test_transforms_code_mode.py            | 385 ++++++++++++++++++
 uv.lock                                       |  38 +-
 13 files changed, 1355 insertions(+), 7 deletions(-)
 create mode 100644 nitrostack/transforms/code_mode/__init__.py
 create mode 100644 nitrostack/transforms/code_mode/destructive_guard.py
 create mode 100644 nitrostack/transforms/code_mode/guest_evaluator.py
 create mode 100644 nitrostack/transforms/code_mode/legible_error.py
 create mode 100644 nitrostack/transforms/code_mode/sandbox_interface.py
 create mode 100644 nitrostack/transforms/code_mode/synthetic_tools.py
 create mode 100644 nitrostack/transforms/code_mode/transform.py
 create mode 100644 nitrostack/transforms/code_mode/types.py
 create mode 100644 nitrostack/transforms/code_mode/worker_pool.py
 create mode 100644 tests/test_transforms_code_mode.py

diff --git a/nitrostack/transforms/__init__.py b/nitrostack/transforms/__init__.py
index a97d8c4..54e764d 100644
--- a/nitrostack/transforms/__init__.py
+++ b/nitrostack/transforms/__init__.py
@@ -13,9 +13,11 @@
 )
 from nitrostack.transforms.validation import ToolArgumentError, validate_tool_arguments
 from nitrostack.transforms.synthetic import SyntheticTool
+from nitrostack.transforms.code_mode import CodeModeTransform
 
 __all__ = [
     "CatalogTransform", "McpTransform", "McpTransformBase", "TransformContext",
     "TransformError", "TransformPipeline", "TransformRegistry",
     "ToolArgumentError", "validate_tool_arguments", "active_bypass", "bypassing", "SyntheticTool",
+    "CodeModeTransform",
 ]
\ No newline at end of file
diff --git a/nitrostack/transforms/code_mode/__init__.py b/nitrostack/transforms/code_mode/__init__.py
new file mode 100644
index 0000000..6d45e45
--- /dev/null
+++ b/nitrostack/transforms/code_mode/__init__.py
@@ -0,0 +1,35 @@
+"""Code Mode transform for NitroStack."""
+from __future__ import annotations
+
+from nitrostack.transforms.code_mode.destructive_guard import (
+    DestructiveToolError,
+    assert_tool_allowed,
+    is_destructive_tool,
+)
+from nitrostack.transforms.code_mode.legible_error import format_legible_error
+from nitrostack.transforms.code_mode.sandbox_interface import SandboxProtocol, ToolsApi
+from nitrostack.transforms.code_mode.transform import CodeModeTransform
+from nitrostack.transforms.code_mode.types import (
+    CodeModeLimits,
+    ExecuteScriptInput,
+    GetSchemaInput,
+    SandboxExecutionResult,
+    SearchToolsInput,
+)
+from nitrostack.transforms.code_mode.worker_pool import WorkerPool
+
+__all__ = [
+    "CodeModeTransform",
+    "CodeModeLimits",
+    "SandboxExecutionResult",
+    "SandboxProtocol",
+    "ToolsApi",
+    "WorkerPool",
+    "is_destructive_tool",
+    "assert_tool_allowed",
+    "DestructiveToolError",
+    "format_legible_error",
+    "SearchToolsInput",
+    "GetSchemaInput",
+    "ExecuteScriptInput",
+]
diff --git a/nitrostack/transforms/code_mode/destructive_guard.py b/nitrostack/transforms/code_mode/destructive_guard.py
new file mode 100644
index 0000000..7db9d9e
--- /dev/null
+++ b/nitrostack/transforms/code_mode/destructive_guard.py
@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class DestructiveToolError(Exception):
+    """Raised when a destructive tool is called while allowDestructive is false."""
+    pass
+
+
+def _get_annotation(annotations: Any, *keys: str) -> Optional[bool]:
+    if annotations is None:
+        return None
+    for k in keys:
+        if isinstance(annotations, dict):
+            if k in annotations:
+                return annotations[k]
+        elif hasattr(annotations, k):
+            return getattr(annotations, k)
+    return None
+
+
+def is_destructive_tool(tool: Any) -> bool:
+    """A tool is destructive unless readOnlyHint is true or destructiveHint is explicitly false."""
+    annotations = getattr(tool, "annotations", None)
+    if annotations is None and hasattr(tool, "config"):
+        annotations = getattr(tool.config, "annotations", None)
+
+    read_only = _get_annotation(annotations, "readOnlyHint", "read_only_hint", "read_only")
+    if read_only is True:
+        return False
+
+    destructive = _get_annotation(annotations, "destructiveHint", "destructive_hint")
+    if destructive is False:
+        return False
+
+    return True
+
+
+def assert_tool_allowed(tool: Any, allow_destructive: bool) -> None:
+    """Reject tool if destructive and allow_destructive is False."""
+    if not allow_destructive and is_destructive_tool(tool):
+        name = getattr(tool, "name", str(tool))
+        raise DestructiveToolError(
+            f"Tool '{name}' is destructive and cannot be executed in code-mode when allowDestructive is false."
+        )
diff --git a/nitrostack/transforms/code_mode/guest_evaluator.py b/nitrostack/transforms/code_mode/guest_evaluator.py
new file mode 100644
index 0000000..8ef57db
--- /dev/null
+++ b/nitrostack/transforms/code_mode/guest_evaluator.py
@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Dict, List, Optional
+from multiprocessing.connection import Connection
+
+from nitrostack.transforms.code_mode.legible_error import format_legible_error
+from nitrostack.transforms.code_mode.types import CodeModeLimits, SandboxExecutionResult
+
+logger = logging.getLogger(__name__)
+
+JS_PRELUDE = """
+const console = {
+    log: (...args) => { __nitrostack_log('info', __formatArgs(args)); },
+    info: (...args) => { __nitrostack_log('info', __formatArgs(args)); },
+    warn: (...args) => { __nitrostack_log('warn', __formatArgs(args)); },
+    error: (...args) => { __nitrostack_log('error', __formatArgs(args)); }
+};
+
+function __formatArgs(args) {
+    return args.map(a => {
+        if (typeof a === 'object' && a !== null) {
+            try { return JSON.stringify(a); } catch(e) { return String(a); }
+        }
+        return String(a);
+    }).join(' ');
+}
+
+const tools = new Proxy({
+    call(name, args) {
+        const payload = JSON.stringify(args || {});
+        const resStr = __nitrostack_call_tool(String(name), payload);
+        const parsed = JSON.parse(resStr);
+        if (parsed && parsed.__nitrostack_error) {
+            const err = new Error(parsed.__nitrostack_error);
+            err.name = parsed.__nitrostack_error_type || 'Error';
+            throw err;
+        }
+        return parsed.__nitrostack_value;
+    }
+}, {
+    get(target, prop) {
+        if (prop in target) return target[prop];
+        return function(args) {
+            return target.call(prop, args);
+        };
+    }
+});
+
+const call_tool = (name, args) => tools.call(name, args);
+const call = (name, args) => tools.call(name, args);
+"""
+
+
+def get_quickjs_module():
+    try:
+        import quickjs
+        return quickjs
+    except ImportError as exc:
+        raise RuntimeError(
+            "The 'quickjs' package is required for Code Mode. "
+            "Install it with: pip install 'nitrostack[code-mode]'"
+        ) from exc
+
+
+def worker_process_main(conn: Connection) -> None:
+    """Main loop for isolated worker process."""
+    quickjs = get_quickjs_module()
+    conn.send({"type": "ready"})
+
+    while True:
+        try:
+            if not conn.poll(None):
+                break
+            msg = conn.recv()
+        except (EOFError, KeyboardInterrupt):
+            break
+
+        cmd = msg.get("cmd")
+        if cmd == "shutdown":
+            break
+
+        if cmd == "run":
+            code = msg["code"]
+            limits_dict = msg["limits"]
+            memory_limit_mb = limits_dict.get("memory_limit_mb", 100)
+
+            ctx = quickjs.Context()
+            memory_limit_bytes = int(memory_limit_mb * 1024 * 1024)
+            ctx.set_memory_limit(memory_limit_bytes)
+
+            logs: List[str] = []
+            tool_call_count = 0
+
+            def log_bridge(level: str, message: str) -> None:
+                logs.append(f"[{level}] {message}")
+
+            def tool_call_bridge(name: str, args_json: str) -> str:
+                nonlocal tool_call_count
+                tool_call_count += 1
+                try:
+                    conn.send({
+                        "type": "tool_call",
+                        "name": name,
+                        "args_json": args_json,
+                        "call_index": tool_call_count,
+                    })
+                    response = conn.recv()
+                    if response.get("status") == "error":
+                        return json.dumps({
+                            "__nitrostack_error": response.get("error", "Tool execution error"),
+                            "__nitrostack_error_type": response.get("error_type", "Error"),
+                        })
+                    return json.dumps({
+                        "__nitrostack_value": response.get("value")
+                    })
+                except Exception as e:
+                    return json.dumps({
+                        "__nitrostack_error": format_legible_error(e),
+                        "__nitrostack_error_type": type(e).__name__,
+                    })
+
+            ctx.add_callable("__nitrostack_log", log_bridge)
+            ctx.add_callable("__nitrostack_call_tool", tool_call_bridge)
+
+            # Evaluate prelude
+            ctx.eval(JS_PRELUDE)
+
+            start_time = time.perf_counter()
+            success = False
+            value = None
+            error = None
+
+            try:
+                try:
+                    raw_result = ctx.eval(code)
+                except quickjs.JSException as exc:
+                    if "return not in a function" in str(exc):
+                        wrapped = "(function() {\n" + code + "\n})()"
+                        raw_result = ctx.eval(wrapped)
+                    else:
+                        raise
+
+                if hasattr(raw_result, "json"):
+                    try:
+                        value = json.loads(raw_result.json())
+                    except Exception:
+                        value = str(raw_result)
+                else:
+                    value = raw_result
+
+                success = True
+            except quickjs.JSException as exc:
+                err_str = str(exc)
+                if "out of memory" in err_str:
+                    error = f"MemoryLimitExceededError: Script exceeded memory limit of {memory_limit_mb}MB."
+                else:
+                    error = format_legible_error(exc)
+            except Exception as exc:
+                error = format_legible_error(exc)
+            finally:
+                duration_ms = (time.perf_counter() - start_time) * 1000.0
+                memory_used_mb = 0.0
+                try:
+                    mem_info = ctx.memory()
+                    if isinstance(mem_info, dict):
+                        used_bytes = mem_info.get("memory_used_size", 0)
+                    else:
+                        used_bytes = getattr(mem_info, "memory_used_size", 0)
+                    memory_used_mb = used_bytes / (1024 * 1024)
+                except Exception:
+                    pass
+
+                try:
+                    ctx.gc()
+                except Exception:
+                    pass
+
+            conn.send({
+                "type": "run_result",
+                "success": success,
+                "value": value,
+                "error": error,
+                "logs": logs,
+                "tool_call_count": tool_call_count,
+                "duration_ms": duration_ms,
+                "memory_used_mb": memory_used_mb,
+            })
diff --git a/nitrostack/transforms/code_mode/legible_error.py b/nitrostack/transforms/code_mode/legible_error.py
new file mode 100644
index 0000000..903bbe5
--- /dev/null
+++ b/nitrostack/transforms/code_mode/legible_error.py
@@ -0,0 +1,43 @@
+"""Format legible error messages for models without leaking host paths or stack frames."""
+from __future__ import annotations
+
+import re
+
+_HOST_PATH_RE = re.compile(
+    r"(?:/[a-zA-Z0-9_\-\.]+)+|(?:[a-zA-Z]:\\[a-zA-Z0-9_\-\.\\]+)"
+)
+
+# Match Python traceback line patterns
+_PY_TRACEBACK_LINE_RE = re.compile(
+    r"^\s*File\s+\".*?\",\s+line\s+\d+.*$",
+    re.MULTILINE
+)
+
+
+def format_legible_error(exc: BaseException | str) -> str:
+    """Format an error message so it is readable (message and location) and leaks no host paths or stack frames."""
+    raw = str(exc)
+
+    # Clean up input markers
+    raw = raw.replace("<eval>", "<script>").replace("<input>", "<script>")
+
+    # Remove python traceback lines
+    lines = []
+    for line in raw.splitlines():
+        if _PY_TRACEBACK_LINE_RE.match(line):
+            continue
+        if "Traceback (most recent call last):" in line:
+            continue
+        lines.append(line)
+
+    cleaned = "\n".join(lines).strip()
+
+    # Scrub any host filesystem paths that may remain
+    def _path_replacer(match: re.Match) -> str:
+        matched = match.group(0)
+        if "<script>" in matched:
+            return matched
+        return "<sanitized-path>"
+
+    cleaned = _HOST_PATH_RE.sub(_path_replacer, cleaned)
+    return cleaned or "ScriptExecutionError: Unknown error occurred."
diff --git a/nitrostack/transforms/code_mode/sandbox_interface.py b/nitrostack/transforms/code_mode/sandbox_interface.py
new file mode 100644
index 0000000..55cc875
--- /dev/null
+++ b/nitrostack/transforms/code_mode/sandbox_interface.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from nitrostack.transforms.code_mode.types import CodeModeLimits, SandboxExecutionResult
+
+
+@runtime_checkable
+class ToolsApi(Protocol):
+    async def call(self, name: str, arguments: dict[str, Any]) -> Any:
+        ...
+
+
+@runtime_checkable
+class SandboxProtocol(Protocol):
+    async def run(
+        self,
+        code: str,
+        tools_api: Any,
+        limits: CodeModeLimits,
+    ) -> SandboxExecutionResult:
+        ...
diff --git a/nitrostack/transforms/code_mode/synthetic_tools.py b/nitrostack/transforms/code_mode/synthetic_tools.py
new file mode 100644
index 0000000..7b9e3b7
--- /dev/null
+++ b/nitrostack/transforms/code_mode/synthetic_tools.py
@@ -0,0 +1,147 @@
+"""Synthetic tools factory and handlers for Code Mode."""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set
+
+from nitrostack.transforms.code_mode.destructive_guard import assert_tool_allowed
+from nitrostack.transforms.code_mode.types import (
+    CodeModeLimits,
+    ExecuteScriptInput,
+    GetSchemaInput,
+    SearchToolsInput,
+)
+from nitrostack.transforms.synthetic import SyntheticTool
+from nitrostack.transforms.transform import TransformContext
+
+if TYPE_CHECKING:
+    from nitrostack.transforms.code_mode.transform import CodeModeTransform
+
+
+class BoundToolsApi:
+    """Tools API exposed to the sandboxed runtime during script execution."""
+
+    def __init__(
+        self,
+        transform: "CodeModeTransform",
+        ctx: TransformContext,
+        limits: CodeModeLimits,
+    ) -> None:
+        self.transform = transform
+        self.ctx = ctx
+        self.limits = limits
+        self.tool_call_count = 0
+
+    async def call(self, name: str, arguments: Dict[str, Any]) -> Any:
+        self.tool_call_count += 1
+        if self.tool_call_count > self.limits.max_tool_calls:
+            raise RuntimeError(f"Tool call limit exceeded ({self.limits.max_tool_calls}).")
+
+        target = (name or "").strip()
+        if target in self.transform.synthetic_names:
+            raise ValueError(f"Cannot invoke meta-tool '{target}' from code-mode script.")
+
+        # Check destructive guard before execution
+        real_tool = self.transform.get_real_tool(target)
+        if real_tool is not None:
+            assert_tool_allowed(real_tool, self.limits.allow_destructive)
+
+        # Route through TransformContext.call_tool
+        # Re-enters the app pipeline so guards and validation run for the real tool,
+        # and CodeModeTransform is bypassed for this nested call.
+        res = await self.ctx.call_tool(target, arguments, caller=self.transform.name)
+        return self.transform.unwrap_tool_result(res)
+
+
+def create_code_mode_tools(transform: "CodeModeTransform") -> Dict[str, SyntheticTool]:
+    """Create the synthetic search, get_schema, and execute tools."""
+
+    async def handle_search(args: SearchToolsInput, ctx: TransformContext) -> Dict[str, Any]:
+        catalog = transform.get_real_tools()
+        query = (args.query or "").strip().lower()
+
+        results = []
+        for t in catalog:
+            name = getattr(t, "name", "")
+            description = getattr(t, "description", "") or ""
+            if not query or query in name.lower() or query in description.lower():
+                results.append({
+                    "name": name,
+                    "description": description,
+                })
+
+        return {
+            "query": args.query,
+            "total_tools": len(catalog),
+            "matches": len(results),
+            "tools": results,
+        }
+
+    async def handle_get_schema(args: GetSchemaInput, ctx: TransformContext) -> Dict[str, Any]:
+        catalog = {getattr(t, "name", ""): t for t in transform.get_real_tools()}
+        names_to_fetch = set()
+        if args.name:
+            names_to_fetch.add(args.name.strip())
+        if args.names:
+            names_to_fetch.update(n.strip() for n in args.names if n.strip())
+
+        schemas: Dict[str, Any] = {}
+        for name in names_to_fetch:
+            if name in catalog:
+                t = catalog[name]
+                schema = None
+                if hasattr(t, "model_dump"):
+                    try:
+                        schema = t.model_dump(by_alias=True).get("inputSchema")
+                    except Exception:
+                        pass
+                if schema is None:
+                    schema = getattr(t, "inputSchema", None) or getattr(t, "input_schema", None)
+                if schema is None and hasattr(t, "input_model"):
+                    schema = t.input_model.model_json_schema()
+
+                annotations = getattr(t, "annotations", None)
+                if annotations is not None and hasattr(annotations, "model_dump"):
+                    annotations_dump = annotations.model_dump(by_alias=True, exclude_none=True)
+                else:
+                    annotations_dump = annotations
+
+                schemas[name] = {
+                    "name": name,
+                    "description": getattr(t, "description", "") or "",
+                    "inputSchema": schema,
+                    "annotations": annotations_dump,
+                }
+            else:
+                schemas[name] = {"error": f"Tool '{name}' not found."}
+
+        return {"schemas": schemas}
+
+    async def handle_execute(args: ExecuteScriptInput, ctx: TransformContext) -> Dict[str, Any]:
+        tools_api = BoundToolsApi(transform, ctx, transform.limits)
+        result = await transform.sandbox.run(args.code, tools_api, transform.limits)
+        return result.to_dict()
+
+    return {
+        transform.search_tool_name: SyntheticTool(
+            name=transform.search_tool_name,
+            description="Search available tools in the catalog by query, or list all tools if query is empty.",
+            input_model=SearchToolsInput,
+            handler=handle_search,
+            read_only=True,
+        ),
+        transform.get_schema_tool_name: SyntheticTool(
+            name=transform.get_schema_tool_name,
+            description="Get the input JSON schema and parameter specifications for one or more tools.",
+            input_model=GetSchemaInput,
+            handler=handle_get_schema,
+            read_only=True,
+        ),
+        transform.execute_tool_name: SyntheticTool(
+            name=transform.execute_tool_name,
+            description="Execute JavaScript code in an isolated sandbox with access to tools API.",
+            input_model=ExecuteScriptInput,
+            handler=handle_execute,
+            read_only=False,
+        ),
+    }
diff --git a/nitrostack/transforms/code_mode/transform.py b/nitrostack/transforms/code_mode/transform.py
new file mode 100644
index 0000000..e5db438
--- /dev/null
+++ b/nitrostack/transforms/code_mode/transform.py
@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Set
+
+import mcp.types as types
+
+from nitrostack.transforms.code_mode.synthetic_tools import create_code_mode_tools
+from nitrostack.transforms.code_mode.types import CodeModeLimits
+from nitrostack.transforms.code_mode.worker_pool import WorkerPool
+from nitrostack.transforms.synthetic import SyntheticTool
+from nitrostack.transforms.transform import CatalogTransform, NextResolver, TransformContext
+
+logger = logging.getLogger(__name__)
+
+
+class CodeModeTransform(CatalogTransform):
+    """Replaces the catalog with synthetic tools (search, get_schema, execute) for Code Mode."""
+
+    name = "code_mode"
+
+    def __init__(
+        self,
+        *,
+        name: Optional[str] = None,
+        search_tool_name: str = "search",
+        get_schema_tool_name: str = "get_schema",
+        execute_tool_name: str = "execute",
+        limits: Optional[CodeModeLimits] = None,
+        sandbox: Optional[Any] = None,
+        always_visible: Iterable[str] = (),
+        timeout_ms: Optional[int] = None,
+        memory_limit_mb: Optional[int] = None,
+        max_tool_calls: Optional[int] = None,
+        allow_destructive: Optional[bool] = None,
+        worker_pool_size: Optional[int] = None,
+    ) -> None:
+        if name:
+            self.name = name
+
+        # Validate unique tool names
+        tool_names = [search_tool_name, get_schema_tool_name, execute_tool_name]
+        if len(set(tool_names)) != len(tool_names) or any(not n.strip() for n in tool_names):
+            raise ValueError("search, get_schema, and execute tool names must be non-empty and unique.")
+
+        self.search_tool_name = search_tool_name
+        self.get_schema_tool_name = get_schema_tool_name
+        self.execute_tool_name = execute_tool_name
+        self.synthetic_names: Set[str] = set(tool_names)
+        self.always_visible = frozenset(always_visible)
+
+        # Configure limits
+        if limits is not None:
+            self.limits = limits
+        else:
+            self.limits = CodeModeLimits(
+                timeout_ms=timeout_ms if timeout_ms is not None else 30000,
+                memory_limit_mb=memory_limit_mb if memory_limit_mb is not None else 100,
+                max_tool_calls=max_tool_calls if max_tool_calls is not None else 50,
+                allow_destructive=allow_destructive if allow_destructive is not None else False,
+                worker_pool_size=worker_pool_size if worker_pool_size is not None else 4,
+            )
+
+        self._registry: Any = None
+        self._sandbox = sandbox
+        self._synthetic: Dict[str, SyntheticTool] = create_code_mode_tools(self)
+
+    @property
+    def sandbox(self) -> Any:
+        if self._sandbox is None:
+            self._sandbox = WorkerPool(self.limits)
+        return self._sandbox
+
+    def on_register(self, registry: Any) -> None:
+        self._registry = registry
+
+    async def dispose(self) -> None:
+        if self._sandbox is not None and hasattr(self._sandbox, "dispose"):
+            await self._sandbox.dispose()
+
+    def synthetic_tools(self) -> List[SyntheticTool]:
+        return list(self._synthetic.values())
+
+    def get_real_tools(self) -> List[Any]:
+        if self._registry is None:
+            return []
+        return [
+            t for t in self._registry.list_tools()
+            if getattr(t, "name", "") not in self.synthetic_names
+        ]
+
+    def get_real_tool(self, name: str) -> Optional[Any]:
+        for t in self.get_real_tools():
+            if getattr(t, "name", "") == name:
+                return t
+        return None
+
+    def unwrap_tool_result(self, res: Any) -> Any:
+        """Unwrap CallToolResult into a python value or parsed json if applicable."""
+        if isinstance(res, types.CallToolResult):
+            is_err = getattr(res, "is_error", getattr(res, "isError", False))
+            if is_err:
+                err_text = ""
+                content = getattr(res, "content", []) or []
+                for c in content:
+                    if hasattr(c, "text"):
+                        err_text += c.text
+                raise RuntimeError(err_text or "Tool call reported an error.")
+
+            structured = getattr(res, "structured_content", getattr(res, "structuredContent", None))
+            if structured is not None:
+                return structured
+
+            content = getattr(res, "content", []) or []
+            if content:
+                for c in content:
+                    if hasattr(c, "text") and c.text:
+                        try:
+                            return json.loads(c.text)
+                        except Exception:
+                            return c.text
+            return None
+        return res
+
+    def apply_transform(self, tools: Sequence[Any], ctx: TransformContext) -> List[Any]:
+        visible = []
+        for t in tools:
+            name = getattr(t, "name", "")
+            if name in self.synthetic_names:
+                continue
+            if name in self.always_visible:
+                visible.append(t)
+        return [s.to_mcp_tool() for s in self._synthetic.values()] + visible
+
+    async def resolve_tool(
+        self, name: str, next: NextResolver, ctx: TransformContext
+    ) -> Optional[Any]:
+        if name in self._synthetic:
+            return self._synthetic[name]
+        return await next(name)
diff --git a/nitrostack/transforms/code_mode/types.py b/nitrostack/transforms/code_mode/types.py
new file mode 100644
index 0000000..05dd068
--- /dev/null
+++ b/nitrostack/transforms/code_mode/types.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, Field
+
+
+DEFAULT_TIMEOUT_MS = 30000
+DEFAULT_MEMORY_LIMIT_MB = 100
+MAX_MEMORY_LIMIT_MB = 128
+DEFAULT_MAX_TOOL_CALLS = 50
+DEFAULT_ALLOW_DESTRUCTIVE = False
+DEFAULT_POOL_SIZE = 4
+
+
+@dataclass
+class CodeModeLimits:
+    timeout_ms: int = DEFAULT_TIMEOUT_MS
+    memory_limit_mb: int = DEFAULT_MEMORY_LIMIT_MB
+    max_tool_calls: int = DEFAULT_MAX_TOOL_CALLS
+    allow_destructive: bool = DEFAULT_ALLOW_DESTRUCTIVE
+    worker_pool_size: int = DEFAULT_POOL_SIZE
+
+    def __post_init__(self) -> None:
+        if self.memory_limit_mb > MAX_MEMORY_LIMIT_MB:
+            self.memory_limit_mb = MAX_MEMORY_LIMIT_MB
+        if self.memory_limit_mb <= 0:
+            raise ValueError("memory_limit_mb must be positive")
+        if self.timeout_ms <= 0:
+            raise ValueError("timeout_ms must be positive")
+        if self.max_tool_calls < 0:
+            raise ValueError("max_tool_calls must be non-negative")
+        if self.worker_pool_size <= 0:
+            raise ValueError("worker_pool_size must be positive")
+
+
+@dataclass
+class SandboxExecutionResult:
+    success: bool
+    value: Any = None
+    error: Optional[str] = None
+    logs: List[str] = field(default_factory=list)
+    tool_call_count: int = 0
+    duration_ms: float = 0.0
+    memory_used_mb: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "success": self.success,
+            "value": self.value,
+            "error": self.error,
+            "logs": self.logs,
+            "toolCallCount": self.tool_call_count,
+            "durationMs": round(self.duration_ms, 2),
+            "memoryUsedMb": round(self.memory_used_mb, 3),
+        }
+
+
+class SearchToolsInput(BaseModel):
+    query: str = Field(default="", description="Search query to filter tools, or empty to list all.")
+
+
+class GetSchemaInput(BaseModel):
+    name: Optional[str] = Field(default=None, description="Exact name of tool to get schema for.")
+    names: Optional[List[str]] = Field(default=None, description="List of tool names to get schemas for.")
+
+
+class ExecuteScriptInput(BaseModel):
+    code: str = Field(..., description="JavaScript code to execute in the isolated sandbox.")
diff --git a/nitrostack/transforms/code_mode/worker_pool.py b/nitrostack/transforms/code_mode/worker_pool.py
new file mode 100644
index 0000000..3ad7924
--- /dev/null
+++ b/nitrostack/transforms/code_mode/worker_pool.py
@@ -0,0 +1,240 @@
+"""Worker pool managing isolated worker processes for Code Mode."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import multiprocessing as mp
+from multiprocessing.connection import Connection
+from multiprocessing.process import BaseProcess
+import time
+from typing import Any, Dict, List, Optional
+
+from nitrostack.transforms.code_mode.guest_evaluator import (
+    get_quickjs_module,
+    worker_process_main,
+)
+from nitrostack.transforms.code_mode.sandbox_interface import SandboxProtocol
+from nitrostack.transforms.code_mode.types import CodeModeLimits, SandboxExecutionResult
+
+logger = logging.getLogger(__name__)
+
+
+class _WorkerSlot:
+    """Manages an individual worker subprocess."""
+
+    def __init__(self) -> None:
+        self.process: Optional[BaseProcess] = None
+        self.conn: Optional[Connection] = None
+        self._start()
+
+    def _start(self) -> None:
+        parent_conn, child_conn = mp.Pipe(duplex=True)
+        ctx = mp.get_context("spawn")
+        p = ctx.Process(target=worker_process_main, args=(child_conn,), daemon=True)
+        p.start()
+        child_conn.close()
+        self.process = p
+        self.conn = parent_conn
+        if parent_conn.poll(10.0):
+            try:
+                msg = parent_conn.recv()
+                if msg.get("type") != "ready":
+                    logger.warning("Unexpected worker initial message: %s", msg)
+            except Exception as e:
+                logger.warning("Error receiving worker ready signal: %s", e)
+        else:
+            logger.error("Worker process failed to become ready within 10s")
+
+    def is_alive(self) -> bool:
+        return (
+            self.conn is not None
+            and self.process is not None
+            and self.process.is_alive()
+        )
+
+    def ensure_started(self) -> None:
+        if not self.is_alive():
+            self.recycle()
+
+    def terminate(self) -> None:
+        if self.conn:
+            try:
+                self.conn.close()
+            except Exception:
+                pass
+            self.conn = None
+        if self.process:
+            try:
+                self.process.kill()
+                self.process.join(timeout=1.0)
+            except Exception:
+                pass
+            self.process = None
+
+    def recycle(self) -> None:
+        self.terminate()
+        try:
+            self._start()
+        except Exception as exc:
+            logger.error("Failed to start worker process during recycle: %s", exc)
+            self.conn = None
+            self.process = None
+
+
+class WorkerPool(SandboxProtocol):
+    """Maintains a pool of isolated worker processes with concurrency and recovery."""
+
+    def __init__(self, limits: Optional[CodeModeLimits] = None) -> None:
+        get_quickjs_module()  # Verify dependency is installed
+        self.limits = limits or CodeModeLimits()
+        self.pool_size = self.limits.worker_pool_size
+        self._queue: asyncio.Queue[_WorkerSlot] = asyncio.Queue()
+        self._all_slots: List[_WorkerSlot] = []
+        self._disposed = False
+
+        for _ in range(self.pool_size):
+            slot = _WorkerSlot()
+            self._all_slots.append(slot)
+            self._queue.put_nowait(slot)
+
+    async def run(
+        self,
+        code: str,
+        tools_api: Any,
+        limits: Optional[CodeModeLimits] = None,
+    ) -> SandboxExecutionResult:
+        if self._disposed:
+            raise RuntimeError("Worker pool has been disposed.")
+
+        effective_limits = limits or self.limits
+        timeout_seconds = effective_limits.timeout_ms / 1000.0
+
+        slot = await self._queue.get()
+        if self._disposed:
+            raise RuntimeError("Worker pool has been disposed.")
+
+        slot.ensure_started()
+        if slot.conn is None:
+            raise RuntimeError("Worker process connection is unavailable.")
+
+        start_time = time.perf_counter()
+
+        try:
+            slot.conn.send({
+                "cmd": "run",
+                "code": code,
+                "limits": {
+                    "timeout_ms": effective_limits.timeout_ms,
+                    "memory_limit_mb": effective_limits.memory_limit_mb,
+                    "max_tool_calls": effective_limits.max_tool_calls,
+                    "allow_destructive": effective_limits.allow_destructive,
+                },
+            })
+
+            # Process messages until run_result or timeout
+            while True:
+                # Poll connection in executor with remaining timeout
+                elapsed = time.perf_counter() - start_time
+                remaining = max(0.01, timeout_seconds - elapsed)
+
+                def check_poll(conn: Connection, timeout: float) -> bool:
+                    return conn.poll(timeout)
+
+                loop = asyncio.get_running_loop()
+                has_msg = await asyncio.wait_for(
+                    loop.run_in_executor(None, check_poll, slot.conn, remaining),
+                    timeout=remaining + 0.5,
+                )
+
+                if not has_msg:
+                    raise asyncio.TimeoutError()
+
+                msg = slot.conn.recv()
+                msg_type = msg.get("type")
+
+                if msg_type == "tool_call":
+                    tool_name = msg["name"]
+                    args_json = msg.get("args_json", "{}")
+                    try:
+                        args = json.loads(args_json) if args_json else {}
+                    except Exception:
+                        args = {}
+
+                    try:
+                        if hasattr(tools_api, "call"):
+                            call_fn = getattr(tools_api, "call")
+                            res = call_fn(tool_name, args)
+                            val = await res if inspect.isawaitable(res) else res
+                        elif callable(tools_api):
+                            res = tools_api(tool_name, args)
+                            val = await res if inspect.isawaitable(res) else res
+                        else:
+                            raise RuntimeError("Tools API is not callable.")
+
+                        if slot.conn is not None:
+                            slot.conn.send({"status": "ok", "value": val})
+                    except Exception as exc:
+                        if slot.conn is not None:
+                            slot.conn.send({
+                                "status": "error",
+                                "error": str(exc),
+                                "error_type": type(exc).__name__,
+                            })
+
+                elif msg_type == "run_result":
+                    # Success or handled script error
+                    return SandboxExecutionResult(
+                        success=msg["success"],
+                        value=msg["value"],
+                        error=msg["error"],
+                        logs=msg["logs"],
+                        tool_call_count=msg["tool_call_count"],
+                        duration_ms=msg["duration_ms"],
+                        memory_used_mb=msg["memory_used_mb"],
+                    )
+
+        except asyncio.TimeoutError:
+            # Kill worker process and replace it in the pool
+            duration_ms = (time.perf_counter() - start_time) * 1000.0
+            try:
+                slot.recycle()
+            except Exception as e:
+                logger.error("Error recycling worker slot after timeout: %s", e)
+            return SandboxExecutionResult(
+                success=False,
+                error=f"TimeoutError: Script execution timed out after {effective_limits.timeout_ms}ms.",
+                duration_ms=duration_ms,
+            )
+        except Exception as exc:
+            # Worker crashed or unexpected error
+            duration_ms = (time.perf_counter() - start_time) * 1000.0
+            try:
+                slot.recycle()
+            except Exception as e:
+                logger.error("Error recycling worker slot after error: %s", e)
+            return SandboxExecutionResult(
+                success=False,
+                error=f"RuntimeError: Worker execution failed: {exc}",
+                duration_ms=duration_ms,
+            )
+        finally:
+            if not self._disposed:
+                if not slot.is_alive():
+                    try:
+                        slot.recycle()
+                    except Exception as e:
+                        logger.error("Failed to recycle dead worker slot: %s", e)
+                self._queue.put_nowait(slot)
+
+    async def dispose(self) -> None:
+        self._disposed = True
+        while not self._queue.empty():
+            try:
+                self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+        for slot in self._all_slots:
+            slot.terminate()
+        self._all_slots.clear()
diff --git a/pyproject.toml b/pyproject.toml
index 6f480c5..5c91683 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,7 +21,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+code-mode = [
+    "quickjs>=1.19.4",
+]
 dev = [
+    "quickjs>=1.19.4",
     "pytest-cov>=4.1.0",
     "pytest>=8",
     "pytest-asyncio>=0.23",
diff --git a/tests/test_transforms_code_mode.py b/tests/test_transforms_code_mode.py
new file mode 100644
index 0000000..f7b94ac
--- /dev/null
+++ b/tests/test_transforms_code_mode.py
@@ -0,0 +1,385 @@
+import asyncio
+import os
+import sys
+import pytest
+from pydantic import BaseModel
+
+import mcp.types as types
+from nitrostack import ExecutionContext, injectable, module, tool, ToolAnnotations
+from nitrostack.testing import NitroTestingModule
+from nitrostack.transforms.code_mode import (
+    CodeModeLimits,
+    CodeModeTransform,
+    WorkerPool,
+    format_legible_error,
+)
+
+try:
+    import quickjs
+    HAS_QUICKJS = True
+except ImportError:
+    HAS_QUICKJS = False
+
+requires_quickjs = pytest.mark.skipif(
+    not HAS_QUICKJS,
+    reason="The 'quickjs' package is required for Code Mode. Install it with: pip install 'nitrostack[code-mode]'",
+)
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+class CalcInput(BaseModel):
+    a: int
+    b: int
+
+
+class WriteInput(BaseModel):
+    key: str
+    val: str
+
+
+guard_call_count = 0
+
+
+class TrackingGuard:
+    async def can_activate(self, context):
+        global guard_call_count
+        guard_call_count += 1
+        return True
+
+
+@injectable()
+class SampleController:
+    @tool(
+        name="add",
+        description="Add two numbers together",
+        input_schema=CalcInput,
+        annotations=ToolAnnotations(read_only_hint=True, destructive_hint=False),
+    )
+    async def add(self, input: CalcInput, context: ExecutionContext) -> int:
+        return input.a + input.b
+
+    @tool(
+        name="multiply",
+        description="Multiply two numbers together",
+        input_schema=CalcInput,
+        annotations=ToolAnnotations(read_only_hint=True, destructive_hint=False),
+    )
+    async def multiply(self, input: CalcInput, context: ExecutionContext) -> int:
+        return input.a * input.b
+
+    @tool(
+        name="destructive_wipe",
+        description="Destructive wipe operation",
+        input_schema=WriteInput,
+        annotations=ToolAnnotations(read_only_hint=False, destructive_hint=True),
+    )
+    async def destructive_wipe(self, input: WriteInput, context: ExecutionContext) -> str:
+        return f"wiped {input.key}"
+
+
+@module(name="sample", controllers=[SampleController])
+class SampleModule:
+    pass
+
+
+@requires_quickjs
+def test_cannot_reach_filesystem():
+    """A script cannot reach the filesystem."""
+    transform = CodeModeTransform()
+    res = run(transform.sandbox.run("typeof fs === 'undefined' ? 'isolated' : fs.readFileSync('/etc/passwd')", None, transform.limits))
+    assert res.success is True
+    assert res.value == "isolated"
+
+    res2 = run(transform.sandbox.run("fs.readFileSync('/etc/passwd')", None, transform.limits))
+    assert res2.success is False
+    assert "ReferenceError" in res2.error
+
+
+@requires_quickjs
+def test_cannot_reach_network():
+    """A script cannot reach network."""
+    transform = CodeModeTransform()
+    res = run(transform.sandbox.run("typeof fetch === 'undefined' && typeof XMLHttpRequest === 'undefined' && typeof WebSocket === 'undefined'", None, transform.limits))
+    assert res.success is True
+    assert res.value is True
+
+    res2 = run(transform.sandbox.run("fetch('https://google.com')", None, transform.limits))
+    assert res2.success is False
+    assert "ReferenceError" in res2.error
+
+
+@requires_quickjs
+def test_cannot_reach_environment_variables():
+    """A script cannot reach environment variables."""
+    transform = CodeModeTransform()
+    os.environ["SECRET_ENV_TOKEN"] = "supersecret123"
+    res = run(transform.sandbox.run("typeof process === 'undefined' ? 'no-process' : process.env.SECRET_ENV_TOKEN", None, transform.limits))
+    assert res.success is True
+    assert res.value == "no-process"
+
+    res2 = run(transform.sandbox.run("process.env", None, transform.limits))
+    assert res2.success is False
+    assert "ReferenceError" in res2.error
+
+
+@requires_quickjs
+def test_cannot_reach_host_modules():
+    """A script cannot reach host modules."""
+    transform = CodeModeTransform()
+    res = run(transform.sandbox.run("typeof require === 'undefined' && typeof __import__ === 'undefined'", None, transform.limits))
+    assert res.success is True
+    assert res.value is True
+
+    res2 = run(transform.sandbox.run("require('os')", None, transform.limits))
+    assert res2.success is False
+    assert "ReferenceError" in res2.error
+
+
+@requires_quickjs
+def test_infinite_loop_stops_within_timeout():
+    """An infinite loop stops within the limits."""
+    limits = CodeModeLimits(timeout_ms=200, memory_limit_mb=50, worker_pool_size=4)
+    pool = WorkerPool(limits)
+    try:
+        res = run(pool.run("while(true) {}", None, limits))
+        assert res.success is False
+        assert res.error is not None
+        assert "TimeoutError" in res.error or "timed out" in res.error
+    finally:
+        run(pool.dispose())
+
+
+@requires_quickjs
+def test_memory_bomb_stops_within_limits():
+    """A memory bomb stops within memory limits."""
+    limits = CodeModeLimits(timeout_ms=10000, memory_limit_mb=5, worker_pool_size=4)
+    pool = WorkerPool(limits)
+    try:
+        res = run(pool.run("let arr = []; while(true) { arr.push(new Array(50000).fill(1)); }", None, limits))
+        assert res.success is False
+        assert res.error is not None
+        assert "MemoryLimitExceededError" in res.error or "out of memory" in res.error
+    finally:
+        run(pool.dispose())
+
+
+@requires_quickjs
+def test_pool_keeps_serving_afterwards():
+    """The pool keeps serving afterwards following timeout and memory bomb errors."""
+    limits = CodeModeLimits(timeout_ms=5000, memory_limit_mb=5, worker_pool_size=4)
+    pool = WorkerPool(limits)
+    try:
+        timeout_limits = CodeModeLimits(timeout_ms=200, memory_limit_mb=5, worker_pool_size=4)
+        r1 = run(pool.run("while(true) {}", None, timeout_limits))
+        assert r1.success is False
+
+        r2 = run(pool.run("let arr = []; while(true) { arr.push(new Array(50000).fill(1)); }", None, limits))
+        assert r2.success is False
+
+        r3 = run(pool.run("const a = 10; const b = 20; a + b;", None, limits))
+        assert r3.success is True
+        assert r3.value == 30
+
+        r4 = run(pool.run("return 40 + 2;", None, limits))
+        assert r4.success is True
+        assert r4.value == 42
+    finally:
+        run(pool.dispose())
+
+
+@requires_quickjs
+def test_script_tool_calls_go_through_pipeline():
+    """Script tool calls invoke real tools through the pipeline."""
+    async def go():
+        transform = CodeModeTransform()
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+
+        script = """
+        const sum = tools.call('add', { a: 10, b: 5 });
+        const product = call_tool('multiply', { a: sum, b: 2 });
+        return { sum, product };
+        """
+        res = await h.call_tool("execute", {"code": script})
+        return res
+
+    result = run(go())
+    assert isinstance(result, dict)
+    assert result["success"] is True
+    assert result["value"] == {"sum": 15, "product": 30}
+    assert result["toolCallCount"] == 2
+
+
+@requires_quickjs
+def test_destructive_guard():
+    """A tool is destructive unless readOnlyHint is true or destructiveHint is explicitly false.
+    Destructive tools are rejected unless allowDestructive is set.
+    """
+    async def test_rejected():
+        transform = CodeModeTransform(allow_destructive=False)
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+
+        script = "tools.call('destructive_wipe', { key: 'test', val: 'val' });"
+        return await h.call_tool("execute", {"code": script})
+
+    res = run(test_rejected())
+    assert isinstance(res, dict)
+    assert res["success"] is False
+    assert "DestructiveToolError" in res["error"]
+    assert "destructive" in res["error"]
+
+    async def test_allowed():
+        transform = CodeModeTransform(allow_destructive=True)
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+
+        script = "tools.call('destructive_wipe', { key: 'test', val: 'val' });"
+        return await h.call_tool("execute", {"code": script})
+
+    res2 = run(test_allowed())
+    assert isinstance(res2, dict)
+    assert res2["success"] is True
+    assert res2["value"] == "wiped test"
+
+
+def test_import_nitrostack_works_without_extra():
+    """import nitrostack works without extra installed."""
+    import nitrostack
+    assert nitrostack.__name__ == "nitrostack"
+
+
+@requires_quickjs
+def test_synthetic_tools_catalog_and_discovery():
+    """Search and get_schema synthetic tools work correctly."""
+    async def go():
+        transform = CodeModeTransform()
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+
+        srv = h.app.mcp_server
+        assert srv is not None
+        tools_list = (await srv.request_handlers[types.ListToolsRequest](
+            types.ListToolsRequest(method="tools/list")
+        )).root.tools
+
+        names = [t.name for t in tools_list]
+        assert set(names) == {"search", "get_schema", "execute"}
+
+        search_res = await h.call_tool("search", {"query": "add"})
+        assert search_res["matches"] == 1
+        assert search_res["tools"][0]["name"] == "add"
+
+        schema_res = await h.call_tool("get_schema", {"name": "add"})
+        assert "add" in schema_res["schemas"]
+        assert "properties" in schema_res["schemas"]["add"]["inputSchema"]
+
+        all_res = await h.call_tool("search", {"query": ""})
+        assert all_res["total_tools"] == 3
+
+    run(go())
+
+
+@requires_quickjs
+def test_configurable_synthetic_tool_names():
+    """Synthetic tool names can be configured."""
+    async def go():
+        transform = CodeModeTransform(
+            search_tool_name="find_tools",
+            get_schema_tool_name="tool_schema",
+            execute_tool_name="run_code",
+        )
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+        srv = h.app.mcp_server
+        assert srv is not None
+        tools_list = (await srv.request_handlers[types.ListToolsRequest](
+            types.ListToolsRequest(method="tools/list")
+        )).root.tools
+        names = [t.name for t in tools_list]
+        assert set(names) == {"find_tools", "tool_schema", "run_code"}
+
+    run(go())
+
+
+@requires_quickjs
+def test_max_tool_calls_limit():
+    """Tool calls exceeding max_tool_calls limit are rejected."""
+    async def go():
+        transform = CodeModeTransform(max_tool_calls=2)
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+
+        script = """
+        tools.call('add', { a: 1, b: 2 });
+        tools.call('add', { a: 3, b: 4 });
+        tools.call('add', { a: 5, b: 6 }); // 3rd call exceeds limit
+        """
+        res = await h.call_tool("execute", {"code": script})
+        return res
+
+    res = run(go())
+    assert isinstance(res, dict)
+    assert res["success"] is False
+    assert "Tool call limit exceeded" in res["error"]
+
+
+def test_legible_error_scrubbing():
+    """Errors returned to the model are readable and do not leak host paths or stack frames."""
+    raw_error = f"Error in /home/aadarshm07/nitrostack/secret/path.py at line 42\n  File \"/home/user/app.py\", line 10, in execute\nReferenceError: 'x' is not defined"
+    cleaned = format_legible_error(raw_error)
+    assert "/home/aadarshm07" not in cleaned
+    assert "File \"/home" not in cleaned
+    assert "ReferenceError: 'x' is not defined" in cleaned
+
+
+@requires_quickjs
+def test_console_logs_captured():
+    """console.log, console.warn, console.error are captured into logs array."""
+    async def go():
+        transform = CodeModeTransform()
+        h = await NitroTestingModule.create(SampleModule, transforms=[transform])
+
+        script = """
+        console.log("Starting calculation");
+        console.warn("Watch out for precision");
+        console.error("Test error message");
+        return 100;
+        """
+        res = await h.call_tool("execute", {"code": script})
+        return res
+
+    res = run(go())
+    assert isinstance(res, dict)
+    assert res["success"] is True
+    assert res["value"] == 100
+    logs = res["logs"]
+    assert any("[info] Starting calculation" in l for l in logs)
+    assert any("[warn] Watch out for precision" in l for l in logs)
+    assert any("[error] Test error message" in l for l in logs)
+
+
+@requires_quickjs
+def test_worker_slot_recovers_if_connection_none():
+    """If a slot connection or process is killed/None, it recovers automatically."""
+    limits = CodeModeLimits(worker_pool_size=1)
+    pool = WorkerPool(limits)
+    try:
+        slot = pool._all_slots[0]
+        slot.terminate()
+        assert slot.conn is None
+
+        res = run(pool.run("return 123 * 2;", None, limits))
+        assert res.success is True
+        assert res.value == 246
+    finally:
+        run(pool.dispose())
+
+
+@requires_quickjs
+def test_worker_pool_disposed_raises_runtime_error():
+    """Running against a disposed pool raises RuntimeError, not AttributeError on NoneType."""
+    limits = CodeModeLimits(worker_pool_size=1)
+    pool = WorkerPool(limits)
+    run(pool.dispose())
+
+    with pytest.raises(RuntimeError, match="disposed"):
+        run(pool.run("1 + 1", None, limits))
+
diff --git a/uv.lock b/uv.lock
index 4c444be..34b63e6 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,10 +1,10 @@
 version = 1
-revision = 5
+revision = 3
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.14'",
     "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'emscripten'",
-    "python_full_version == '3.11.*' or (python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten')",
+    "(python_full_version >= '3.11' and python_full_version < '3.14' and sys_platform != 'emscripten') or (python_full_version == '3.11.*' and sys_platform == 'emscripten')",
     "python_full_version < '3.11'",
 ]
 
@@ -399,7 +399,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -442,8 +442,8 @@ name = "httpcore2"
 version = "2.12.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "h11" },
-    { name = "truststore" },
+    { name = "h11", marker = "python_full_version < '3.12' or python_full_version >= '3.14' or sys_platform != 'emscripten'" },
+    { name = "truststore", marker = "python_full_version < '3.12' or python_full_version >= '3.14' or sys_platform != 'emscripten'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/be/ad/f4f0e57345f1870f3e8cb624e058d7eca6e5a27d33bcc3311d9b618734cd/httpcore2-2.12.0.tar.gz", hash = "sha256:9293522bba0aa7c4c8e9e3f040c16575bd8868e155a77fa30c7a9085a5eae648", size = 67548, upload-time = "2026-08-18T13:22:08.211Z" }
 wheels = [
@@ -592,6 +592,9 @@ dependencies = [
 ]
 
 [package.optional-dependencies]
+code-mode = [
+    { name = "quickjs" },
+]
 dev = [
     { name = "httpx" },
     { name = "pytest" },
@@ -613,13 +616,14 @@ requires-dist = [
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.23" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.1.0" },
     { name = "pytest-timeout", marker = "extra == 'dev'", specifier = ">=2.3.0" },
+    { name = "quickjs", marker = "extra == 'code-mode'", specifier = ">=1.19.4" },
     { name = "starlette", specifier = ">=0.30.0" },
     { name = "tomli", marker = "python_full_version < '3.11'", specifier = ">=2.0.0" },
     { name = "tox", marker = "extra == 'dev'", specifier = ">=4.0.0" },
     { name = "uvicorn", specifier = ">=0.20.0" },
     { name = "watchfiles", specifier = ">=0.18.0" },
 ]
-provides-extras = ["dev"]
+provides-extras = ["code-mode", "dev"]
 
 [[package]]
 name = "opentelemetry-api"
@@ -943,6 +947,26 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/23/ed/4532e9388e65fa16b46776ef47ad631a64eda1631884488af707666350ed/pywin32-312-cp315-cp315-win_arm64.whl", hash = "sha256:a8597d28f267b39074aef51fa593530082b39cbe5a074226096857b1fed2dfb9", size = 6840337, upload-time = "2026-06-04T07:49:57.531Z" },
 ]
 
+[[package]]
+name = "quickjs"
+version = "1.19.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f1/a7/8fac2e213db8108d8108e9f1ee8d6c2abfcbe943238b0960585c26666862/quickjs-1.19.4.tar.gz", hash = "sha256:1205953abc24ff757f4a795304d5d61e4bf1e555c9ef6ec96a132d4b95535484", size = 456179, upload-time = "2023-11-19T10:06:39.445Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/67/1c/152eba405e315348f9028cd5be1c7206730a76474d1cdd911b5ad9c89d06/quickjs-1.19.4-cp310-cp310-macosx_11_0_x86_64.whl", hash = "sha256:19520c326e840ef4aa72298e49f60c8feffeaf33ac62fac74ed9130ed46e7cb6", size = 532527, upload-time = "2023-11-19T10:06:03.963Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/a5/2ea2a6fb7c5df83e4e6e02d713f31ed470d4c5c9ba45a0340fd04d217b67/quickjs-1.19.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:be7424b9af7853aaff930e3af2d1f2ebd83241cd2764abcea66247476a6d56d5", size = 2177974, upload-time = "2023-11-19T10:06:05.965Z" },
+    { url = "https://files.pythonhosted.org/packages/21/6a/a04a823c60bdc6b5f4cd38c3579cbfb73df5f6aeaab7ec781f69d35fc25f/quickjs-1.19.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9d579851d2a34be57b8adcc48e2b30d3f2e8b87a30898c90ebad440cefbda6f1", size = 2172385, upload-time = "2023-11-19T10:06:07.774Z" },
+    { url = "https://files.pythonhosted.org/packages/76/0c/92377aba51d068fd0a739905f642e38bd41b05c768ad200fbde65160414e/quickjs-1.19.4-cp310-cp310-win_amd64.whl", hash = "sha256:4bf4a6596dbc49dfc79ab15ca38bf2c300fbde7e45f5f63ba836d841e79df3e9", size = 382324, upload-time = "2023-11-19T10:06:09.767Z" },
+    { url = "https://files.pythonhosted.org/packages/65/f4/9edeafd79dd295d2f46c66b52c6b158263f5183e88ca6a29dd6a023c2184/quickjs-1.19.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:2272597b5fbe468a11803a700b1fc345df65d1bdba27dcde929c7d905e67e1e8", size = 1004505, upload-time = "2023-11-19T10:06:11.175Z" },
+    { url = "https://files.pythonhosted.org/packages/73/19/1cc58e237d935fd3b640f9d8ab4f21a43fcc5bf210ad3ca7c486aa9ca937/quickjs-1.19.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:845d0635f86b6168d819ef13d820dec07453e07b1ac735e0738d889c66762788", size = 2179366, upload-time = "2023-11-19T10:06:12.885Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/18/ef9346c67c26c8941523f2b840018319f0d5028dc34e267f5ea5279126f9/quickjs-1.19.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:93c32e0f55c9871beff92a020b852e9addc59480b596955a9d1d40f5cbde8c5a", size = 2173800, upload-time = "2023-11-19T10:06:14.411Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/2b/d365ae4066cd7d9b84c006080c73a66c49e2d54ec093c5813e1ba592e010/quickjs-1.19.4-cp311-cp311-win_amd64.whl", hash = "sha256:d730ccbf65040a246105cceaafff7da9c67fe7c4a0832489c0982c153161b83c", size = 382407, upload-time = "2023-11-19T10:06:15.816Z" },
+    { url = "https://files.pythonhosted.org/packages/95/4f/df90bde103703cd052fd76ad7bddfcb9a4f908ab6c940ad05fdb3997e173/quickjs-1.19.4-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:1bc38a840144a54e90668fb1f99441148429ab1d1b1355ecafbbe656eaeff788", size = 1004472, upload-time = "2023-11-19T10:06:17.453Z" },
+    { url = "https://files.pythonhosted.org/packages/26/59/1689a6f59f26d8f68c082dc6dfbbb38d9b7eaa3e243a775f8be2c876b561/quickjs-1.19.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:45d0e68570425d8322c48fb8989865df9b8c3e3ad3a01726151e0451d3c637eb", size = 2179639, upload-time = "2023-11-19T10:06:21.064Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/cd/8fd683236b976487bbd4c99e24334b25fc0542367164f2348bca08572490/quickjs-1.19.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ac4b6d40b90553e9b135b35b3eaca264d10cdf92bfafce36ed9fb9acfdc5b420", size = 2173664, upload-time = "2023-11-19T10:06:22.931Z" },
+    { url = "https://files.pythonhosted.org/packages/be/10/58064fe6beeb72c122f2ecb4729cf437055d89891d29cc2cd20ed88c1d66/quickjs-1.19.4-cp312-cp312-win_amd64.whl", hash = "sha256:3ebe018eaef1957a21264b98877c6217d7bfc4e28cbc5d87e75f879e1f45fc85", size = 382359, upload-time = "2023-11-19T10:06:25.343Z" },
+]
+
 [[package]]
 name = "referencing"
 version = "0.37.0"
@@ -1090,7 +1114,7 @@ source = { registry = "https://pypi.org/simple" }
 resolution-markers = [
     "python_full_version >= '3.14'",
     "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'emscripten'",
-    "python_full_version == '3.11.*' or (python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten')",
+    "(python_full_version >= '3.11' and python_full_version < '3.14' and sys_platform != 'emscripten') or (python_full_version == '3.11.*' and sys_platform == 'emscripten')",
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/aa/2a/9618a122aeb2a169a28b03889a2995fe297588964333d4a7d67bdf46e147/rpds_py-2026.6.3.tar.gz", hash = "sha256:1cebd1337c242e4ec2293e541f712b2da849b29f48f0c293684b71c0632625d4", size = 64051, upload-time = "2026-06-30T07:17:53.009Z" }
 wheels = [

From 705a751e5cb34aebd4801e8c0ca71c65df276788 Mon Sep 17 00:00:00 2001
From: Aadarsh Mahesh K <aadarshmahk@gmail.com>
Date: Wed, 28 Oct 2026 16:51:17 +0530
Subject: [PATCH 2/2] feat: enforce script timeout during tool calls and revert
 uv.lock downgrade

---
 .../transforms/code_mode/worker_pool.py       | 32 +++++++++++++------
 tests/test_transforms_code_mode.py            | 21 +++++++++++-
 uv.lock                                       | 12 +++----
 3 files changed, 48 insertions(+), 17 deletions(-)

diff --git a/nitrostack/transforms/code_mode/worker_pool.py b/nitrostack/transforms/code_mode/worker_pool.py
index 3ad7924..4178181 100644
--- a/nitrostack/transforms/code_mode/worker_pool.py
+++ b/nitrostack/transforms/code_mode/worker_pool.py
@@ -137,7 +137,9 @@ async def run(
             while True:
                 # Poll connection in executor with remaining timeout
                 elapsed = time.perf_counter() - start_time
-                remaining = max(0.01, timeout_seconds - elapsed)
+                remaining = timeout_seconds - elapsed
+                if remaining <= 0:
+                    raise asyncio.TimeoutError()
 
                 def check_poll(conn: Connection, timeout: float) -> bool:
                     return conn.poll(timeout)
@@ -163,18 +165,28 @@ def check_poll(conn: Connection, timeout: float) -> bool:
                         args = {}
 
                     try:
-                        if hasattr(tools_api, "call"):
-                            call_fn = getattr(tools_api, "call")
-                            res = call_fn(tool_name, args)
-                            val = await res if inspect.isawaitable(res) else res
-                        elif callable(tools_api):
-                            res = tools_api(tool_name, args)
-                            val = await res if inspect.isawaitable(res) else res
-                        else:
-                            raise RuntimeError("Tools API is not callable.")
+                        elapsed = time.perf_counter() - start_time
+                        remaining_tool_time = timeout_seconds - elapsed
+                        if remaining_tool_time <= 0:
+                            raise asyncio.TimeoutError()
+
+                        async def _invoke_tool() -> Any:
+                            if hasattr(tools_api, "call"):
+                                call_fn = getattr(tools_api, "call")
+                                res = call_fn(tool_name, args)
+                                return await res if inspect.isawaitable(res) else res
+                            elif callable(tools_api):
+                                res = tools_api(tool_name, args)
+                                return await res if inspect.isawaitable(res) else res
+                            else:
+                                raise RuntimeError("Tools API is not callable.")
+
+                        val = await asyncio.wait_for(_invoke_tool(), timeout=remaining_tool_time)
 
                         if slot.conn is not None:
                             slot.conn.send({"status": "ok", "value": val})
+                    except asyncio.TimeoutError:
+                        raise
                     except Exception as exc:
                         if slot.conn is not None:
                             slot.conn.send({
diff --git a/tests/test_transforms_code_mode.py b/tests/test_transforms_code_mode.py
index f7b94ac..6b18121 100644
--- a/tests/test_transforms_code_mode.py
+++ b/tests/test_transforms_code_mode.py
@@ -1,6 +1,5 @@
 import asyncio
 import os
-import sys
 import pytest
 from pydantic import BaseModel
 
@@ -383,3 +382,23 @@ def test_worker_pool_disposed_raises_runtime_error():
     with pytest.raises(RuntimeError, match="disposed"):
         run(pool.run("1 + 1", None, limits))
 
+
+@requires_quickjs
+def test_timeout_applied_while_tool_call_in_progress():
+    """Script timeout is enforced while a slow tool call is in progress."""
+    async def slow_tool(name, args):
+        await asyncio.sleep(0.6)
+        return "done"
+
+    limits = CodeModeLimits(timeout_ms=50, worker_pool_size=1)
+    pool = WorkerPool(limits)
+    try:
+        res = run(pool.run("tools.call('slow', {})", slow_tool, limits))
+        assert res.success is False
+        assert res.error is not None
+        assert "TimeoutError" in res.error or "timed out" in res.error
+        # The script duration should be around 50ms, not 600ms+
+        assert res.duration_ms < 250
+    finally:
+        run(pool.dispose())
+
diff --git a/uv.lock b/uv.lock
index 34b63e6..e906362 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,10 +1,10 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.14'",
     "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'emscripten'",
-    "(python_full_version >= '3.11' and python_full_version < '3.14' and sys_platform != 'emscripten') or (python_full_version == '3.11.*' and sys_platform == 'emscripten')",
+    "python_full_version == '3.11.*' or (python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten')",
     "python_full_version < '3.11'",
 ]
 
@@ -399,7 +399,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -442,8 +442,8 @@ name = "httpcore2"
 version = "2.12.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "h11", marker = "python_full_version < '3.12' or python_full_version >= '3.14' or sys_platform != 'emscripten'" },
-    { name = "truststore", marker = "python_full_version < '3.12' or python_full_version >= '3.14' or sys_platform != 'emscripten'" },
+    { name = "h11" },
+    { name = "truststore" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/be/ad/f4f0e57345f1870f3e8cb624e058d7eca6e5a27d33bcc3311d9b618734cd/httpcore2-2.12.0.tar.gz", hash = "sha256:9293522bba0aa7c4c8e9e3f040c16575bd8868e155a77fa30c7a9085a5eae648", size = 67548, upload-time = "2026-08-18T13:22:08.211Z" }
 wheels = [
@@ -1114,7 +1114,7 @@ source = { registry = "https://pypi.org/simple" }
 resolution-markers = [
     "python_full_version >= '3.14'",
     "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'emscripten'",
-    "(python_full_version >= '3.11' and python_full_version < '3.14' and sys_platform != 'emscripten') or (python_full_version == '3.11.*' and sys_platform == 'emscripten')",
+    "python_full_version == '3.11.*' or (python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten')",
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/aa/2a/9618a122aeb2a169a28b03889a2995fe297588964333d4a7d67bdf46e147/rpds_py-2026.6.3.tar.gz", hash = "sha256:1cebd1337c242e4ec2293e541f712b2da849b29f48f0c293684b71c0632625d4", size = 64051, upload-time = "2026-06-30T07:17:53.009Z" }
 wheels = [