Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions python/packages/monty/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,9 @@ from agent_framework.monty import (
- `file_mounts` — sequence of `FileMountInput` (str shorthand,
`(host_path, mount_path)` tuple, or `FileMount`)
- `resource_limits` — Monty 1.x `ResourceLimits` keys; legacy `max_duration_secs`
maps to `max_feed_duration_secs`, and supplying both is an error
maps to `max_feed_duration_secs`, and supplying both is an error. When neither
key is set, a 30-second `max_feed_duration_secs` applies at run time (it is not
part of the `resource_limits` property or serializable state); `None` removes it.
- `include_detailed_errors` — keyword-only Boolean, default `False`. Host failures become generic
`RuntimeError`s and execution errors omit raw details. Trusted opt-in preserves original diagnostics.
The flag is not a code input, is independent of outer-client error/logging settings, and is copied
Expand Down Expand Up @@ -72,9 +74,26 @@ Tool-management methods on both classes: `add_tools`, `get_tools`,
- **`_execute_code_tool.py`** — `MontyExecuteCodeTool` plus tool / mount
normalization, approval helpers, dynamic `description`/`instructions`
builders, and the post-execution file-capture flow that surfaces files
written to `read-write` mounts as `Content.from_data` items.
written to `read-write` mounts as `Content.from_data` items. Captured files
are attributed by comparing the mount before and after a run, so calls on a
tool with a `read-write` mount take turns through a `MountGate`. The tool
hands its gate to every run-scoped copy from `create_run_tool()`, so all runs
of one provider share it. Tools and mounts are read once a call has its turn.
- **`_mount_gate.py`** — `MountGate`, a first-in-first-out turn gate that works
across event loops and threads (a lock bound to one event loop would not). A
call that a host tool starts while its own call has the turn is part of that
turn and does not wait (tracked with a context variable, so it needs no
explicit hand-off). A counter on the turn tracks its running calls, and the
gate passes the turn on only when the last one has ended, even if a host tool
left a call running in the background. A waiting call fails with
`MountGateTimeoutError` after `WAIT_TIMEOUT_SECS`, which `_run_code` turns into
an error `Content` whose message always shows. The gate does not cap how long
a call holds its turn. A copy of a tool shares the gate, and a pickled tool
gets a fresh one.
- **`_monty_bridge.py`** — `InlineCodeBridge` and `generate_type_stubs`,
adapted from the reference Monty CodeAct repo. Pauses on `FunctionSnapshot`
adapted from the reference Monty CodeAct repo. Runs guest code through the
async pool (`AsyncMonty`) so it never blocks the event loop, and awaits every
`feed_start` / `resume` / `resume_auto`. Pauses on `AsyncFunctionSnapshot`
to dispatch host calls, then resumes; supports direct typed tool calls
(keyword arguments only; the generated stubs are keyword-only, omit parameters
guest code cannot supply such as an injected context, `self`, `*args` and
Expand Down
22 changes: 22 additions & 0 deletions python/packages/monty/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,28 @@ codeact = MontyCodeActProvider(
`max_memory`, `gc_interval`, `max_recursion_depth`, `max_suspensions`, and
`max_total_sleep_secs`. These interpreter limits do not independently bound
host-side post-execution attachment capture.
- Sandbox code runs in Monty worker processes, so it does not block the event
loop, and cancelling an `execute_code` call discards its worker. When
`resource_limits` sets neither `max_feed_duration_secs` nor `max_duration_secs`,
a **30-second** `max_feed_duration_secs` applies. Set it to another value, or to
`None` (`resource_limits={"max_feed_duration_secs": None}`), to change or remove
the limit. A call that reaches the limit returns an `Execution error`; with
`include_detailed_errors=True` its details name the limit
(`TimeoutError: feed time limit exceeded`). Concurrent `execute_code` calls
overlap and each starts its own worker process, so bound concurrency in your
application when serving many callers.
- Calls that can write to the same host files take turns, so captured files stay
attributed to the right call. A tool with a `read-write` mount (including
`workspace_root`) serves one call at a time. This covers every run of one
provider and works across event loops and threads. A call waits at most 10
minutes for its turn and then returns an error, and a slow host tool holds up
the calls behind it. A call that a host tool starts while its own call has the
turn, such as a sub-agent that uses the same provider, is part of that call
and does not wait; the outer call also returns the files that the inner call
wrote. The turn lasts until the call and every call it started have ended,
even when a host tool leaves one running in the background. Separate tools or
providers that mount the same host directory do not take turns with each
other, so give each one its own directory.

## DSL inside `execute_code`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@

from ._instructions import build_codeact_instructions, build_execute_code_description
from ._monty_bridge import InlineCodeBridge, generate_type_stubs
from ._mount_gate import MountGate, MountGateTimeoutError
from ._types import FileMount, FileMountInput

logger = logging.getLogger("agent_framework")
Expand Down Expand Up @@ -249,7 +250,12 @@ class MontyExecuteCodeTool(FunctionTool):
Hyperlight's ``/output`` flow.

``resource_limits`` is forwarded to Monty's ``ResourceLimits`` to cap CPU
time, memory, output size, recursion depth, and GC frequency.
time, memory, output size, recursion depth, and GC frequency. When it sets
neither ``max_feed_duration_secs`` nor its legacy alias ``max_duration_secs``,
guest execution is limited to 30 seconds, not counting time spent waiting on
host tools. Set ``max_feed_duration_secs`` to another value, or to ``None`` to
remove the limit. ``max_duration_secs`` will be removed soon, because this
package is in beta.

``tool_description_format`` controls parameter documentation in both the
description and instructions: ``"compact"`` (default) or ``"json"`` globally,
Expand All @@ -258,8 +264,21 @@ class MontyExecuteCodeTool(FunctionTool):
are copied and retain entries for tools registered later.

All mutators (``add_tools``, ``add_file_mounts`` etc.) must be called from
the same task/thread that owns the tool. Monty itself runs on the event
loop, so no internal locking is needed.
the same task/thread that owns the tool; they are not synchronized. Guest
code runs in Monty worker processes and does not block the event loop, so
concurrent ``execute_code`` calls overlap and each starts its own worker
process.

Calls on a tool that has a read-write mount (including ``workspace_root``)
take turns, so that written files are attributed to the right call. This
covers every run of one provider and works across event loops and threads.
A call waits at most 10 minutes for its turn and then returns an error. A call
that a host tool starts while its own call has the turn, such as a sub-agent
that uses the same provider, is part of that call and does not wait. The turn
lasts until the call and every call it started have ended. Tools and mounts
are read when a call gets its turn. Separate tools or providers that mount the
same host directory do not take turns with each other, so give each one its
own directory.

Keyword Args:
include_detailed_errors: Include host exception types/messages and execution error details.
Expand All @@ -278,6 +297,7 @@ def __init__(
tool_description_format: _ToolDescriptionFormat = "compact",
include_detailed_errors: bool = False,
_fides_warned_metadata: list[tuple[FunctionTool, dict[str, str]]] | None = None,
_mount_gate: MountGate | None = None,
) -> None:
if not isinstance(include_detailed_errors, bool):
raise TypeError("include_detailed_errors must be a bool.")
Expand All @@ -300,6 +320,7 @@ def __init__(
)
self._file_mounts: dict[str, FileMount] = {}
self._resource_limits: dict[str, Any] | None = dict(resource_limits) if resource_limits else None
self._mount_gate: MountGate = _mount_gate or MountGate()

if tools is not None:
self.add_tools(tools)
Expand Down Expand Up @@ -398,7 +419,10 @@ def workspace_root(self) -> Path | None:

@property
def resource_limits(self) -> dict[str, Any] | None:
"""Return the configured Monty :class:`pydantic_monty.ResourceLimits`, if any."""
"""Return the configured Monty :class:`pydantic_monty.ResourceLimits`, if any.

The default guest execution limit applied when no feed duration is configured is not included.
"""
return dict(self._resource_limits) if self._resource_limits else None

def build_instructions(self, *, tools_visible_to_model: bool) -> str:
Expand All @@ -423,6 +447,7 @@ def create_run_tool(self) -> MontyExecuteCodeTool:
resource_limits=self._resource_limits,
tool_description_format=self._tool_description_format,
include_detailed_errors=self._include_detailed_errors,
_mount_gate=self._mount_gate,
)

def build_serializable_state(self) -> dict[str, Any]:
Expand Down Expand Up @@ -500,6 +525,17 @@ def _effective_mounts(self) -> list[FileMount]:
return mounts

async def _run_code(self, *, code: str) -> list[Content]:
# Written files are attributed by comparing read-write mounts before and after the run, so calls that can
# write to the same host files take turns.
if not any(mount.mode == "read-write" for mount in self._effective_mounts()):
return await self._execute(code)
try:
async with self._mount_gate.hold():
Comment thread
eavanvalkenburg marked this conversation as resolved.
Resolved
return await self._execute(code)
except MountGateTimeoutError as exc:
return [Content.from_error(message=str(exc))]

async def _execute(self, code: str) -> list[Content]:
include_detailed_errors = self._include_detailed_errors
tools = list(self._managed_tools)
mounts = self._effective_mounts()
Expand Down
72 changes: 41 additions & 31 deletions python/packages/monty/agent_framework_monty/_monty_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@

MAX_PRINT_OUTPUT_CHARS = 8192

# Guest execution budget in seconds, applied when ``resource_limits`` configures no feed duration.
DEFAULT_MAX_FEED_DURATION_SECS = 30.0

# Prelude injected into all Monty code so `asyncio.gather` works for fan-out.
_CODEACT_PRELUDE = """\
import asyncio
Expand Down Expand Up @@ -203,8 +206,8 @@ def output(self) -> str:
def load_monty() -> Any:
"""Import ``pydantic_monty`` lazily so unit tests can run without it.

Returns the module so callers can read ``Monty``, ``MontyComplete``,
``FunctionSnapshot``, ``FutureSnapshot``, ``NameLookupSnapshot`` from it.
Returns the module so callers can read ``AsyncMonty``, ``MontyComplete``,
``AsyncFunctionSnapshot``, ``AsyncFutureSnapshot``, ``AsyncNameLookupSnapshot`` from it.
"""
try:
import pydantic_monty
Expand All @@ -220,8 +223,14 @@ class InlineCodeBridge:
"""Execute Monty code inline (non-durable).

Supports both ``await call_tool('name', ...)`` and direct ``await name(...)``
calls. When Monty yields a :class:`FutureSnapshot`, the bridge invokes the
calls. When Monty yields an :class:`AsyncFutureSnapshot`, the bridge invokes the
registered host tools and resumes execution with the results.

Guest code runs in Monty worker processes through the asynchronous pool API, so it does
not block the event loop. Cancelling :meth:`run` discards the worker. When ``resource_limits``
configures neither ``max_feed_duration_secs`` nor the legacy ``max_duration_secs``,
``DEFAULT_MAX_FEED_DURATION_SECS`` bounds the guest execution time. Set
``max_feed_duration_secs`` to ``None`` to remove that bound.
"""

def __init__(
Expand All @@ -245,32 +254,33 @@ async def run(self, code: str) -> dict[str, Any]:
raise ValueError("Code must be a non-empty string.")

monty_module = load_monty()
Monty = monty_module.Monty
AsyncMonty = monty_module.AsyncMonty
MontyComplete = monty_module.MontyComplete
FunctionSnapshot = monty_module.FunctionSnapshot
FutureSnapshot = monty_module.FutureSnapshot
NameLookupSnapshot = monty_module.NameLookupSnapshot
FunctionSnapshot = monty_module.AsyncFunctionSnapshot
FutureSnapshot = monty_module.AsyncFutureSnapshot
NameLookupSnapshot = monty_module.AsyncNameLookupSnapshot

printer = _PrintCollector()
checkout_kwargs: dict[str, Any] = {
"script_name": "codeact.py",
"type_check": self.type_stubs is not None,
"type_check_stubs": self.type_stubs,
}
if self._resource_limits:
limits = dict(self._resource_limits)
if "max_duration_secs" in limits:
if "max_feed_duration_secs" in limits:
raise ValueError("Specify only one of max_duration_secs and max_feed_duration_secs.")
limits["max_feed_duration_secs"] = limits.pop("max_duration_secs")
checkout_kwargs["limits"] = limits
limits = dict(self._resource_limits) if self._resource_limits else {}
if "max_duration_secs" in limits:
if "max_feed_duration_secs" in limits:
raise ValueError("Specify only one of max_duration_secs and max_feed_duration_secs.")
limits["max_feed_duration_secs"] = limits.pop("max_duration_secs")
# Only an absent key gets the default; an explicit ``None`` is the caller's opt-out.
limits.setdefault("max_feed_duration_secs", DEFAULT_MAX_FEED_DURATION_SECS)
checkout_kwargs["limits"] = limits

feed_kwargs: dict[str, Any] = {"print_callback": printer}
if self._mounts:
feed_kwargs["mount"] = list(self._mounts)

with Monty() as pool, pool.checkout(**checkout_kwargs) as session:
progress = session.feed_start(_build_code(code), **feed_kwargs)
async with AsyncMonty() as pool, pool.checkout(**checkout_kwargs) as session:
Comment thread
eavanvalkenburg marked this conversation as resolved.
Resolved
Comment thread
eavanvalkenburg marked this conversation as resolved.
Resolved
progress = await session.feed_start(_build_code(code), **feed_kwargs)

while True:
if isinstance(progress, MontyComplete):
Expand All @@ -280,7 +290,7 @@ async def run(self, code: str) -> dict[str, Any]:
"truncated": printer.truncated,
}
if isinstance(progress, FunctionSnapshot):
progress = self._handle_function(progress)
progress = await self._handle_function(progress)
continue
if isinstance(progress, FutureSnapshot):
progress = await self._handle_future(progress)
Expand All @@ -289,60 +299,60 @@ async def run(self, code: str) -> dict[str, Any]:
raise RuntimeError(f"Name lookup not supported: {progress.variable_name!r}")
raise RuntimeError(f"Unsupported Monty progress type: {type(progress).__name__}")

def _handle_function(self, snapshot: Any) -> Any:
async def _handle_function(self, snapshot: Any) -> Any:
if snapshot.is_os_function:
# pydantic-monty pool API: feed_start always surfaces OS calls as
# snapshots. Mounts (and os=) are consulted only by resume_auto(),
# not by a plain resume(...) payload.
if self._mounts:
return snapshot.resume_auto()
return snapshot.resume({
return await snapshot.resume_auto()
return await snapshot.resume({
"exc_type": "PermissionError",
"message": "OS and filesystem calls are not available.",
})

function_name = str(snapshot.function_name)

if function_name in self.tool_map:
return self._schedule_direct_tool(snapshot, function_name)
return await self._schedule_direct_tool(snapshot, function_name)
if function_name == "call_tool":
return self._schedule_call_tool(snapshot)
return await self._schedule_call_tool(snapshot)

return snapshot.resume({
return await snapshot.resume({
"exc_type": "NameError",
"message": f"Function {function_name!r} is not available.",
})

def _schedule_direct_tool(self, snapshot: Any, name: str) -> Any:
async def _schedule_direct_tool(self, snapshot: Any, name: str) -> Any:
# The generated stubs are keyword-only, so ``ty`` rejects positional calls before any code runs. Fail
# closed on anything that still reaches the host (for example when type checking is bypassed) instead of
# dropping the positional arguments and running the host tool with its defaults. This is a bridge-owned
# usage error, not a host failure, so it stays actionable under redaction (like ``_schedule_call_tool``).
if snapshot.args:
return snapshot.resume(
return await snapshot.resume(
_external_error(
TypeError(f"{name} accepts keyword arguments only. Use keyword arguments for parameters."),
include_detailed_errors=True,
)
)
self._pending_calls[int(snapshot.call_id)] = (name, dict(snapshot.kwargs))
return snapshot.resume({"future": ...})
return await snapshot.resume({"future": ...})

def _schedule_call_tool(self, snapshot: Any) -> Any:
async def _schedule_call_tool(self, snapshot: Any) -> Any:
try:
name, kwargs = _parse_call_tool(snapshot.args, snapshot.kwargs)
if name not in self.tool_map:
allowed = ", ".join(sorted(self.tool_map.keys())) or "<none>"
raise ValueError(f"Tool {name!r} is not registered. Available tools: {allowed}")
self._pending_calls[int(snapshot.call_id)] = (name, kwargs)
except Exception as exc:
return snapshot.resume(_external_error(exc, include_detailed_errors=True))
return snapshot.resume({"future": ...})
return await snapshot.resume(_external_error(exc, include_detailed_errors=True))
return await snapshot.resume({"future": ...})

async def _handle_future(self, snapshot: Any) -> Any:
pending_call_ids = [int(cid) for cid in snapshot.pending_call_ids]
if not pending_call_ids:
return snapshot.resume({})
return await snapshot.resume({})

entries: list[tuple[int, tuple[str, dict[str, Any]]]] = []
for cid in pending_call_ids:
Expand All @@ -353,7 +363,7 @@ async def _handle_future(self, snapshot: Any) -> Any:
tasks = [self._invoke_tool(cid, name, kwargs) for cid, (name, kwargs) in entries]
results = await asyncio.gather(*tasks)
resume_results: dict[int, Any] = dict(results)
return snapshot.resume(resume_results)
return await snapshot.resume(resume_results)

async def _invoke_tool(self, cid: int, name: str, kwargs: dict[str, Any]) -> tuple[int, Any]:
# Every entry in ``self.tool_map`` is produced by ``_make_tool_callback``
Expand Down
Loading
Loading