feat(tools): add Velaris tools: sandboxed execution of agent-written code with effect budgets

lib/crewai-tools/pyproject.toml

@@ -170,6 +170,9 @@ e2b = [
     "e2b~=2.20.0",
     "e2b-code-interpreter~=2.6.0",
 ]
+velaris = [
+    "velaris-lang>=2.57.0",
+]
 
 
 [tool.uv]

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -210,6 +210,11 @@
 from crewai_tools.tools.tavily_search_tool.tavily_search_tool import TavilySearchTool
 from crewai_tools.tools.txt_search_tool.txt_search_tool import TXTSearchTool
 from crewai_tools.tools.url_read_tool.url_read_tool import URLReadTool
+from crewai_tools.tools.velaris_tool.velaris_tool import (
+    VelarisAuditTool,
+    VelarisCardTool,
+    VelarisRunTool,
+)
 from crewai_tools.tools.vision_tool.vision_tool import VisionTool
 from crewai_tools.tools.wait_tool.wait_tool import WaitTool
 from crewai_tools.tools.weaviate_tool.vector_search import WeaviateVectorSearchTool
@@ -329,6 +334,9 @@
     "TavilyResearchTool",
     "TavilySearchTool",
     "URLReadTool",
+    "VelarisAuditTool",
+    "VelarisCardTool",
+    "VelarisRunTool",
     "VisionTool",
     "WaitTool",
     "WeaviateVectorSearchTool",

lib/crewai-tools/src/crewai_tools/tools/__init__.py

@@ -197,6 +197,11 @@
 from crewai_tools.tools.tavily_search_tool.tavily_search_tool import TavilySearchTool
 from crewai_tools.tools.txt_search_tool.txt_search_tool import TXTSearchTool
 from crewai_tools.tools.url_read_tool.url_read_tool import URLReadTool
+from crewai_tools.tools.velaris_tool.velaris_tool import (
+    VelarisAuditTool,
+    VelarisCardTool,
+    VelarisRunTool,
+)
 from crewai_tools.tools.vision_tool.vision_tool import VisionTool
 from crewai_tools.tools.wait_tool.wait_tool import WaitTool
 from crewai_tools.tools.weaviate_tool.vector_search import WeaviateVectorSearchTool
@@ -312,6 +317,9 @@
     "TavilyResearchTool",
     "TavilySearchTool",
     "URLReadTool",
+    "VelarisAuditTool",
+    "VelarisCardTool",
+    "VelarisRunTool",
     "VisionTool",
     "WaitTool",
     "WeaviateVectorSearchTool",

lib/crewai-tools/src/crewai_tools/tools/velaris_tool/README.md

@@ -0,0 +1,84 @@
+# Velaris Tools
+
+## Description
+
+Run code your agents write, in a box. These tools compile a
+[Velaris](https://github.com/gowrishankar-infra/velaris-lang) program,
+report what it can touch, and run it under an effect budget chosen by
+you, the crew's author, not by the agent.
+
+- **VelarisRunTool**: runs a program under an effect budget. `VelarisRunTool(allow=["io"])` means anything the agent writes can print and nothing else - not read a file, reach the network, or call Python - whatever the code claims. A refusal stops the program and the tool reports which effect was refused.
+- **VelarisAuditTool**: tells the agent (and you) what a program can touch and how much of its promises were proven before running, in the versioned `velaris.audit/1` JSON format.
+- **VelarisCardTool**: returns the Velaris language card (about 2,300 words), which an agent can read before writing Velaris.
+
+The program runs in a separate, killable process bounded by `timeout`
+(seconds, default 30) and `max_memory_mb` (default 512). A program that
+never ends or eats memory is stopped, and the tool reports which limit
+it hit. The limits are enforced on every supported compiler version: on
+velaris-lang 2.59.0 and newer by `velaris.run` itself, on older versions
+by the tool's own subprocess. The memory cap is enforced on Linux;
+best-effort on macOS; not applied on Windows.
+
+Not a security boundary: `allow=["ffi"]` grants everything Python can
+do. It is a real guard for the ordinary case of running a script a
+model wrote.
+
+## Installation
+
+Install the crewai_tools package and the Velaris compiler:
+
+```shell
+pip install 'crewai[tools]' velaris-lang
+```
+
+or, with the optional extra:
+
+```shell
+uv add crewai-tools --extra velaris
+```
+
+`z3-solver` is optional. Without it, promises are checked while running
+rather than proven beforehand, and the audit says so.
+
+## Example
+
+```python
+from crewai import Agent
+from crewai_tools import VelarisAuditTool, VelarisRunTool
+
+analyst = Agent(
+    role="Data analyst",
+    goal="Total the expenses in the CSV and report the largest",
+    tools=[VelarisAuditTool(), VelarisRunTool(allow=["io"])],
+)
+```
+
+To let the program read files as well:
+
+```python
+VelarisRunTool(allow=["io", "fs"])
+```
+
+## Arguments
+
+### VelarisRunTool
+
+Constructor:
+
+- `allow`: (Optional) The effects the program may perform, chosen from `io`, `fs`, `net`, `clock`, `rand` and `ffi`. Defaults to `["io"]`.
+- `timeout`: (Optional) Seconds the program may run before it is stopped. Defaults to `30.0`.
+- `max_memory_mb`: (Optional) Memory the program may use, in MB, before it is stopped. Defaults to `512`. Enforced on Linux; best-effort on macOS; not applied on Windows.
+
+Run:
+
+- `source`: The Velaris program to run.
+- `stdin`: (Optional) Text to feed the program on standard input.
+- `args`: (Optional) Command-line arguments for the program.
+
+### VelarisAuditTool
+
+- `source`: The Velaris program to inspect.
+
+### VelarisCardTool
+
+Takes no arguments.

lib/crewai-tools/src/crewai_tools/tools/velaris_tool/__init__.py

@@ -0,0 +1,16 @@
+from crewai_tools.tools.velaris_tool.velaris_tool import (
+    VelarisAuditTool,
+    VelarisAuditToolSchema,
+    VelarisCardTool,
+    VelarisRunTool,
+    VelarisRunToolSchema,
+)
+
+
+__all__ = [
+    "VelarisAuditTool",
+    "VelarisAuditToolSchema",
+    "VelarisCardTool",
+    "VelarisRunTool",
+    "VelarisRunToolSchema",
+]