Skip to content

Self-improving AI Employees for everyone

feat(code): add montyExecutor sandboxed-Python node (Pydantic Monty)

trohitg3896b8af1ce2
diff --git a/CLAUDE.md b/CLAUDE.md
index 3cb2d573..9c4112c1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1025,6 +1025,7 @@ Nodes that work BOTH as standalone workflow nodes AND as AI Agent tools. When co
- **whatsappSend**: Send WhatsApp messages (text, media, location, contact) to contacts, groups, or newsletter channels. Full schema for all message types.
- **whatsappDb**: Query WhatsApp database - chat history, contacts, groups, and newsletter channels with filtering and pagination.
- **pythonExecutor**: Execute Python code for calculations, data processing, and automation. Tool name: `python_code`. Available: math, json, datetime, Counter, defaultdict, random.
+- **montyExecutor**: Sandboxed Python via Pydantic Monty (`pydantic-monty`). Tool name: `sandboxed_python`. Deny-by-default with ENFORCED time/memory limits + dynamic `capabilities` (`http_get`/`workspace_read`/`workspace_write`). Supported subset only (no class/yield/with/match/random/collections).
- **javascriptExecutor**: Execute JavaScript code via persistent Node.js server for calculations, data processing, and JSON manipulation. Tool name: `javascript_code`.
- **typescriptExecutor**: Execute TypeScript code via persistent Node.js server with type safety. Tool name: `typescript_code`.
- **gmaps_locations**: Google Maps Geocoding service for address-to-coordinates conversion. Tool name: `geocode`.
@@ -1486,8 +1487,9 @@ Residential proxy provider management with geo-targeting, session control, and a
- **start**: Manual workflow trigger to start workflow execution
- **taskTrigger**: Event-driven trigger that fires when a delegated child agent completes its task (success or error). Filters by task_id, agent_name, status (all/completed/error), and parent_node_id. Output includes task_id, status, agent_name, result/error, workflow_id.
-### Code Nodes (3 nodes)
-- **pythonExecutor**: **Dual-purpose node** - Execute Python code with syntax-highlighted editor, input_data access, and console output. Works as workflow node OR AI Agent tool (`python_code`). Available libraries: math, json, datetime, timedelta, re, random, Counter, defaultdict.
+### Code Nodes (4 nodes)
+- **pythonExecutor**: **Dual-purpose node** - Execute Python code with syntax-highlighted editor, input_data access, and console output. Works as workflow node OR AI Agent tool (`python_code`). Available libraries: math, json, datetime, timedelta, re, random, Counter, defaultdict. CPython `exec()` with a restricted-builtins namespace; its `timeout` param is NOT enforced (only Temporal's CODE_EXEC activity timeout bounds it).
+- **montyExecutor**: **Dual-purpose node** - Execute Python in a hard sandbox via Pydantic's [Monty](https://github.com/pydantic/monty) interpreter (`pydantic-monty==0.0.18`, pinned alpha). Works as workflow node OR AI Agent tool (`sandboxed_python`). Deny-by-default: no filesystem/network/env access unless the LLM requests it via the dynamic `capabilities` param (`http_get` → SSRF-guarded host fetch; `workspace_read`/`workspace_write` → `MountDir` over the per-workflow workspace at `/workspace`). **ENFORCED** `timeout` (→ `ResourceLimits.max_duration_secs`) and `max_memory_mb` (→ `max_memory` bytes) — the headline win over pythonExecutor. Supported subset: def/closures/lambda, comprehensions, f-strings, try/except, async def/await, and `import math|json|re`; NOT supported: class, yield/generators, with, match, `import random|collections|os`. Reads `input_data`; returns the last expression as `output` + captured `print()` as `console_output`. Lazy-imports `pydantic_monty` inside the op (graceful `NodeUserError` if the wheel is missing); plugin at [server/nodes/code/monty_executor/](./server/nodes/code/monty_executor/). Skill: `server/skills/coding_agent/monty-skill/SKILL.md`.
- **javascriptExecutor**: **Dual-purpose node** - Execute JavaScript code via persistent Node.js server with syntax-highlighted editor and console output. Works as workflow node OR AI Agent tool (`javascript_code`).
- **typescriptExecutor**: **Dual-purpose node** - Execute TypeScript code via persistent Node.js server with type safety, syntax-highlighted editor and console output. Works as workflow node OR AI Agent tool (`typescript_code`).
diff --git a/server/nodes/README.md b/server/nodes/README.md
index 784bb78e..a393ffa3 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -112,7 +112,7 @@ email/ — IMAP/SMTP via Himalaya CLI
search/ — Web search APIs (brave / serper / perplexity / duckduckgo)
scraper/ — Apify / Crawlee
document/ — RAG pipeline (scrape / download / parse / chunk / embed / store)
-code/ — Python / JS / TS executors
+code/ — Python / Monty (sandboxed Python) / JS / TS executors
filesystem/ — file_read / file_modify / shell / fs_search
proxy/ — Residential proxy (request / config / status)
location/ — Google Maps (create / locations / nearby places)
@@ -142,7 +142,7 @@ these first before writing new code:
| `model/` | `_base.ChatModelBase` | 9 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |
| `android/` | `_base.AndroidServiceBase` | 16 Android services inherit; payload translation + `SERVICE_ID_MAP` lives on this base |
| `android/` | `_base.execute_android_toolkit` / `execute_android_service_tool` | AI-tool dispatchers — called from `services/handlers/tools.py` for the toolkit aggregator + direct service tool branches |
-| `code/` | `_base.CodeExecutorBase` + `_nodejs.NodeJSClient` | Python/JS/TS executors |
+| `code/` | `_base.CodeExecutorBase` + `_nodejs.NodeJSClient` | Python/JS/TS executors; `monty_executor/` is sandboxed Python via `pydantic-monty` (enforced limits + opt-in capabilities) |
| `google/` | `_base.build_google_service` / `track_google_usage` | 7 Google plugins (OAuth + API) |
| `google/` | `_gmail.fetch_email_details` / `mark_email_as_read` | gmail + gmail_receive |
| `twitter/` | `_base.call_with_retry` / `format_tweet` / `sync_search_recent` | 4 twitter plugins (XDK + refresh) |
diff --git a/server/nodes/code/monty_executor/__init__.py b/server/nodes/code/monty_executor/__init__.py
new file mode 100644
index 00000000..950f27f7
--- /dev/null
+++ b/server/nodes/code/monty_executor/__init__.py
@@ -0,0 +1,267 @@
+"""Monty Executor — sandboxed Python via Pydantic's Monty interpreter.
+
+A deny-by-default alternative to ``pythonExecutor``. Where ``pythonExecutor``
+runs user code through CPython ``exec()`` with a restricted-builtins namespace
+(a known-weak sandbox whose ``timeout`` is never actually enforced), this node
+runs code inside `pydantic-monty <https://github.com/pydantic/monty>`_ — a
+minimal Python subset implemented in Rust with ENFORCED wall-clock + memory
+limits and zero host access unless explicitly granted.
+
+Capabilities are dynamic: the caller (an LLM, when wired as the
+``sandboxed_python`` tool) selects from a fixed, vetted menu via the
+``capabilities`` param. Each selection wires a real Monty grant — an
+``external_functions`` entry (``http_get``) and/or a ``MountDir`` over the
+per-workflow workspace (``workspace_read`` / ``workspace_write``). The default
+(empty list) is pure deny-by-default.
+
+Verified against pydantic-monty==0.0.18 (the pinned version):
+ - ``Monty(code, inputs=[...])`` parses on construct; raises ``MontySyntaxError``.
+ - ``m.run(*, inputs, limits, external_functions, print_callback, mount, os)``
+ is SYNC and returns the program's last-expression value directly.
+ ``run_async`` has no ``mount`` param, so we use ``run`` via ``asyncio.to_thread``.
+ - ``ResourceLimits`` is a TypedDict: ``max_duration_secs`` (float),
+ ``max_memory`` (BYTES), ``max_allocations``, ``max_recursion_depth``, ``gc_interval``.
+ - Resource breach / unsupported feature / user runtime error -> ``MontyRuntimeError``
+ (a ``MontyError`` subclass). Host-function exceptions also surface as
+ ``MontyRuntimeError`` carrying the original message.
+ - stdout/print -> ``CollectString()`` whose ``.output`` is the captured str.
+ - ``MountDir(virtual_path, host_path, *, mode='read-only'|'read-write'|'overlay')``.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from typing import Any, Callable, Dict, Optional, Tuple
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from services.plugin import NodeContext, NodeUserError, Operation
+
+from .._base import CodeExecutorBase, CodeExecutorOutput
+
+
+# Fixed, vetted capability menu the LLM may request per call. Each maps to a
+# real Monty grant in ``_build_capabilities``. Keep this in sync with the
+# tool_description below and the monty-skill SKILL.md.
+CAPABILITY_MENU: Tuple[str, ...] = ("http_get", "workspace_read", "workspace_write")
+
+# Subset note surfaced to the LLM on import errors etc.
+_SUPPORTED = (
+ "def/closures/lambda, if/for/while, try/except, list/dict/set comprehensions, "
+ "f-strings, async def/await, and `import math|json|re`"
+)
+_UNSUPPORTED = "class, yield/generators, with, match, `import random|collections|os`"
+
+
+# ---------------------------------------------------------------------------
+# Capability builders (host functions run in the PARENT process; each is a
+# deliberate, bounded hole in the sandbox).
+# ---------------------------------------------------------------------------
+
+
+def _is_public_url(url: str) -> Tuple[bool, str]:
+ """SSRF guard: allow only http/https to a publicly-routable host.
+
+ Resolves every A/AAAA record and rejects loopback / private / link-local /
+ reserved / multicast / unspecified addresses. (DNS is re-resolved by httpx,
+ so this is a best-effort guard, not TOCTOU-proof — acceptable for v1.)
+ """
+ parsed = urlparse(url)
+ if parsed.scheme not in ("http", "https"):
+ return False, f"only http/https allowed (got {parsed.scheme or 'no scheme'!r})"
+ host = parsed.hostname
+ if not host:
+ return False, "missing host"
+ try:
+ infos = socket.getaddrinfo(host, None)
+ except socket.gaierror as exc:
+ return False, f"DNS resolution failed: {exc}"
+ for info in infos:
+ try:
+ ip = ipaddress.ip_address(info[4][0])
+ except ValueError:
+ continue
+ if (
+ ip.is_private
+ or ip.is_loopback
+ or ip.is_link_local
+ or ip.is_reserved
+ or ip.is_multicast
+ or ip.is_unspecified
+ ):
+ return False, f"blocked non-public address {ip}"
+ return True, ""
+
+
+def _make_http_get(timeout: float = 15.0) -> Callable[[str], str]:
+ """Return a vetted ``http_get(url) -> str`` for the sandbox to call.
+
+ Synchronous (Monty calls external functions inline on the worker thread).
+ Raises ValueError on a blocked URL / non-2xx — the message surfaces to the
+ sandboxed code as a normal exception, and to the node as a NodeUserError.
+ """
+ import httpx
+
+ def http_get(url: str) -> str:
+ ok, reason = _is_public_url(url)
+ if not ok:
+ raise ValueError(f"http_get blocked: {reason}")
+ resp = httpx.get(url, timeout=timeout, follow_redirects=True)
+ resp.raise_for_status()
+ return resp.text
+
+ return http_get
+
+
+def _build_capabilities(
+ monty, ctx: NodeContext, caps: set
+) -> Tuple[Optional[Dict[str, Callable]], Optional[Any]]:
+ """Translate the selected ``capabilities`` into Monty grants.
+
+ Returns ``(external_functions | None, mount | None)``.
+ """
+ unknown = caps - set(CAPABILITY_MENU)
+ if unknown:
+ raise NodeUserError(
+ f"Unknown capability {sorted(unknown)}. Available: {list(CAPABILITY_MENU)}"
+ )
+
+ ext_funcs: Dict[str, Callable] = {}
+ mount = None
+
+ if "http_get" in caps:
+ ext_funcs["http_get"] = _make_http_get()
+
+ if caps & {"workspace_read", "workspace_write"}:
+ if not ctx.workspace_dir:
+ raise NodeUserError(
+ "A workspace capability was requested but no workspace_dir is "
+ "available for this run."
+ )
+ # read-write is a superset of read-only; the sandbox only ever sees
+ # the virtual '/workspace' path (MountDir handles path isolation).
+ mode = "read-write" if "workspace_write" in caps else "read-only"
+ mount = monty.MountDir("/workspace", ctx.workspace_dir, mode=mode)
+
+ return (ext_funcs or None), mount
+
+
+class MontyExecutorParams(BaseModel):
+ code: str = Field(..., min_length=1, json_schema_extra={"editor": "code"})
+ # Wall-clock limit, ENFORCED by Monty (unlike pythonExecutor's timeout).
+ timeout: int = Field(default=30, ge=1, le=600)
+ # Memory limit in MB, converted to bytes for ResourceLimits.max_memory.
+ max_memory_mb: int = Field(default=256, ge=16, le=2048)
+ # LLM picks per call from CAPABILITY_MENU; empty = pure deny-by-default.
+ capabilities: list[str] = Field(
+ default_factory=list,
+ json_schema_extra={"enum_values": list(CAPABILITY_MENU)},
+ )
+
+ model_config = ConfigDict(extra="allow")
+
+
+class MontyExecutorNode(CodeExecutorBase):
+ type = "montyExecutor"
+ display_name = "Monty Executor"
+ subtitle = "Sandboxed Python"
+ description = (
+ "Run AI-generated Python in a hard sandbox (Pydantic Monty). "
+ "Deny-by-default with enforced time + memory limits; opt-in capabilities."
+ )
+ tool_name = "sandboxed_python"
+ tool_description = (
+ "Run untrusted/AI-generated Python in a secure sandbox (Pydantic Monty) "
+ "with ENFORCED time + memory limits. Deny-by-default: NO filesystem, "
+ "network, or env access unless you list it in `capabilities`. "
+ f"Supported: {_SUPPORTED}. NOT supported: {_UNSUPPORTED}. "
+ "Read inputs from the `input_data` dict (upstream node outputs); return "
+ "a result as the LAST expression. Optional `capabilities`: "
+ "['http_get','workspace_read','workspace_write'] — request only what the "
+ "task needs (workspace files are mounted at /workspace). For full Python "
+ "with more libraries, use `python_code` instead."
+ )
+
+ Params = MontyExecutorParams
+ Output = CodeExecutorOutput
+
+ @Operation("execute")
+ async def execute_op(self, ctx: NodeContext, params: MontyExecutorParams) -> Any:
+ """Execute user code inside Monty with enforced limits + opt-in grants.
+
+ ``input_data`` exposes ``connected_outputs`` (upstream node results);
+ the program's last expression is returned as ``output`` and any
+ ``print()`` output is captured into ``console_output``.
+ """
+ import asyncio
+
+ if not params.code.strip():
+ raise NodeUserError("No code provided")
+
+ # Lazy import so the server still boots + registers every other node if
+ # the wheel is missing for this platform.
+ try:
+ import pydantic_monty as monty
+ except ImportError as exc:
+ raise NodeUserError(
+ "Monty sandbox is unavailable (pydantic-monty is not installed, "
+ "or no wheel exists for this platform). Install `pydantic-monty`, "
+ "or use the python_code tool for non-sandboxed execution."
+ ) from exc
+
+ input_data = ctx.raw.get("connected_outputs") or {}
+ collector = monty.CollectString()
+
+ caps = set(params.capabilities)
+ ext_funcs, mount = _build_capabilities(monty, ctx, caps)
+
+ limits = monty.ResourceLimits(
+ max_duration_secs=params.timeout,
+ max_memory=params.max_memory_mb * 1024 * 1024,
+ )
+
+ try:
+ # Construction parses the code; run executes it. Both can raise the
+ # "unsupported feature" NotImplementedError (e.g. `class` surfaces a
+ # MontyRuntimeError at CONSTRUCT time), so they share one handler.
+ # run() is sync with the full kwarg set (incl. mount, which
+ # run_async lacks) and is offloaded so the CPU-bound Rust execution
+ # doesn't block the event loop.
+ m = monty.Monty(params.code, inputs=["input_data"])
+ result = await asyncio.to_thread(
+ m.run,
+ inputs={"input_data": input_data},
+ limits=limits,
+ external_functions=ext_funcs,
+ print_callback=collector,
+ mount=mount,
+ )
+ except monty.MontyError as exc:
+ # All Monty failures (syntax / typing / runtime / resource breach /
+ # unsupported feature / host-function exception) subclass MontyError.
+ # Classify by message so the LLM gets an actionable hint.
+ msg = str(exc)
+ low = msg.lower()
+ if "does not yet support" in low or "notimplementederror" in low:
+ raise NodeUserError(
+ f"{msg}\n\nMonty supports a Python SUBSET ({_SUPPORTED}); "
+ f"NOT {_UNSUPPORTED}. Use the python_code tool for those."
+ ) from exc
+ if "time limit" in low or "timeouterror" in low:
+ raise NodeUserError(
+ f"Monty time limit exceeded (timeout={params.timeout}s): {msg}"
+ ) from exc
+ if "memory limit" in low or "memoryerror" in low:
+ raise NodeUserError(
+ f"Monty memory limit exceeded (max_memory_mb={params.max_memory_mb}): {msg}"
+ ) from exc
+ if isinstance(exc, monty.MontySyntaxError):
+ raise NodeUserError(f"SyntaxError: {msg}") from exc
+ # Plain user-code runtime error (incl. exceptions raised by a
+ # capability host function, e.g. a blocked http_get URL).
+ raise NodeUserError(msg) from exc
+
+ out = result.output if isinstance(result, monty.MontyComplete) else result
+ return {"output": out, "console_output": collector.output}
diff --git a/server/nodes/code/monty_executor/icon.svg b/server/nodes/code/monty_executor/icon.svg
new file mode 100644
index 00000000..00312483
--- /dev/null
+++ b/server/nodes/code/monty_executor/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill="#50fa7b" d="M64 8 105 23v37c0 30.4-17.6 52.9-41 62-23.4-9.1-41-31.6-41-62V23z"/><path fill="#1a2e1f" d="M64 19 95 30.4V60c0 24.1-13.4 42.4-31 50.3C46.4 102.4 33 84.1 33 60V30.4z"/><path fill="none" stroke="#50fa7b" stroke-width="6" d="M54 63v-9a10 10 0 0 1 20 0v9"/><rect x="48" y="62" width="32" height="27" rx="5" fill="#50fa7b"/><circle cx="64" cy="72" r="4.5" fill="#1a2e1f"/><path fill="#1a2e1f" d="M61.8 74h4.4l1.6 9h-7.6z"/></svg>
diff --git a/server/nodes/code/monty_executor/meta.json b/server/nodes/code/monty_executor/meta.json
new file mode 100644
index 00000000..aa33b4b5
--- /dev/null
+++ b/server/nodes/code/monty_executor/meta.json
@@ -0,0 +1,3 @@
+{
+ "color": "#50fa7b"
+}
diff --git a/server/nodes/visuals.json b/server/nodes/visuals.json
index e71c33e7..fec53257 100644
--- a/server/nodes/visuals.json
+++ b/server/nodes/visuals.json
@@ -238,6 +238,9 @@
"pythonExecutor": {
"skill": "python-skill"
},
+ "montyExecutor": {
+ "skill": "monty-skill"
+ },
"rlm_agent": {
"icon": "🧠"
},
diff --git a/server/pyproject.toml b/server/pyproject.toml
index 384206f6..e58eaa0b 100644
--- a/server/pyproject.toml
+++ b/server/pyproject.toml
@@ -147,6 +147,16 @@ dependencies = [
# out-of-process pty-host (VSCode's pattern).
"ptyprocess>=0.7.0; sys_platform != 'win32'",
"pywinpty>=3.0.3; sys_platform == 'win32'",
+
+ # Sandboxed Python interpreter (montyExecutor node). Pydantic Monty:
+ # a deny-by-default Python subset written in Rust with ENFORCED
+ # time/memory limits, for safely running AI-generated code without
+ # container overhead (no filesystem/network/env unless explicitly
+ # granted via external_functions / MountDir). Prebuilt cross-platform
+ # wheels on PyPI (cp310-cp314, win/mac/linux), so a normal dep — NOT
+ # the pooch/npm lazy-binary pattern (that's for non-PyPI binaries).
+ # Pinned because pre-1.0 (alpha; API still moving fast).
+ "pydantic-monty==0.0.18",
]
[project.optional-dependencies]
diff --git a/server/services/node_executor.py b/server/services/node_executor.py
index 316fd4db..800517db 100644
--- a/server/services/node_executor.py
+++ b/server/services/node_executor.py
@@ -263,6 +263,7 @@ class NodeExecutor:
_NEEDS_CONNECTED_OUTPUTS = frozenset(
{
"pythonExecutor",
+ "montyExecutor",
"javascriptExecutor",
"typescriptExecutor",
"webhookResponse",
diff --git a/server/skills/coding_agent/monty-skill/SKILL.md b/server/skills/coding_agent/monty-skill/SKILL.md
new file mode 100644
index 00000000..cda061e6
--- /dev/null
+++ b/server/skills/coding_agent/monty-skill/SKILL.md
@@ -0,0 +1,116 @@
+---
+name: monty-skill
+description: Run AI-generated Python in a hard sandbox (Pydantic Monty) with enforced time + memory limits and opt-in capabilities. Use for untrusted code; supports a Python subset.
+allowed-tools: "monty_executor"
+metadata:
+ author: machina
+ version: "1.0"
+ category: code
+
+---
+
+# Sandboxed Python (Monty) Tool
+
+Execute Python in a **deny-by-default** sandbox powered by [Pydantic Monty](https://github.com/pydantic/monty) — a minimal Python interpreter written in Rust. Unlike the `python_code` tool (CPython `exec` with a restricted namespace), Monty **enforces** wall-clock and memory limits and grants **zero** host access unless you explicitly request it.
+
+Prefer this tool when running code you don't fully trust, or when you need guaranteed time/memory bounds. Use `python_code` instead when you need libraries Monty doesn't support (e.g. `random`, `collections`) or language features it lacks (classes, generators).
+
+## How It Works
+
+Connect the **Monty Executor** node to an agent's `input-tools` handle. The LLM calls the `sandboxed_python` tool with `code` (and optionally `capabilities`, `timeout`, `max_memory_mb`).
+
+## Schema Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| code | string | Yes | — | Python code to run in the sandbox |
+| timeout | int | No | 30 | Max wall-clock seconds (1–600), **enforced** |
+| max_memory_mb | int | No | 256 | Max memory in MB (16–2048), **enforced** |
+| capabilities | string[] | No | `[]` | Host grants to enable (see below); empty = no host access |
+
+## Inputs & Output
+
+- **`input_data`** — a dict of upstream node outputs is available as the variable `input_data`. Read with `input_data.get('someNode', {})`.
+- **Return a result** by making it the **last expression** in your code (e.g. a final line that is just `output` or a dict literal).
+- **`print(...)`** output is captured and returned as `console_output`.
+
+## Supported Python Subset
+
+| Works | Does NOT work |
+|-------|---------------|
+| `def`, closures, `lambda` | `class` definitions |
+| `if` / `for` / `while` | `yield` / generators |
+| `try` / `except` | `with` statements (without a workspace mount) |
+| list / dict / set comprehensions | `match` / `case` |
+| f-strings | `import random`, `import collections`, `import os` |
+| `async def` / `await` | arbitrary third-party packages |
+| `import math`, `import json`, `import re` | |
+
+If you hit an unsupported feature, rewrite without it or switch to the `python_code` tool.
+
+## Capabilities (opt-in host access)
+
+By default the sandbox has **no** filesystem, network, or environment access. Request only what the task needs via `capabilities`:
+
+| Capability | Grants | In-sandbox usage |
+|------------|--------|------------------|
+| `http_get` | An `http_get(url)` function (public http/https only; private/loopback hosts blocked) | `body = http_get("https://example.com")` |
+| `workspace_read` | Read-only mount of the workflow workspace at `/workspace` | `open("/workspace/data.txt").read()` |
+| `workspace_write` | Read-write mount at `/workspace` | `open("/workspace/out.txt", "w").write(text)` |
+
+Requesting more than necessary is discouraged — each capability is a deliberate hole in the sandbox.
+
+## Examples
+
+**Basic calculation (no capabilities):**
+```json
+{
+ "code": "total = sum(range(1, 11))\nprint(f'sum 1..10 = {total}')\ntotal"
+}
+```
+
+**Process upstream data:**
+```json
+{
+ "code": "nums = input_data.get('start', {}).get('numbers', [1,2,3])\navg = sum(nums) / len(nums)\nprint(f'avg = {avg}')\n{'avg': avg, 'count': len(nums)}"
+}
+```
+
+**Use the curated stdlib:**
+```json
+{
+ "code": "import math, json\nr = 5\narea = math.pi * r ** 2\njson.dumps({'radius': r, 'area': round(area, 2)})"
+}
+```
+
+**Fetch a URL (requires http_get):**
+```json
+{
+ "code": "body = http_get('https://example.com')\nlen(body)",
+ "capabilities": ["http_get"]
+}
+```
+
+**Read a workspace file (requires workspace_read):**
+```json
+{
+ "code": "data = open('/workspace/input.txt').read()\nlen(data.splitlines())",
+ "capabilities": ["workspace_read"]
+}
+```
+
+**Enforced timeout (this will be terminated, not hang):**
+```json
+{
+ "code": "while True:\n pass",
+ "timeout": 1
+}
+```
+
+## Guidelines
+
+1. **Return via the last expression** — don't rely on a magic `output` variable; the final expression's value is returned.
+2. **Use `print()` for debugging** — captured as `console_output`.
+3. **Request minimal `capabilities`** — start with none; add only what the task needs.
+4. **Keep limits sane** — `timeout` and `max_memory_mb` are hard caps; raise them only when justified.
+5. **Unsupported feature?** Rewrite without it, or fall back to the `python_code` tool.
diff --git a/server/tests/nodes/test_monty_executor.py b/server/tests/nodes/test_monty_executor.py
new file mode 100644
index 00000000..8e3d66d9
--- /dev/null
+++ b/server/tests/nodes/test_monty_executor.py
@@ -0,0 +1,289 @@
+"""Contract tests for the montyExecutor node (sandboxed Python via Monty).
+
+Tier A (always runs): drives the node through NodeExecutor with a FAKE
+`pydantic_monty` module injected into sys.modules. The fake mirrors the real
+v0.0.18 surface the plugin depends on (Monty(code, inputs=...), .run(*, inputs,
+limits, external_functions, print_callback, mount), CollectString().output,
+ResourceLimits, MountDir, and the MontyError/MontyRuntimeError/MontySyntaxError
+hierarchy). This keeps CI deterministic regardless of whether the real wheel is
+present.
+
+Tier B (skipif no real package): exercises the actual pydantic-monty interpreter
+to prove the headline behaviours — enforced timeout, the supported subset, and
+the unsupported-feature error path.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import types
+from unittest.mock import patch
+
+import pytest
+
+
+pytestmark = pytest.mark.node_contract
+
+
+# ============================================================================
+# Fake pydantic_monty (Tier A)
+# ============================================================================
+
+
+def _make_fake_monty_module() -> types.ModuleType:
+ mod = types.ModuleType("pydantic_monty")
+
+ class MontyError(Exception):
+ pass
+
+ class MontyRuntimeError(MontyError):
+ pass
+
+ class MontySyntaxError(MontyError):
+ pass
+
+ class MontyTypingError(MontyError):
+ pass
+
+ class MontyComplete:
+ def __init__(self, output):
+ self.output = output
+
+ class CollectString:
+ def __init__(self):
+ self.output = ""
+
+ def ResourceLimits(**kwargs): # real one is a TypedDict -> returns a dict
+ return dict(kwargs)
+
+ class MountDir:
+ def __init__(self, virtual_path, host_path, *, mode="read-only", write_bytes_limit=None):
+ self.virtual_path = virtual_path
+ self.host_path = host_path
+ self.mode = mode
+
+ class Monty:
+ """Behaviour is keyed off sentinel substrings in the code string."""
+
+ last_instance = None
+
+ def __init__(self, code, *, inputs=None, **kwargs):
+ self.code = code
+ self.inputs = inputs
+ self.last_inputs = None
+ self.last_limits = None
+ self.last_external_functions = None
+ self.last_mount = None
+ Monty.last_instance = self
+ if "SYNTAX" in code:
+ raise MontySyntaxError("Expected an expression")
+
+ def run(self, *, inputs=None, limits=None, external_functions=None, print_callback=None, mount=None, os=None):
+ self.last_inputs = inputs
+ self.last_limits = limits
+ self.last_external_functions = external_functions
+ self.last_mount = mount
+ if print_callback is not None:
+ print_callback.output = "console-out\n"
+ if "TIMEOUT" in self.code:
+ raise MontyRuntimeError("TimeoutError: time limit exceeded: 1001ms > 1000ms")
+ if "MEMORY" in self.code:
+ raise MontyRuntimeError("MemoryError: memory limit exceeded: 9 bytes > 8 bytes")
+ if "UNSUPPORTED" in self.code:
+ raise MontyRuntimeError(
+ "NotImplementedError: The monty syntax parser does not yet support class definitions"
+ )
+ if "RUNTIME" in self.code:
+ raise MontyRuntimeError("NameError: name 'x' is not defined")
+ return {"echo": (inputs or {}).get("input_data")}
+
+ mod.MontyError = MontyError
+ mod.MontyRuntimeError = MontyRuntimeError
+ mod.MontySyntaxError = MontySyntaxError
+ mod.MontyTypingError = MontyTypingError
+ mod.MontyComplete = MontyComplete
+ mod.CollectString = CollectString
+ mod.ResourceLimits = ResourceLimits
+ mod.MountDir = MountDir
+ mod.Monty = Monty
+ return mod
+
+
+def fake_monty():
+ mod = _make_fake_monty_module()
+ with patch.dict(sys.modules, {"pydantic_monty": mod}):
+ yield mod
+
+
+# ============================================================================
+# Tier A — fake-backed contract tests
+# ============================================================================
+
+
+class TestMontyExecutor:
+ async def test_empty_code_rejected(self, harness, fake_monty):
+ result = await harness.execute("montyExecutor", {"code": " \n\t"})
+ harness.assert_envelope(result, success=False)
+ assert "no code provided" in result["error"].lower()
+
+ async def test_package_missing_graceful_error(self, harness):
+ # sys.modules[name] = None makes `import name` raise ImportError.
+ with patch.dict(sys.modules, {"pydantic_monty": None}):
+ result = await harness.execute("montyExecutor", {"code": "1 + 1"})
+ harness.assert_envelope(result, success=False)
+ assert result.get("error_type") == "NodeUserError"
+ assert "pydantic-monty" in result["error"] or "install" in result["error"].lower()
+
+ async def test_happy_path_reads_input_and_returns(self, harness, fake_monty):
+ # connected_outputs are keyed by SOURCE TYPE (see node_executor).
+ upstream = {"source_A::output_main": {"n": 5}}
+ nodes = [
+ {"id": "m1", "type": "montyExecutor"},
+ {"id": "source_A", "type": "start"},
+ ]
+ edges = [{"source": "source_A", "target": "m1", "sourceHandle": "output-main"}]
+
+ result = await harness.execute(
+ "montyExecutor",
+ {"code": "input_data"},
+ node_id="m1",
+ upstream_outputs=upstream,
+ nodes=nodes,
+ edges=edges,
+ )
+
+ harness.assert_envelope(result, success=True)
+ harness.assert_output_shape(result, ["output", "console_output"])
+ payload = result["result"]
+ assert payload["output"] == {"echo": {"start": {"n": 5}}}
+ assert "console-out" in payload["console_output"]
+
+ async def test_input_data_wired_into_monty(self, harness, fake_monty):
+ # Regression-guards the _NEEDS_CONNECTED_OUTPUTS edit: without it,
+ # input_data would arrive empty.
+ upstream = {"source_A::output_main": {"k": "v"}}
+ nodes = [
+ {"id": "m1", "type": "montyExecutor"},
+ {"id": "source_A", "type": "start"},
+ ]
+ edges = [{"source": "source_A", "target": "m1", "sourceHandle": "output-main"}]
+
+ await harness.execute(
+ "montyExecutor",
+ {"code": "input_data"},
+ node_id="m1",
+ upstream_outputs=upstream,
+ nodes=nodes,
+ edges=edges,
+ )
+
+ inst = fake_monty.Monty.last_instance
+ assert inst.inputs == ["input_data"]
+ assert inst.last_inputs == {"input_data": {"start": {"k": "v"}}}
+ # ResourceLimits carried the enforced bounds (defaults).
+ assert inst.last_limits["max_duration_secs"] == 30
+ assert inst.last_limits["max_memory"] == 256 * 1024 * 1024
+
+ async def test_timeout_maps_to_user_error(self, harness, fake_monty):
+ result = await harness.execute("montyExecutor", {"code": "TIMEOUT", "timeout": 1})
+ harness.assert_envelope(result, success=False)
+ assert result.get("error_type") == "NodeUserError"
+ assert "limit exceeded" in result["error"].lower()
+
+ async def test_memory_limit_maps_to_user_error(self, harness, fake_monty):
+ result = await harness.execute("montyExecutor", {"code": "MEMORY"})
+ harness.assert_envelope(result, success=False)
+ assert "memory limit" in result["error"].lower()
+
+ async def test_unsupported_feature_points_to_python_code(self, harness, fake_monty):
+ result = await harness.execute("montyExecutor", {"code": "UNSUPPORTED"})
+ harness.assert_envelope(result, success=False)
+ assert "python_code" in result["error"]
+ assert "does not yet support" in result["error"]
+
+ async def test_syntax_error_maps_to_user_error(self, harness, fake_monty):
+ result = await harness.execute("montyExecutor", {"code": "SYNTAX"})
+ harness.assert_envelope(result, success=False)
+ assert "syntaxerror" in result["error"].lower()
+
+ async def test_unknown_capability_rejected(self, harness, fake_monty):
+ result = await harness.execute("montyExecutor", {"code": "1", "capabilities": ["bogus"]})
+ harness.assert_envelope(result, success=False)
+ assert "unknown capability" in result["error"].lower()
+ assert "http_get" in result["error"]
+
+ async def test_no_capabilities_grants_nothing(self, harness, fake_monty):
+ await harness.execute("montyExecutor", {"code": "1"})
+ inst = fake_monty.Monty.last_instance
+ assert inst.last_external_functions is None
+ assert inst.last_mount is None
+
+ async def test_capabilities_wire_grants(self, harness, fake_monty):
+ ctx = harness.build_context(workspace_dir="/tmp/ws")
+ await harness.execute(
+ "montyExecutor",
+ {"code": "1", "capabilities": ["http_get", "workspace_write"]},
+ node_id="m1",
+ context=ctx,
+ )
+ inst = fake_monty.Monty.last_instance
+ assert "http_get" in (inst.last_external_functions or {})
+ assert inst.last_mount is not None
+ assert inst.last_mount.mode == "read-write"
+ assert inst.last_mount.virtual_path == "/workspace"
+ assert inst.last_mount.host_path == "/tmp/ws"
+
+ async def test_workspace_read_only_mode(self, harness, fake_monty):
+ ctx = harness.build_context(workspace_dir="/tmp/ws")
+ await harness.execute(
+ "montyExecutor",
+ {"code": "1", "capabilities": ["workspace_read"]},
+ node_id="m1",
+ context=ctx,
+ )
+ inst = fake_monty.Monty.last_instance
+ assert inst.last_mount.mode == "read-only"
+
+ async def test_workspace_capability_without_workspace_dir_errors(self, harness, fake_monty):
+ result = await harness.execute(
+ "montyExecutor",
+ {"code": "1", "capabilities": ["workspace_read"]},
+ )
+ harness.assert_envelope(result, success=False)
+ assert "workspace" in result["error"].lower()
+
+
+# ============================================================================
+# Tier B — real pydantic-monty (skipped when the wheel is absent)
+# ============================================================================
+
+
+ importlib.util.find_spec("pydantic_monty") is None,
+ reason="pydantic-monty not installed",
+)
+class TestMontyExecutorReal:
+ async def test_real_happy_path(self, harness):
+ result = await harness.execute("montyExecutor", {"code": "print('hi')\n40 + 2"})
+ harness.assert_envelope(result, success=True)
+ assert result["result"]["output"] == 42
+ assert "hi" in result["result"]["console_output"]
+
+ async def test_real_enforced_timeout(self, harness):
+ result = await harness.execute(
+ "montyExecutor", {"code": "while True:\n pass", "timeout": 1}
+ )
+ harness.assert_envelope(result, success=False)
+ assert "limit" in result["error"].lower()
+
+ async def test_real_unsupported_feature(self, harness):
+ result = await harness.execute("montyExecutor", {"code": "class Foo:\n pass"})
+ harness.assert_envelope(result, success=False)
+ assert "python_code" in result["error"]
+
+ async def test_real_curated_stdlib_import(self, harness):
+ result = await harness.execute("montyExecutor", {"code": "import math\nmath.factorial(5)"})
+ harness.assert_envelope(result, success=True)
+ assert result["result"]["output"] == 120