Skip to content

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 ...).

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.

description: str

This 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.

repl_history_description: str | None

The 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.

initialize(inputs: dict[str, object], subinvoke: Callable[..., object] | None, session_id: str = '', repl_history_withheld: bool = False) -> StateT

Build 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 type
second = repl.initialize(inputs=..., subinvoke=None, session_id="b") # an independent one
repl.exec(first, "x = 1", "0") # pass the state back to exec

The 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 name invoke, 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 with WithholdREPLHistory. A REPL that binds the name (repl_history_description is not None) then binds none; a REPL that binds no such name ignores it. update_repl_history is still called on every turn either way.

Returns:

A fresh instance of this REPL’s own state type, holding everything the run needs.

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.

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.

update_repl_history(state: StateT, llm_response: LLMResponse, exec_result: ExecResult[Any]) -> None

Update 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 by initialize.
  • llm_response (LLMResponse) — The whole response that produced the turn, so an implementation may record token counts, cost or provider extra as well as the text.
  • exec_result (ExecResult[Any]) — The turn’s finalized ExecResult.
add_to_namespace(state: StateT, entries: dict[str, object]) -> None

Bind 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.

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 by initialize.

Returns

  • Mapping[str, object] — A name-to-value mapping of the bound names.
drop_from_namespace(state: StateT, names: Iterable[str], allow_missing: Iterable[str] = ()) -> None

Remove 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 (from DropFromNamespace(..., 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.

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 raise exits the REPL with that exception.

If False, only return is available for finishing (a top-level raise is left as ordinary Python and not treated as a finish).

allowed_imports: tuple[str, ...]

Module names the agent’s code may import (["*"] allows all) — read-only.

allowed_attributes: tuple[str, ...]

Attribute-name patterns the agent’s code may read — read-only.

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.

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.

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.

repl_history_description: str

The __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.

description: str

The agent-facing description of this REPL, rendered from its own settings.

__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) -> None

Configure 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 unless allow_timeout_pragma is 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, overriding exec_timeout with no ceiling. Set False to make exec_timeout a 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-level raise exits the REPL with that exception. If False, only return is 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 finishing return/raise is rejected (not executed) when the same code also printed output — the agent must review the output and re-run only the return/raise. If False, finishing is allowed even with printed output.
  • allowed_imports (list[str] | None) (default: None) — Import allow-list. None applies 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 of allowed_read_paths / allowed_write_paths for that route; the agent is still instructed to respect them.
  • allowed_attributes (list[str] | None) (default: None) — Attribute allow-list. None applies the secure default.
  • allowed_read_paths (list[str] | None) (default: None) — gitignore-style globs for file reads. None applies 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 the open builtin 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. None applies the fail-closed default (deny all). Instructed and enforced the same way as allowed_read_paths, with the same allowed_imports caveat.
  • traceback_verbosity (TracebackVerbosity | Literal['all', 'repl_only', 'message_only']) (default: TracebackVerbosity.ALL) — How much of the error traceback the agent sees, a TracebackVerbosity or 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 raises ValueError on 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 — If traceback_verbosity is not a known value.
initialize(inputs: dict[str, object], subinvoke: Callable[..., object] | None, session_id: str = '', repl_history_withheld: bool = False) -> PythonREPLState

Build 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 as invoke, 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’s repl_history is then None and nothing is recorded.

Raises

  • KeyEditDeniedError — An input is named __builtins__, which holds the sandbox.
update_repl_history(state: PythonREPLState, llm_response: LLMResponse, exec_result: ExecResult[Any]) -> None

Append 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.

add_to_namespace(state: PythonREPLState, entries: dict[str, object]) -> None

Bind 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).
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.

drop_from_namespace(state: PythonREPLState, names: Iterable[str], allow_missing: Iterable[str] = ()) -> None

Remove 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.

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 execute
  • code_id (str) — The unique identifier for the REPL code

Returns

  • ExecResult[Any] — class:~jaz.repl.ExecResult — exactly one of Continue
  • ExecResult[Any] — (ran, session continues; carries output and an optional recoverable
  • ExecResult[Any] — exception), Return (finished by returning return_value),
  • ExecResult[Any] — class:~jaz.repl.Raise (finished by raising exception). The REPL state is
  • ExecResult[Any] — mutated in place.
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.

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 through PythonREPL.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 dict initialize installed as exec_globals["__builtins__"]. The REPL checks, before it reads or runs anything, that the key still holds this very object; agent code that replaced it (through globals()) has corrupted the state, and the exec that did so fails with KeyEditDeniedError at its end, as does every later read of the sandbox.
  • repl_history (list[object] | None) — The REPL-history list the agent’s code reads, one REPLHistoryEntry per turn, appended to by PythonREPL.update_repl_history; None when the history is withheld.
__init__(exec_globals: dict[str, object] = dict(), session_id: str = '', sandbox_builtins: dict[str, object] = dict(), repl_history: list[object] | None = None) -> None

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.

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.

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.

No frames at all — just ExceptionType: message.

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 a str: a terminal Return/Raise turn records "".
  • repl_exception (BaseException | None) — The raw exception object from a recoverable error, or None on a clean success and on every terminal turn.
__init__(llm_response: str, repl_output: str, repl_exception: BaseException | None) -> None

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.

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; None on a clean success. (Terminal raises are Raise instead of Continue.)

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.

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.