jaz.repl
New to JAZ? This is generated API reference. Start with the docs and the concepts overview.
Public API of the jaz.repl submodule (import from jaz.repl, e.g. from jaz.repl import ...).
ExecResult, a union ofContinue,ReturnandRaise— the type of the result of a REPL execution.BaseREPL, generic in the per-invoke state type an implementation chooses, andPythonREPL, the shipped in-process Python implementation.REPLHistoryEntry, one entry of the__history__recordPythonREPLkeeps.
BaseREPL
Section titled “BaseREPL”Bases: ABC
Base contract for REPL implementations used by LM agents.
Generic in StateT, the per-invoke state this REPL works in terms of: initialize
returns one and exec / aexec / add_to_namespace / drop_from_namespace
/ namespace take it back. An implementation declares its own state type and writes
class MyREPL(BaseREPL[MyREPLState]); nothing constrains what that type is, so a REPL whose
namespace lives in another process or another machine holds whatever it actually needs (a
connection, a container handle) rather than a namespace dict it would leave empty.
The REPL knows nothing about the return type or its validation. Return-type checking,
return-value validation, and REPL-code validation all live in hooks (ReturnType /
ValidateReturn / ValidateREPLCode) that act on the effect path; the REPL only
produces a Return carrying the value and the hooks decide whether it’s acceptable.
The __history__ record is the REPL’s: initialize binds it, the agent loop
hands each turn to update_repl_history, and repl_history_description
describes it to the agent, or is None for a REPL that binds no such name. The system
prompt describes the record exactly when the invoke binds it — the description is not None
and no hook withheld it with WithholdREPLHistory — so the prompt
never advertises a name the agent cannot reference.
BaseREPL.description
Section titled “BaseREPL.description”description: strThis REPL’s instructions for the system prompt, rendered from its own settings.
A REPL is its own configuration, so what it tells the agent comes from the object that
enforces it — PythonREPL offers raise as a finish only when it allows one.
Must be a non-empty string: the system prompt refuses an empty or non-string value with
ValueError rather than rendering an empty <repl_spec> element.
BaseREPL.repl_history_description
Section titled “BaseREPL.repl_history_description”repl_history_description: str | NoneThe agent-facing description of this REPL’s __history__ record, or None.
Returns the prompt text telling the agent what __history__ holds and what an entry’s
fields are; the system-prompt template splices it in verbatim and owns the framing. A
REPL with an in-process Python namespace binds the name and describes it; one whose
namespace lives elsewhere cannot bind it and returns None, and the system prompt then
omits its __history__ section. Otherwise the text must be non-empty: the prompt
refuses "" or a non-string with ValueError, as it does every description seam,
and drops the section on None alone.
BaseREPL.initialize
Section titled “BaseREPL.initialize”initialize(inputs: dict[str, object], subinvoke: Callable[..., object] | None, session_id: str = '', repl_history_withheld: bool = False) -> StateTBuild one invoke’s state — the REPL itself stays pure configuration.
Takes only invoke-time arguments. Everything that configures the REPL —
exec_timeout, the sandbox allow-lists, the finishing rules — is a constructor
parameter, so a REPL is configured by construction and produces a fresh StateT
per run. The REPL holds no per-invoke state, so one configured REPL serves many invokes:
repl = PythonREPL(exec_timeout=30.0)first = repl.initialize(inputs=..., subinvoke=None, session_id="a") # this REPL's state typesecond = repl.initialize(inputs=..., subinvoke=None, session_id="b") # an independent onerepl.exec(first, "x = 1", "0") # pass the state back to execThe returned state is threaded back into exec / add_to_namespace /
drop_from_namespace; the REPL never mutates self, so two invokes cannot bleed into
each other by construction. An implementation chooses what the state holds — the shipped
PythonREPL keeps the exec namespace in it, a REPL executing elsewhere
keeps whatever connects it to that elsewhere.
Parameters
inputs(dict[str, object]) — A dictionary of initial inputs to the REPL.subinvoke(Callable[..., object] | None) — The recursive sub-invoke primitive to bind in the REPL under the bare nameinvoke, or None to withhold it (recursion disabled).session_id(str) (default:'') — Unique session identifier for this REPL instance.repl_history_withheld(bool) (default:False) — Whether a hook withheld__history__from this invoke withWithholdREPLHistory. A REPL that binds the name (repl_history_descriptionis notNone) then binds none; a REPL that binds no such name ignores it.update_repl_historyis still called on every turn either way.
Returns:
A fresh instance of this REPL’s own state type, holding everything the run needs.
BaseREPL.exec
Section titled “BaseREPL.exec”exec(state: StateT, src: str, code_id: str) -> ExecResult[Any]Execute REPL code against state, mutating it in place.
Errors in the executed code should be captured and returned as a recoverable
Continue (its exception set, its output shown to the
agent) — with one carve-out: an exception that must escape the invoke (a
FatalError-category error, a non-Exception
signal, or an enclosing exec’s timeout/memory breach) re-raises out of
this call instead of becoming feedback, so it propagates past the agent.
Parameters
src(str) — The REPL code to execute.code_id(str) — The unique identifier for the REPL code.
Returns:
An ExecResult — exactly one of Continue
(ran, session continues; carries output and an optional recoverable
exception), Return (finished by returning
return_value), or Raise (finished by raising
exception). The REPL state is mutated in place.
BaseREPL.aexec
Section titled “BaseREPL.aexec”async aexec(state: StateT, src: str, code_id: str) -> ExecResult[Any]Async version of exec(). Runs exec() in a thread pool to avoid blocking the event loop.
Contextvar propagation: asyncio.to_thread copies the current context snapshot into the thread (reads see the caller’s values), but any contextvar a hook rebinds inside the thread is not visible back on the event loop — propagation is one-way (inward only).
Concurrency note: to_thread uses the default ThreadPoolExecutor (bounded to roughly min(32, cpu_count+4) threads). Under a wide asyncio.gather of agents that are all in REPL exec simultaneously, excess tasks queue behind the thread limit rather than running in true parallel — real concurrency is capped at the executor size.
BaseREPL.update_repl_history
Section titled “BaseREPL.update_repl_history”update_repl_history(state: StateT, llm_response: LLMResponse, exec_result: ExecResult[Any]) -> NoneUpdate the REPL history held in state with one turn.
Called by the agent loop once per iteration, after the turn’s result is final: the
hooks’ exit-time overrides are applied, so the result is what the agent was told
rather than what the REPL alone saw. Every turn the model answered is handed here,
including one a hook resolved without running exec.
It is called on every turn even when the invoke withheld __history__
(repl_history_withheld at initialize), and on a REPL that binds no such
name, so a REPL that keeps a history for some use other than the agent’s can still do
so. Withholding decides what the agent can reach, not what the REPL keeps.
PythonREPL keeps nothing on a withheld invoke.
Parameters
state(StateT) — This REPL’s per-invoke state, as returned byinitialize.llm_response(LLMResponse) — The whole response that produced the turn, so an implementation may record token counts, cost or providerextraas well as the text.exec_result(ExecResult[Any]) — The turn’s finalizedExecResult.
BaseREPL.add_to_namespace
Section titled “BaseREPL.add_to_namespace”add_to_namespace(state: StateT, entries: dict[str, object]) -> NoneBind entries raw into the REPL namespace (the per-turn AddToNamespace).
Binds the given objects verbatim into the REPL namespace and leaves the prompt
untouched — a variable is not an input, so nothing renders a prompt block for it.
Applied at REPLExecEnter before each turn’s code runs, so a hook may re-bind a name
every turn. Naming the sandbox key __builtins__ raises KeyEditDeniedError (at effect
composition, and again in implementations on a direct call).
Parameters
entries(dict[str, object]) — Dictionary of name -> value to bind verbatim.
Note
Implementation-specific — a REPL that doesn’t maintain a mutable namespace may treat this as a no-op.
BaseREPL.get_namespace
Section titled “BaseREPL.get_namespace”get_namespace(state: StateT) -> Mapping[str, object]The names currently bound in the REPL namespace, with their values.
Read twice per turn: at REPLExecEnter (before that turn’s AddToNamespace /
DropFromNamespace, populating REPLExecEnter.namespace — the proposal the effects
edit) and at REPLExecSend (after them and before the code runs, populating
REPLExecSend.namespace — the namespace the committed code is about to run
against). Returns the names the agent’s code is run against at the top level: invoke
inputs, hook-bound names and the agent’s assignments, plus, for a REPL with a builtins
layer (PythonREPL’s __builtins__), that layer read-only. The top-level names other
than that layer are exactly what drop_from_namespace can edit.
The returned mapping is copied by the caller before anything else touches the
namespace, so an implementation may return a live view; the variables’ values are never
copied, so a caller holding the snapshot holds the live objects (PythonREPL shows its
builtins layer as a copy, so it does not change under a kept snapshot). A REPL whose namespace it
cannot read cheaply (one in another process) may return a partial or empty mapping,
and should document which.
Parameters
state(StateT) — This REPL’s per-invoke state, as returned byinitialize.
Returns
Mapping[str, object]— A name-to-value mapping of the bound names.
BaseREPL.drop_from_namespace
Section titled “BaseREPL.drop_from_namespace”drop_from_namespace(state: StateT, names: Iterable[str], allow_missing: Iterable[str] = ()) -> NoneRemove names from the REPL namespace — the namespace counterpart of
add_to_namespace.
Applies a DropFromNamespace effect: each name is unbound so the agent’s next
turn sees it as undefined (referencing it raises NameError). Dropping a name
that isn’t currently bound raises MissingDropTargetError (a hook bug — a drop
of an absent name), UNLESS the name is in allow_missing (the set of names whose
DropFromNamespace opted into tolerating absence), in which case it is skipped. Naming
the compiler-sandbox key __builtins__ raises KeyEditDeniedError (at effect
composition, and again in implementations on a direct call), so import/attribute/
builtins policy can’t be unbound. An allowed builtin (len) that no variable shadows
is policy, not a bound name, so naming one is a missing target, as del len raises
NameError in Python. An implementation checks every name before removing any, so a
call that raises removes nothing.
Parameters
names(Iterable[str]) — The variable names to remove from REPL state.allow_missing(Iterable[str]) (default:()) — Names a drop may find unbound (fromDropFromNamespace(..., allow_missing=True)); an absent one is skipped, not raised.
Note
Implementation-specific — a REPL that doesn’t maintain a mutable namespace may treat this as a no-op.
PythonREPL
Section titled “PythonREPL”Bases: BaseREPL[PythonREPLState]
REPL implementation that enforces compile-time safety policies.
Uses native return / raise semantics: a top-level return / raise statement
(not nested inside a function or class) finishes the REPL, producing a Return / Raise
result. An AST transform rewrites such top-level statements into the finish mechanism.
Configuration flags
allow_raise: If True (default), a top-level
raiseexits the REPL with that exception.If False, only
returnis available for finishing (a top-levelraiseis left as ordinary Python and not treated as a finish).
PythonREPL.allowed_imports
Section titled “PythonREPL.allowed_imports”allowed_imports: tuple[str, ...]Module names the agent’s code may import (["*"] allows all) — read-only.
PythonREPL.allowed_attributes
Section titled “PythonREPL.allowed_attributes”allowed_attributes: tuple[str, ...]Attribute-name patterns the agent’s code may read — read-only.
PythonREPL.allowed_write_attributes
Section titled “PythonREPL.allowed_write_attributes”allowed_write_attributes: tuple[str, ...]Attribute-name patterns the agent’s code may write — read-only.
Derived from allowed_attributes at construction, not a constructor parameter.
PythonREPL.allowed_read_paths
Section titled “PythonREPL.allowed_read_paths”allowed_read_paths: tuple[str, ...]Glob patterns the agent is told to read files under — read-only.
Enforced only at the open builtin; see __init__ for the two layers and how
allowed_imports bounds the enforced one.
PythonREPL.allowed_write_paths
Section titled “PythonREPL.allowed_write_paths”allowed_write_paths: tuple[str, ...]Glob patterns the agent is told to write files under — read-only.
Enforced only at the open builtin; see __init__ for the two layers and how
allowed_imports bounds the enforced one.
PythonREPL.repl_history_description
Section titled “PythonREPL.repl_history_description”repl_history_description: strThe __history__ description (see BaseREPL.repl_history_description).
A constant: this REPL’s namespace is in-process, so it always binds the list, and it
describes the REPLHistoryEntry records it appends.
PythonREPL.description
Section titled “PythonREPL.description”description: strThe agent-facing description of this REPL, rendered from its own settings.
PythonREPL.__init__
Section titled “PythonREPL.__init__”__init__(*, exec_timeout: float | None = 30.0, exec_memory_limit: int | None = None, allow_timeout_pragma: bool = True, allow_raise: bool = True, repl_description_template: str = 'jaz/python_repl_description.jinja2', reject_finish_on_printed_output: bool = True, allowed_imports: list[str] | None = None, allowed_attributes: list[str] | None = None, allowed_read_paths: list[str] | None = None, allowed_write_paths: list[str] | None = None, traceback_verbosity: TracebackVerbosity | Literal['all', 'repl_only', 'message_only'] = TracebackVerbosity.ALL) -> NoneConfigure a REPL. The result is not yet usable — call initialize first.
Construction takes only configuration; the per-invoke state (inputs, the subinvoke
binding, the session id, the history list) is supplied by initialize.
Parameters
exec_timeout(float | None) (default:30.0) — Per-exec wall-clock bound in seconds (None = no timeout). Defaults to 30 s. Agent code can override it per execution unlessallow_timeout_pragmais False.exec_memory_limit(int | None) (default:None) — Process-wide RSS ceiling in bytes, per exec (None = off).allow_timeout_pragma(bool) (default:True) — If True (default), a leading# timeout: <seconds>comment in the code sets that execution’s wall-clock bound, overridingexec_timeoutwith no ceiling. Set False to makeexec_timeouta bound the agent cannot raise; the comment is then ordinary text and is not described in the prompt.allow_raise(bool) (default:True) — If True (default), a top-levelraiseexits the REPL with that exception. If False, onlyreturnis available for finishing.repl_description_template(str) (default:'jaz/python_repl_description.jinja2') — Jinja2 template name for the REPL description.reject_finish_on_printed_output(bool) (default:True) — If True (default), a finishingreturn/raiseis rejected (not executed) when the same code also printed output — the agent must review the output and re-run only thereturn/raise. If False, finishing is allowed even with printed output.allowed_imports(list[str] | None) (default:None) — Import allow-list.Noneapplies the fail-closed default (deny all);["*"]is the explicit allow-all. Granting any module that can reach the filesystem — directly, or by spawning a process that does — lifts the enforcement ofallowed_read_paths/allowed_write_pathsfor that route; the agent is still instructed to respect them.allowed_attributes(list[str] | None) (default:None) — Attribute allow-list.Noneapplies the secure default.allowed_read_paths(list[str] | None) (default:None) — gitignore-style globs for file reads.Noneapplies the fail-closed default (deny all). These patterns do two things, and only one of them is enforced: the agent is told to respect them — they are rendered into its instructions whatever else is configured — and theopenbuiltin refuses paths outside them. Nothing checks them on any other route to the filesystem, so granting a module that can reach it — directly, or by spawning a process that does — leaves the instruction and removes the enforcement. Past that point these are a rule the model is asked to follow rather than a limit it cannot exceed.allowed_write_paths(list[str] | None) (default:None) — gitignore-style globs for file writes.Noneapplies the fail-closed default (deny all). Instructed and enforced the same way asallowed_read_paths, with the sameallowed_importscaveat.traceback_verbosity(TracebackVerbosity | Literal['all', 'repl_only', 'message_only']) (default:TracebackVerbosity.ALL) — How much of the error traceback the agent sees, aTracebackVerbosityor one of its values as a literal string. A string whose value is not known statically — one read from your own config — needs wrapping:TracebackVerbosity(value), which raisesValueErroron an unknown one. The REPL’s engine frames above the agent’s code are always stripped; this controls the agent-relevant remainder: “all” (default; agent frame + library frames it called into), “repl_only” (agent frames only — drops library frames and their identity-leaking paths), or “message_only” (just the exception message).
Raises
ValueError— Iftraceback_verbosityis not a known value.
PythonREPL.initialize
Section titled “PythonREPL.initialize”initialize(inputs: dict[str, object], subinvoke: Callable[..., object] | None, session_id: str = '', repl_history_withheld: bool = False) -> PythonREPLStateBuild one invoke’s PythonREPLState; the REPL stays a reusable config template.
Takes only the invoke-time arguments — everything here belongs to one run rather than
to the REPL’s configuration, which was fixed at construction. Builds the namespace
(__builtins__ under this REPL’s sandbox policy, __history__, invoke, and a
binding per input) inside the returned state; the REPL itself is not touched, so one
configured instance serves every invoke.
Parameters
inputs(dict[str, object]) — The invoke’s inputs, bound under their own names.subinvoke(Callable[..., object] | None) — The recursive sub-invoke primitive to bind asinvoke, or None.session_id(str) (default:'') — Unique session identifier for linecache filenames.repl_history_withheld(bool) (default:False) — True to bind no__history__(the invoke withholds it); the state’srepl_historyis thenNoneand nothing is recorded.
Raises
KeyEditDeniedError— An input is named__builtins__, which holds the sandbox.
PythonREPL.update_repl_history
Section titled “PythonREPL.update_repl_history”update_repl_history(state: PythonREPLState, llm_response: LLMResponse, exec_result: ExecResult[Any]) -> NoneAppend one turn’s REPLHistoryEntry to state.repl_history (see
BaseREPL.update_repl_history); records nothing when the invoke withheld
__history__.
The entry records the response text (llm_response.content; an empty completion
records ""), the REPL output, and the recoverable exception. repl_output is
always a str: the output of a Continue, and "" for a terminal
Return/Raise, which carry none. repl_exception is the raw exception object of
a recoverable Continue and None otherwise: a terminal Raise’s exception
travels out of the invoke, not into history.
PythonREPL.add_to_namespace
Section titled “PythonREPL.add_to_namespace”add_to_namespace(state: PythonREPLState, entries: dict[str, object]) -> NoneBind entries into the REPL namespace raw — the per-turn, namespace-level
write applied at REPLExecEnter.
A variable is not an input: an input renders a prompt block, a variable does not. The prompt is untouched either way.
Naming __builtins__ raises KeyEditDeniedError: it holds the compiler sandbox, and is
not a namespace entry. Binds the name and nothing else: there is no inputs snapshot to
mirror.
Overwriting a name that is already bound in the REPL namespace (a top-level input, the
agent’s own variable, or a prior binding) raises REPLInputConflictError rather than
silently clobbering it — symmetric with AddInputs refusing to shadow a caller input, so
no hook can quietly replace a value the agent (or caller) put there. To re-bind a name
(e.g. to reset it each turn), DropFromNamespace it first, then AddToNamespace — the drop
makes the intent-to-replace explicit, and the agent loop applies drops before adds so the
name is free by the time this runs. The drop needs allow_missing=True if the name may
not be bound yet. (Names living in __builtins__ — the allowed
builtins and framework magics — are not checked here; this guards the variable namespace.)
Parameters
entries(dict[str, object]) — Dictionary of name -> value to bind (verbatim).
PythonREPL.get_namespace
Section titled “PythonREPL.get_namespace”get_namespace(state: PythonREPLState) -> Mapping[str, object]The agent-visible namespace: exactly the keys the agent’s globals() holds.
That is every variable (an invoke input, a hook’s binding, the agent’s own), and
__builtins__, shown as a read-only copy: it holds the allowed builtins and what the
framework provides, such as __history__, invoke and the last-expression _. A
fresh dict per call; the event it lands on freezes it. Other values are the live objects,
never copies.
Raises KeyEditDeniedError when agent code has replaced the
sandbox’s __builtins__, as exec does.
PythonREPL.drop_from_namespace
Section titled “PythonREPL.drop_from_namespace”drop_from_namespace(state: PythonREPLState, names: Iterable[str], allow_missing: Iterable[str] = ()) -> NoneRemove names from the REPL namespace — the namespace counterpart of
add_to_namespace.
A drop does what del name does in the agent’s code: it unbinds a key of the agent’s
globals(). Dropping a variable that shadows something in __builtins__ (an allowed
builtin such as len, or what the framework provides there, such as __history__
and invoke) removes only the shadow, so the original shows again. Dropping a name
that is not bound raises MissingDropTargetError, as del raises NameError,
including a name __builtins__ provides that no variable shadows. A drop of an absent
name is a hook bug (a typo, or a “re-drop every turn” pattern that should be
first-turn-only), so it fails loud rather than no-op’ing. This is still order-independent
and safe for the legitimate double-drop case: the framework unions the dropped names
first, and this applies the set once against the pre-drop namespace, so two hooks
dropping the same present name coalesce to a single deletion and never trip the check.
A name in allow_missing (its DropFromNamespace opted into tolerating absence, e.g.
a first-turn input drop when a DropInputs may have already un-passed the input) is
skipped when absent instead of raising.
Naming __builtins__ itself raises KeyEditDeniedError: it holds the compiler
sandbox, and unbinding the dict would strip import/attribute/builtins policy. A refused
call removes nothing.
PythonREPL.exec
Section titled “PythonREPL.exec”exec(state: PythonREPLState, src: str, code_id: str) -> ExecResult[Any]Executes REPL code and mutates state in place.
Runs the Python code in the REPL. A top-level return statement exits the REPL
with that return value; a top-level raise (when allow_raise) exits with that
exception. If an error occurs during execution, the error is captured and returned
back into the REPL as a recoverable Continue — except a fatal
exception (FatalError, non-Exception signals) or an
enclosing exec’s timeout/memory breach, which re-raises out of this call so it
propagates out of the invoke. A KeyEditDeniedError re-raises
too, before anything is compiled when an earlier exec replaced the sandbox’s
__builtins__ (through globals()) and at the end of the exec that does so: that
state cannot run code again, so the invoke fails rather than being shown the error.
The code sets its own wall-clock bound with a # timeout: <seconds> comment among the
lines that open it (before any real code), which overrides the configured
exec_timeout for this call only. A malformed value there is reported
as a recoverable Continue and the code is not executed. Configuring
allow_timeout_pragma=False turns that comment back into ordinary text.
Parameters
src(str) — The REPL command to executecode_id(str) — The unique identifier for the REPL code
Returns
ExecResult[Any]— class:~jaz.repl.ExecResult— exactly one ofContinueExecResult[Any]— (ran, session continues; carriesoutputand an optional recoverableExecResult[Any]—exception),Return(finished by returningreturn_value),ExecResult[Any]— class:~jaz.repl.Raise(finished by raisingexception). The REPL state isExecResult[Any]— mutated in place.
PythonREPL.aexec
Section titled “PythonREPL.aexec”async aexec(state: PythonREPLState, src: str, code_id: str) -> ExecResult[Any]Async exec: the code runs as a coroutine on the event loop, so the agent
can use top-level await (e.g. result = await ainvoke(...)). The whole
submission takes the async path (there is no separate command syntax to route
synchronously); native return / raise still finish the REPL.
The # timeout: <seconds> pragma applies here exactly as it does to exec.
Like sync exec, this does not write __history__ — the agent loop calls
update_repl_history with the turn’s final result — and like it, a replaced
sandbox __builtins__ re-raises as KeyEditDeniedError.
PythonREPLState
Section titled “PythonREPLState”The per-invoke state of a PythonREPL run — everything one initialize() builds.
A REPL is configured by construction (its sandbox policy, timeouts, finishing rules) and initialized per invoke; this holds exactly the per-invoke half. With the state here rather than on the REPL, the REPL is pure configuration and one instance safely serves many invokes — there is nothing per-run for two of them to share.
Note the two distinct lifetimes: this is per-invoke state. Per-exec scratch (the REPL’s
per-turn bookkeeping) does not belong here — it lives for one exec call and is threaded
locally, not stored across turns.
The dataclass is frozen, but that constrains rebinding, not contents: a writer mutates
exec_globals in place and never reassigns a field.
Attributes
exec_globals(dict[str, object]) — The live globals mapping the agent’s code runs against. Hooks see it throughPythonREPL.get_namespace, a copy with__builtins__shown read-only.session_id(str) — Identifier for the invoke this state belongs to; empty when none was given.sandbox_builtins(dict[str, object]) — The dictinitializeinstalled asexec_globals["__builtins__"]. The REPL checks, before it reads or runs anything, that the key still holds this very object; agent code that replaced it (throughglobals()) has corrupted the state, and the exec that did so fails withKeyEditDeniedErrorat its end, as does every later read of the sandbox.repl_history(list[object] | None) — The REPL-history list the agent’s code reads, oneREPLHistoryEntryper turn, appended to byPythonREPL.update_repl_history;Nonewhen the history is withheld.
PythonREPLState.__init__
Section titled “PythonREPLState.__init__”__init__(exec_globals: dict[str, object] = dict(), session_id: str = '', sandbox_builtins: dict[str, object] = dict(), repl_history: list[object] | None = None) -> NoneTracebackVerbosity
Section titled “TracebackVerbosity”Bases: StrEnum
How much of an error traceback the agent is shown.
The REPL’s own engine frames — the .py plumbing that exec’s the
agent’s code, sitting above the agent’s <repl_...> frame in the stack —
are ALWAYS stripped: they are an artifact of the REPL implementation, never
part of the agent’s error. These levels say how much of the remaining,
agent-relevant traceback to keep (most → least): ALL ("all", the default)
keeps the agent’s own frames plus any library frames its code called into;
REPL_ONLY ("repl_only") keeps only the agent’s own frames; MESSAGE_ONLY
("message_only") keeps no frames — just the exception line.
TracebackVerbosity.ALL
Section titled “TracebackVerbosity.ALL”All agent-relevant frames: the agent’s own <repl_...> frame(s) plus
any library frames its code called into (e.g. a tool/proxy that raised).
This is the historical default.
TracebackVerbosity.REPL_ONLY
Section titled “TracebackVerbosity.REPL_ONLY”Only the agent’s own <repl_...> frames — every one in the chain, even
a frame reached via a library callback (e.g. the agent passes f to an
external g and g calls f). All library frames are dropped. Hides
library internals — and their file paths, which can leak the benchmark/
harness identity — while keeping the agent’s failing line(s) and the
exception message.
TracebackVerbosity.MESSAGE_ONLY
Section titled “TracebackVerbosity.MESSAGE_ONLY”No frames at all — just ExceptionType: message.
REPLHistoryEntry
Section titled “REPLHistoryEntry”One __history__ entry — what PythonREPL.update_repl_history appends per turn.
__history__ is a plain list of one entry per iteration in order — [0] first, [-1]
most recent — with no init snapshot, so __history__[0] is the first iteration. Another
REPL may record an entirely different shape, or none.
Attributes
llm_response(str) — The full model output that produced the turn — the raw response text, not the parsed code;""for an empty completion.repl_output(str) — What the turn’s code printed (stdout, plus the traceback on a recoverable error). Always astr: a terminalReturn/Raiseturn records"".repl_exception(BaseException | None) — The raw exception object from a recoverable error, orNoneon a clean success and on every terminal turn.
REPLHistoryEntry.__init__
Section titled “REPLHistoryEntry.__init__”__init__(llm_response: str, repl_output: str, repl_exception: BaseException | None) -> NoneExecResult
Section titled “ExecResult”The outcome of running one REPL turn: executing a turn’s code yields exactly one of three results.
Continue— the code ran and the session continues to the next turn.Return— the code finished the run by returning a value.Raise— the code finished the run by raising an exception.
An ExecResult is what a hook receives as event.exec_result, and what it wraps in
jaz.hooks.effects.SupplyExecResult / ModifyExecResult to supply or replace the outcome of a
turn.
Continue
Section titled “Continue”Bases: NamedTuple
An ExecResult for a turn that ran and continues to the next turn.
Covers both a clean success and a recoverable error as one type, distinguished by
exception: they share control flow (feed output back, loop again) and payload,
so the error case is a Continue carrying an exception rather than a separate
variant.
Attributes
output(str) — The output from the REPL execution, including error information on a recoverable error.exception(BaseException | None) — An optional exception object indicating any exception that occurred during execution;Noneon a clean success. (Terminal raises areRaiseinstead ofContinue.)
Return
Section titled “Return”Bases: NamedTuple
An ExecResult for a turn that finishes the REPL session by returning a value that
propagates out of the invoke.
Attributes
return_value(ReturnT) — The value returned by the code.
Bases: NamedTuple
An ExecResult for a turn that finishes the REPL session by raising an exception
that propagates out of the invoke.
Attributes
exception(BaseException) — The exception object that was raised.
TerminalExecResult
Section titled “TerminalExecResult”The subset of ExecResult a run can terminate on: a Return or a
Raise, never a Continue.
A single REPL turn may end on any of the three ExecResult kinds, but an invoke only
ever finishes on a terminal one — a Continue appends an observation and loops again, so
by the time the invoke’s result exists the loop has already broken on a Return /
Raise. This alias names that narrower domain so the invoke transform boundary can require
it — see jaz.hooks.effects.ModifyInvokeResult and jaz.hooks.events.InvokeComplete — rather
than accept the full ExecResult union and lean on a runtime check.