jaz.hooks.events
New to JAZ? This is generated API reference. Start with the docs and the concepts overview.
Public API of the jaz.hooks.events submodule (import from jaz.hooks.events, e.g. from jaz.hooks.events import ...).
Every event has a matching handler on jaz.hooks.Hook, named after it
(LLMQueryEnter → on_llm_query_enter). A handler observes the event and returns a
list of effects; returning effects is the only way a hook influences the run. Which effects
are accepted depends on the event — each event class documents its own allowed set, and an
effect returned at an event outside that set raises
InvalidEffectError (out-of-stage effects are hook bugs and fail
loudly, never silently no-op). A hook that treats every event alike overrides on_any
instead:
from jaz.hooks import Hookfrom jaz.hooks.effects import Abort, Effectfrom jaz.hooks.events import LLMQueryEnter
class StopAfterTenTurns(Hook): def on_llm_query_enter(self, event: LLMQueryEnter) -> list[Effect]: if event.iteration >= 10: # iterations are 0-based return [Abort(error=RuntimeError("too many turns"))] return []Each span’s events follow one pipeline of value states:
proposal ──[edits]──▸ committed input ──[work or supply]──▸ raw result ──[modify]──▸ outcome
*Enter observes the proposal controls edits + abort fires always*Send observes the committed input controls supply + abort fires iff the input committed*Complete observes the raw result controls modify + abort fires iff a raw result exists*Exit observes the outcome union controls abort (per-turn) fires whenever the span openedEvents mark value states becoming fixed, not phases of the machinery: an event’s
payload is the commit of the previous stage’s effects, so no event can observe its own
composition’s output — only the next event can carry it. *Send therefore fires on the
supplied/replayed path too (the input commit is real even when no provider is called), and
*Exit carries a tagged outcome union (Completed[...] | Aborted | Failed — the variant
IS the span status, its payload the post-transform result or the terminating exception),
so an interval that opened always closes, with the true outcome. A
BlackboardWrite is valid at every event, these included; beyond it
the per-turn LLMQueryExit / REPLExecExit accept an Abort on
every arm, and InvokeExit accepts nothing.
The events, by span:
InvokeEnter/InvokeSend/InvokeComplete/InvokeExit— one quadruple per invoke.LLMQueryEnter/LLMQuerySend/LLMQueryComplete/LLMQueryExit— the per-turn LLM call.LLMQueryRetry— fired per retry attempt of that call.REPLExecEnter/REPLExecSend/REPLExecComplete/REPLExecExit— the turn’s REPL execution. This is the one conditional span: it opens only on a turn that reaches execution, so it is skipped when the query span ended without getting there — the call errored, or a hook aborted at any of theLLMQueryevents,LLMQueryCompleteandLLMQueryExitincluded, which abort after a response exists. What does not skip it is the response’s content:BaseProtocol.parseis contracted to return the code and never raise, and an empty parse is empty code, so an empty, blank or prose-only response opens the span like any other. (A protocol that raises anyway is terminal — nothing catches it — and ends the invoke rather than skipping the span.)
The shape of every event follows from four principles:
- Ambient invoke context rides every event. What belongs to the invoke rather than to any
one span —
config,scope,hooks,blackboard, plus the identityinvoke_id/depth— is a baseEventfield, stamped on every event by the dispatcher. None of it is a proposal: no*Entereffect edits it and no*Sendcarries an edit record for it. (blackboardstill advances between events, byBlackboardWrite, andhooksis the live active set.) - An
*Entercarries what its effects can edit, as the proposal. Under the field’s own name:inputs,messages,codeandnamespace. - A
*Sendcarries the same fields committed, plus one<thing>_editsper field.input_edits,message_edits,code_edits,namespace_edits— each aResolved<Thing>Editsof self-contained records of what every enter-time effect did, one sequence per effect named by its verb (adds/drops,inserts/deletes), ordered by the coordinate a record names (name, position, offset) and, where a coordinate can repeat, by the order the fold applied them within it — a drop record carrying the value it removed, read off the Enter snapshot. Only same-slot message adds and same-offset code inserts can share a coordinate; each sequence’s own docstring says what its order resolves to there. - An effect edits the field it is named for, and only that.
DropInputseditsinputs(ajaz.scopevalue is not an input);AddToNamespaceeditsnamespace.
Which gives, per span:
┌─────────────────────┬──────────────────────┬──────────────────────┬──────────────────────────────────┐│ │ Invoke │ LLMQuery │ REPLExec │├─────────────────────┼──────────────────────┼──────────────────────┼──────────────────────────────────┤│ Enter: the proposal │ inputs │ messages │ code, namespace ││ Send: committed │ inputs │ messages │ code, namespace ││ Send: the edits │ input_edits │ message_edits │ code_edits, namespace_edits ││ ← effects │ AddInputs/DropInputs │ AddMessages/ │ InsertCode/DeleteCode, ││ │ │ DropMessages │ AddToNamespace/DropFromNamespace ││ record sequences │ adds, drops │ adds, drops │ inserts, deletes; adds, drops ││ Enter → Send shape │ same │ same (stamped) │ same ││ Loop → span handoff │ send(inputs) │ send(shown_messages) │ send(namespace) │└─────────────────────┴──────────────────────┴──────────────────────┴──────────────────────────────────┘Outside that shape, and each deliberate:
DisableRecursionandWithholdREPLHistoryareInvokeEntereffects that edit no field (they withholdinvokeand__history__, which are not inputs), so they are recorded asInvokeSend.recursion_disabledandInvokeSend.repl_history_withheldrather than inside any<thing>_edits; their result shows one span later, as the absence ofinvokeor__history__fromnamespace["__builtins__"]inREPLExecEnter.namespace.LLMQueryRetryis not a value-state event, so the stage table above does not describe it: it fires per retry rather than at a commit, only on this span, and accepts no effects. It rides the retry policy’s before-sleep, so it counts the attempts that are followed by another one: a turn whose first attempt succeeds never fires it, and the final failure — the one that exhausts the policy and propagates — fires nothing either. It has no*Enter/*Sendcounterpart because a retry commits nothing, and no counterpart on the other spans because only the provider call is retried.*Exitis terminal on every span, but the two per-turn spans acceptAbortthere, on every arm, whileInvokeExitstays observation-only. The per-turn opening buys aborting on the post-transform result — a re-priced cost, say. An invoke aborting at its own terminalExitwould instead make that event’s payload diverge from what the caller receives, andInvokeCompletealready governs the final result.
Events also carry coordinates that place them, which the table does not show because they are
neither proposal nor edit and no effect touches them: which turn (iteration, on every
per-turn event), which invoke and how deep (invoke_id, depth), when (timestamp,
a base field like the ambient context but varying per event rather than per invoke), and on
InvokeEnter which invoke and which of its turns spawned this one
(parent_invoke_id, parent_repl_iteration). The payload a *Complete or *Exit
carries is not in the table either; those stages are the pipeline’s, described above it.
Two deliberate non-uniformities in the records: only the message records carry persistent
(only the message buffer has a per-query vs carried-forward distinction), and
REPLExecEnter.namespace/REPLExecSend.namespace are exact for PythonREPL
and best-effort for a REPL whose namespace it cannot read (see BaseREPL.get_namespace).
An observer written against one Send reads the others the same way.
Base class for all events.
Events represent discrete points in the agent’s execution lifecycle where hooks can observe and influence behavior.
Every event carries invoke_id (the invoke it belongs to), depth (that invoke’s
nesting depth — 1 for a top-level invoke, one more per sub-invoke), config
(the effective configuration the invoke runs under, overrides applied), scope (the
resolved jaz.scope values in effect for it, as a read-only mapping) and hooks
(the hook instances in effect for it).
Every event carries timestamp — the moment it was emitted to hooks, as a
timezone-aware UTC datetime. Durations are
consumer arithmetic over two events’ timestamps: Exit.timestamp - Enter.timestamp
is a span’s boundary-to-boundary interval, and the Send/Complete stamps give
the per-stage breakdown. There are no interval fields on any event.
Every event also carries blackboard — the per-invoke key-value store hooks use to
receive caller data and to coordinate with one another, as a read-only Mapping.
Read it like a dict (event.blackboard.get("label")); the only way to write is to
return a BlackboardWrite effect, which the dispatcher applies
after every hook for the event has run. A write is therefore invisible to the event that
produced it and visible from the next event onward, so producer and consumer hooks
coordinate without depending on dispatch order.
One board per invoke, and a nested invoke gets its own. “Per-invoke” means one board
each, not one shared down the tree: a sub-invoke seeds a fresh board before its own
InvokeEnter, so no board write crosses the boundary in either direction — the child
does not see what the parent wrote, and the parent’s board is unchanged by the child.
Values still cross, just not on the board. Downward, seed them:
Hook.blackboard_seed runs again for every invoke the hook is active in, which is
what an ambient with MyHook(): gives you and a per-call invoke(MyHook(), ...)
deliberately does not. Upward, or across siblings, the carrier is the hook instance’s own
attributes — a hook that stores something while the child runs can write it to the parent’s
board at the parent’s next event. That is the supported way to accumulate across invokes;
the board is not.
A key that has not been produced is simply absent: board[key] raises KeyError
and board.get(key) returns None (or the supplied default). “Not produced yet” and
“never produced” read identically on purpose — a consumer must not be able to tell whether
a producer hook has not run yet or is not active at all. Read defensively: prefer
.get(key, default) and treat absence as “no value this generation.”
Event objects must be treated as immutable and should never be mutated. Side effects are
emitted by returning effects from the event handler (see Hook).
That rule is wider than what the framework enforces, so treat it as absolute rather than as
“whatever raises”. Enforcement stops at the container: rebinding a field raises, and the
mappings and sequences an event carries are copies that reject writes. Past that line
nothing is promised — what those containers hold is the framework’s own state. Some of it
happens to be immutable (an exec result is a NamedTuple, a Config is frozen), and the
rest is live: input and scope values, message dicts, namespace bindings, the components
inside config, the peer instances in hooks, the LLMResponse on an
LLMQueryComplete, the value on an edit record. Mutating one of those changes the run,
with none of the ordering guarantees that make effects safe. Read through an event; write by
returning effects.
Event.__init__
Section titled “Event.__init__”__init__(*, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneCompleted
Section titled “Completed”The span produced its normal result, carried as result.
One of the three outcome variants every *Exit event’s outcome field holds
(Completed[...] | Aborted | Failed). The variant is the span status: match on the
type to branch on how the span ended, and read the payload off the matched variant —
there is no parallel status enum to keep in sync.
T is the span’s payload type: LLMResponse for the LLM query,
ExecResult for the REPL execution, Return | Raise for the
invoke.
Completed.__init__
Section titled “Completed.__init__”__init__(result: T) -> NoneAborted
Section titled “Aborted”The span was deliberately stopped by an Abort;
exception carries the abort’s error.
See Completed for the outcome-union contract.
Aborted.__init__
Section titled “Aborted.__init__”__init__(exception: BaseException) -> NoneFailed
Section titled “Failed”The span’s machinery unwound on an in-flight exception before a result existed;
exception carries the propagating error (which still propagates after the exit
event fires).
See Completed for the outcome-union contract.
Failed.__init__
Section titled “Failed.__init__”__init__(exception: BaseException) -> NoneLLMQueryOutcome
Section titled “LLMQueryOutcome”REPLExecOutcome
Section titled “REPLExecOutcome”InvokeOutcome
Section titled “InvokeOutcome”REPLExecEnter
Section titled “REPLExecEnter”Bases: Event
Fired before executing parsed REPL code.
Not every turn. It fires only on a turn that reaches execution, so a turn is skipped
entirely when the LLM call itself errors, or when a hook emits an Abort at any of
the LLMQuery events — including LLMQueryComplete and LLMQueryExit,
which abort after a response exists. The response’s content never skips it: an empty or
unparseable response is empty or nonsense code, which the REPL judges.
Allowed effects:
Abort— abort the invoke.AddToNamespace— bind names into the REPL namespace before the code runs.DropFromNamespace— unbind names from the REPL namespace before the code runs.InsertCode— insert source into the proposed code before it runs.DeleteCode— delete a character range from the proposed code before it runs.
InsertCode / DeleteCode edit the code (the LLM-message twins are AddMessages /
DropMessages); AddToNamespace / DropFromNamespace edit the namespace. Both edit this
event’s proposal — code here is the LLM’s original, and the composed edits produce the
committed code that REPLExecSend carries and the REPL runs.
Suppliers do not compose here: SupplyExecResult is a REPLExecSend
effect — a supplier decides on the basis of the committed code, which at this event
composition may still rewrite.
Attributes
iteration(int) — The agent-loop iteration this execution belongs to.code(str) — The REPL source proposed by the LLM, before any enter-timeInsertCode/DeleteCodeedits (which produce the committed code carried byREPLExecSend).namespace(Mapping[str, object]) — The REPL namespace as it stands before this turn’sAddToNamespace/DropFromNamespaceedits — the agent’sglobals()(inputs, hook bindings, the agent’s own assignments from earlier turns, and__builtins__as a read-only copy, which holds the allowed builtins and the framework’sinvokeand__history__), as a read-only snapshot whose variables’ values are the live objects. What the REPL reports viaBaseREPL.get_namespace, so a REPL whose namespace it cannot read may report less. The edited-then-committed namespace ridesREPLExecSend.namespace.
REPLExecEnter.__init__
Section titled “REPLExecEnter.__init__”__init__(iteration: int, code: str, namespace: Mapping[str, object], *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneREPLExecSend
Section titled “REPLExecSend”Bases: Event
Fired when an execution’s code has committed — code + namespace deltas are final.
Fires after REPLExecEnter’s AddToNamespace / DropFromNamespace have
been applied to the REPL namespace, before the code runs — including when a supply then
short-circuits the execution (the namespace deltas committed either way).
Allowed effects:
SupplyExecResult— supply a result in place of running the code; the code is not executed and the supplied result becomes the turn’s raw result.Abort— abort the invoke, declining the committed code.
Attributes
iteration(int) — The agent-loop iteration this execution belongs to.code(str) — The REPL source about to be executed (or short-circuited) — the enter-time proposal after anyInsertCode/DeleteCodeedits were folded in.code_edits(ResolvedCodeEdits) — The enter-time edits that producedcode, as self-contained records (seeResolvedCodeEdits).namespace_edits(ResolvedNamespaceEdits) — The enter-time edits that producednamespacefromREPLExecEnter.namespace, as self-contained records (seeResolvedNamespaceEdits).namespace(Mapping[str, object]) — The REPL namespace the committed code runs against — the agent’sglobals()(inputs, hook bindings, the agent’s own assignments, and__builtins__as a read-only copy, which holds the allowed builtins and the framework’sinvokeand__history__) after this turn’s deltas. The mapping is read-only; the variables’ values are the live objects. What the REPL reports viaBaseREPL.get_namespace, so a REPL whose namespace it cannot read may report less.
REPLExecSend.__init__
Section titled “REPLExecSend.__init__”__init__(iteration: int, code: str, namespace: Mapping[str, object], code_edits: ResolvedCodeEdits = ResolvedCodeEdits(), namespace_edits: ResolvedNamespaceEdits = ResolvedNamespaceEdits(), *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneResolvedCodeEdits
Section titled “ResolvedCodeEdits”This execution’s enter-time code edits as self-contained, pre-resolved records.
inserts records InsertCode, deletes records DeleteCode — each
sequence named by the verb of the effect it records, the rule every <thing>_edits
field follows. A record carries what the edit did, including what it removed: a delete
record is one run of removed source after the DeleteCode ranges are unioned, so the
delete records never overlap (see CodeDeleteRecord).
Ordering: inserts in application order (by resolved offset, hook order within one);
deletes by resolved start (disjoint, so that is a total order).
ResolvedCodeEdits.__init__
Section titled “ResolvedCodeEdits.__init__”__init__(inserts: Sequence[CodeInsertRecord] = (), deletes: Sequence[CodeDeleteRecord] = ()) -> NoneResolvedNamespaceEdits
Section titled “ResolvedNamespaceEdits”This execution’s enter-time namespace edits as self-contained records.
adds records AddToNamespace, drops records DropFromNamespace — each
sequence named by the verb of the effect it records. A drop record carries the value it
unbound, read off REPLExecEnter.namespace (the namespace before the drops).
Ordering: both sequences sorted by name — a record’s coordinate, the rule every
<thing>_edits sequence follows.
ResolvedNamespaceEdits.__init__
Section titled “ResolvedNamespaceEdits.__init__”__init__(adds: Sequence[NamespaceAddRecord] = (), drops: Sequence[NamespaceDropRecord] = ()) -> NoneCodeInsertRecord
Section titled “CodeInsertRecord”One InsertCode edit folded into this execution’s committed code.
Attributes
text(str) — The inserted source.position(int) — The resolved offset into the enter-time code the text was inserted at (a negativeatcounts from the end; this is the absolute result).
CodeInsertRecord.__init__
Section titled “CodeInsertRecord.__init__”__init__(text: str, position: int) -> NoneCodeDeleteRecord
Section titled “CodeDeleteRecord”One run of source the DeleteCode edits removed from this execution’s
enter-time code.
A record is what was removed, not which effect asked: overlapping and adjacent
DeleteCode ranges are unioned into disjoint runs, one record each, so the records
never overlap and their text sums to exactly what the committed code lost; an empty
range removes nothing and leaves no record.
Attributes
start(int) — The resolved start offset of the run into the enter-time code.end(int) — The resolved end offset (exclusive).text(str) — The deleted source —code[start:end]of the enter-time code.
CodeDeleteRecord.__init__
Section titled “CodeDeleteRecord.__init__”__init__(start: int, end: int, text: str) -> NoneNamespaceAddRecord
Section titled “NamespaceAddRecord”One name an AddToNamespace bound into the namespace before this execution.
Attributes
name(str) — The bound name.value(object) — The bound object, verbatim.
NamespaceAddRecord.__init__
Section titled “NamespaceAddRecord.__init__”__init__(name: str, value: object) -> NoneNamespaceDropRecord
Section titled “NamespaceDropRecord”One name a DropFromNamespace unbound from the namespace before this execution.
Attributes
name(str) — The dropped name.value(object | UnsetType) — The object that was unbound, orUNSETwhen nothing was — the name was absent (anallow_missingdrop) or the REPL cannot report values (seeBaseREPL.get_namespace).
NamespaceDropRecord.__init__
Section titled “NamespaceDropRecord.__init__”__init__(name: str, value: object | UnsetType) -> NoneREPLExecComplete
Section titled “REPLExecComplete”Bases: Event
Fired when an execution’s raw result exists — the transform boundary.
Fires with the result the producer made: the value repl.exec returned, or the result
a SupplyExecResult supplied at REPLExecSend (a supplied result is a
result; only aborts divert). It does not fire when the span unwinds on an
in-flight exception (no raw result exists — transformers never run during unwind).
Allowed effects:
ModifyExecResult— replace the execution result with a different one.Abort— abort the invoke.
Attributes
iteration(int) — The agent-loop iteration this execution belongs to.exec_result(ExecResult) — The raw result the producer made — aContinue,Return, orRaise— before any transform composes.
REPLExecComplete.__init__
Section titled “REPLExecComplete.__init__”__init__(iteration: int, exec_result: ExecResult, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneREPLExecExit
Section titled “REPLExecExit”Bases: Event
Fired when the execution span closes, with the turn’s final outcome.
Fires on the turns REPLExecEnter did. outcome is the tagged union
REPLExecOutcome: Completed carries the turn’s final,
post-transform result (outcome.result — any ModifyExecResult composed at
REPLExecComplete already applied); Aborted means a hook’s
Abort at one of this execution’s control stages ended the invoke
(outcome.exception carries the abort’s error, which propagates after the event
fires); Failed carries every other error that escaped before a result existed
(outcome.exception; it still propagates after the event fires).
Allowed effects — narrow: a hook may return Abort (and only Abort), on every
arm. On the Completed arm this stops the run on the basis of the final,
post-transform result (the thing REPLExecComplete can’t see, since a
ModifyExecResult there composes after every Complete hook has run). On the
Aborted / Failed arms a terminating exception is already unwinding, so an abort
here cannot replace it: it is folded into it via an ExceptionGroup (the in-flight
exception stays present, so is_fatal still governs how far the combined error travels). Any
effect other than Abort raises InvalidEffectError on the Completed
arm and is dropped with an error log on the abnormal arms (a loud raise there would replace the
exception that must win). To transform a result rather than abort on it, use
ModifyExecResult at REPLExecComplete.
Timing: like every event, this exit carries only timestamp
(its emission time); the span’s duration is Exit.timestamp - Enter.timestamp.
Attributes
iteration(int) — The agent-loop iteration this execution belongs to.outcome(REPLExecOutcome) — How the span ended, with its payload — match on the variant (Completed[ExecResult] | Aborted | Failed).
REPLExecExit.__init__
Section titled “REPLExecExit.__init__”__init__(iteration: int, outcome: REPLExecOutcome, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneLLMQueryEnter
Section titled “LLMQueryEnter”Bases: Event
Fired once per turn, before making an LLM API call.
Fires on every turn — it is the always-present per-turn boundary, unlike the conditional REPL execution events (skipped when the response fails to parse). That makes it the home of per-turn loop and budget control.
Allowed effects:
Abort— abort the invoke; this is where the iteration and budget hard-stops fire.AddMessages— add a message to the prompt for this query.DropMessages— remove messages from the prompt for this query.
Suppliers do not compose here: SupplyLLMResponse is a LLMQuerySend
effect — a supplier decides on the basis of the message list, and the list it must see is
the committed post-edit one, which at this event composition may still rewrite.
Attributes
messages(Sequence[dict[str, Any]]) — The message buffer as it stands before this query’s edits are folded in.iteration(int) — The agent-loop iteration this query belongs to.
LLMQueryEnter.__init__
Section titled “LLMQueryEnter.__init__”__init__(messages: Sequence[dict[str, Any]], iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneLLMQuerySend
Section titled “LLMQuerySend”Bases: Event
Fired when a query’s input has committed — the post-edit message list is final.
Fires after LLMQueryEnter’s edits have composed, once per query, on every
path where the input commits: before a live provider call, and equally when a
SupplyLLMResponse (e.g. TrajectoryReplay) answers here and skips the call — the
commitment of the input is real on both. It does not fire when the query is aborted at
LLMQueryEnter (the input never commits).
Allowed effects:
SupplyLLMResponse— supply a response, overriding the default producer (the provider call); the query still completes normally with it.Abort— abort the invoke, declining the committed input.
Attributes
messages(Sequence[dict[str, Any]]) — The committed message list — the post-edit buffer view, the same shape asLLMQueryEnter.messages(provenance stamps intact). This turn’s ownAddMessagesadditions carry no stamp yet — a persistent one is stamped after the query — so only the buffer’s messages have a stable id here. The provider receives its wire projection, so a hook that forwardsevent.messagesto a provider itself must project them withjaz._provenance.to_wire_messagesfirst. The dicts are the buffer’s own: rewriting one in place here changes the conversation for every later turn, exactly as atLLMQueryEnter.iteration(int) — The agent-loop iteration this query belongs to.message_edits(ResolvedMessageEdits) — The enter-time edits that producedmessages, as self-contained records (dropped message content + persistence; added messages + resolved position).
LLMQuerySend.__init__
Section titled “LLMQuerySend.__init__”__init__(messages: Sequence[dict[str, Any]], iteration: int, message_edits: ResolvedMessageEdits = ResolvedMessageEdits(), *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneLLMQueryComplete
Section titled “LLMQueryComplete”Bases: Event
Fired when the query’s raw response exists — the response control boundary.
Fires once per completed query, with the response the producer made: the provider’s
return, or the response a SupplyLLMResponse supplied at LLMQuerySend.
It does not fire when the query was aborted before a response existed, or when the
call raised (no raw response — only LLMQueryExit fires then, with the failure).
This is the earliest point a hook can decide “this run must not continue” on the basis of what came back — an unpriceable cost, a policy-violating completion, a provider degradation. The query itself is already finished and is never un-done: an abort here stops the turn after the response, before the agent acts on it, so the code the model just proposed is never executed.
Allowed effects:
ModifyLLMResponse— transform the response (content and/or token/cost fields) the agent then acts on. The transform is authoritative: the modified response is what the agent parses into its next turn and whatLLMQueryExitobservers + cost accounting see.Abort— abort the invoke on the basis of the response.
Attributes
response(LLMResponse) — The rawLLMResponsethe producer returned (pre-transform) — content, token counts, and cost. AModifyLLMResponsecomposed here transforms it; the post-transform response is whatLLMQueryExitcarries.iteration(int) — The agent-loop iteration this query belongs to.
LLMQueryComplete.__init__
Section titled “LLMQueryComplete.__init__”__init__(response: LLMResponse, iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneLLMQueryExit
Section titled “LLMQueryExit”Bases: Event
Fired when the LLM-query span closes, with the query’s outcome.
outcome is the tagged union LLMQueryOutcome: Completed carries the
LLMResponse the query produced (outcome.result) — including a response supplied
by SupplyLLMResponse (no call is made, but the query completes normally);
Aborted means a hook’s Abort at one of this query’s control stages
ended the invoke (outcome.exception carries the abort’s error, which propagates
after the event fires); Failed carries the exception the call (or the span’s
own machinery) raised (outcome.exception; it still propagates after the event
fires). The event fires on every path once the query span opened — an aborted
query closes Aborted, it no longer skips the exit.
Allowed effects — narrow: a hook may return Abort (and only Abort), on every
arm. On the Completed arm this stops the run on the basis of the final,
post-transform response — the thing LLMQueryComplete can’t see, since a
ModifyLLMResponse there composes after every Complete hook has run — firing before the agent
acts on the response. On the Aborted / Failed arms a terminating exception is
already unwinding, so an abort here cannot replace it: it is folded into it via an
ExceptionGroup (the in-flight exception stays present, so is_fatal still governs how far
the combined error travels). Any effect other than Abort raises
InvalidEffectError on the Completed arm and is dropped with an
error log on the abnormal arms (a loud raise there would replace the exception that must win).
To transform the response (rather than abort on it), use ModifyLLMResponse at
LLMQueryComplete.
Timing: like every event, this exit carries only timestamp
(its emission time); a span’s duration is Exit.timestamp - Enter.timestamp.
Attributes
outcome(LLMQueryOutcome) — How the span ended, with its payload — match on the variant (Completed[LLMResponse] | Aborted | Failed).iteration(int) — The agent-loop iteration this query belongs to.
LLMQueryExit.__init__
Section titled “LLMQueryExit.__init__”__init__(outcome: LLMQueryOutcome, iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneResolvedMessageEdits
Section titled “ResolvedMessageEdits”This query’s composed message edits as self-contained, pre-resolved records.
drops records DropMessages, adds records AddMessages — each
sequence named by the verb of the effect it records.
Ordering: drops by resolved position (one record per position, so that is a total
order); adds in application order — by resolved slot, and within one slot as the fold
applied them (persistent adds first, then transient, each in hook order).
ResolvedMessageEdits.__init__
Section titled “ResolvedMessageEdits.__init__”__init__(drops: Sequence[MessageDropRecord] = (), adds: Sequence[MessageAddRecord] = ()) -> NoneMessageDropRecord
Section titled “MessageDropRecord”One message dropped from this query’s committed input.
Attributes
message(dict[str, Any]) — The dropped message itself (with its provenance stamp, so its stable per-message id is readable viajaz._provenance.provenance_of).position(int) — The resolved slot the message occupied in the enter-time snapshot when it was dropped – the drop’s input coordinate, mirroringMessageAddRecord.position. A live buffer index, so it drifts across turns; the message’s id and iteration (via its provenance) are the stable identity.persistent(bool) — Whether the drop also removed the message from the carried-forward buffer (True) or applied to this query’s view only (False).
MessageDropRecord.__init__
Section titled “MessageDropRecord.__init__”__init__(message: dict[str, Any], position: int, persistent: bool) -> NoneMessageAddRecord
Section titled “MessageAddRecord”One AddMessages edit folded into this query’s committed input.
Attributes
messages(Sequence[dict[str, Any]]) — The inserted messages.position(int) — The resolved slot in the enter-time snapshot the messages were inserted before (len(snapshot)for an append).persistent(bool) — Whether the add also survives into later turns’ buffers.
MessageAddRecord.__init__
Section titled “MessageAddRecord.__init__”__init__(messages: Sequence[dict[str, Any]], position: int, persistent: bool) -> NoneInvokeEnter
Section titled “InvokeEnter”Bases: Event
Fired when Agent.invoke is called, before any execution begins.
Fires once per invoke, not per turn — one of these opens every invoke, including each nested sub-invoke, before the first LLM query.
Allowed effects:
Abort— abort the invoke before its first turn.AddInputs— add an input, visible in the prompt and bound in the REPL.DropInputs— remove an input from both the prompt and the REPL.DisableRecursion— withhold the recursiveinvoketool from this invoke.WithholdREPLHistory— withhold__history__from this invoke.
Attributes
parent_invoke_id(str | None) — The enclosing invoke’s id, orNoneat the top level.parent_repl_iteration(int | None) — The enclosing invoke’s iteration that spawned this one, orNoneat the top level.inputs(Mapping[str, object]) — The explicit**inputspassed tojaz.invoke, as a read-only mapping. Disjoint from the ambientscopeevery event carries.
InvokeEnter.__init__
Section titled “InvokeEnter.__init__”__init__(parent_invoke_id: str | None, parent_repl_iteration: int | None, inputs: Mapping[str, object], *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneInvokeSend
Section titled “InvokeSend”Bases: Event
Fired when an invoke’s input set has committed — post AddInputs / DropInputs.
Fires once per invoke, after InvokeEnter’s input effects have been folded into
the inputs the prompt renders and the REPL binds, before the first turn. It does not
fire when a hook aborts the invoke at InvokeEnter (the input never commits).
Allowed effects:
SupplyInvokeResult— supply the invoke’s terminal result and skip the whole agent loop (the invoke-boundary twin ofSupplyExecResultatREPLExecSend).Abort— abort the invoke, declining the committed input set.
Attributes
inputs(Mapping[str, object]) — The invoke’s committed explicit inputs (post add/drop), as a read-only mapping — the counterpart ofInvokeEnter’s pre-commitinputs.input_edits(ResolvedInputEdits) — The enter-time edits that producedinputsfromInvokeEnter.inputs, as self-contained records (seeResolvedInputEdits).recursion_disabled(bool) — Whether a hook emittedDisableRecursion— the invoke then binds no recursivesubinvoketool. The one enter-time edit that applies to no field of this event (subinvokeis not an input), so it rides the event itself rather thaninput_edits; its result shows one span later as the absence ofinvokefromnamespace["__builtins__"]inREPLExecEnter.namespace.repl_history_withheld(bool) — Whether a hook emittedWithholdREPLHistory— the invoke then binds no__history__and its prompt does not describe one. Recorded here for the same reason asrecursion_disabled.
InvokeSend.__init__
Section titled “InvokeSend.__init__”__init__(inputs: Mapping[str, object], input_edits: ResolvedInputEdits = ResolvedInputEdits(), recursion_disabled: bool = False, repl_history_withheld: bool = False, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneResolvedInputEdits
Section titled “ResolvedInputEdits”This invoke’s enter-time input edits as self-contained records.
adds records AddInputs, drops records DropInputs — each sequence
named by the verb of the effect it records, the rule every <thing>_edits field
follows. A record carries what the edit did, including what it removed: a drop record’s
value is read off InvokeEnter.inputs, the proposal the drop applied to.
Ordering: both sequences sorted by name — a record’s coordinate, the rule every
<thing>_edits sequence follows.
ResolvedInputEdits.__init__
Section titled “ResolvedInputEdits.__init__”__init__(adds: Sequence[InputAddRecord] = (), drops: Sequence[InputDropRecord] = ()) -> NoneInputAddRecord
Section titled “InputAddRecord”One name an AddInputs added to this invoke’s inputs.
Attributes
name(str) — The added input’s name.value(object) — The bound object, verbatim.
InputAddRecord.__init__
Section titled “InputAddRecord.__init__”__init__(name: str, value: object) -> NoneInputDropRecord
Section titled “InputDropRecord”One name a DropInputs un-passed from this invoke’s inputs.
Attributes
name(str) — The dropped name.value(object | UnsetType) — The object that was un-passed, orUNSETwhen nothing was — the name was absent (anallow_missingdrop).
InputDropRecord.__init__
Section titled “InputDropRecord.__init__”__init__(name: str, value: object | UnsetType) -> NoneInvokeComplete
Section titled “InvokeComplete”Bases: Event
Fired when the invoke’s raw terminal result exists — the transform boundary.
Fires once per invoke, with the terminal result the loop produced. It does not
fire when the invoke unwinds on an in-flight exception before a terminal result
exists (transformers never run during unwind), nor when a hook’s Abort
ended the invoke at an earlier stage (an abort skips the pipeline’s remaining
stages — its stickiness is structural).
Allowed effects:
ModifyInvokeResult— replace the invoke’s terminal result.Abort— abort the invoke with an error.
Attributes
result(TerminalExecResult) — The invoke’s raw terminal result — aReturnor aRaise— before any transform composes.
InvokeComplete.__init__
Section titled “InvokeComplete.__init__”__init__(result: TerminalExecResult, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneInvokeExit
Section titled “InvokeExit”Bases: Event
Fired when the invoke span closes, with the invoke’s final outcome.
Fires once per invoke, not per turn. outcome is the tagged union
InvokeOutcome: Completed carries the invoke’s final, post-transform
terminal result (outcome.result — any ModifyInvokeResult composed at
InvokeComplete already applied), exactly what the invoke returns or raises to
its caller. Aborted means this invoke’s own hook control plane ended it via
Abort — at whichever stage the effect composed (outcome.exception
carries the abort’s error, which the invoke raises to its caller). Failed
carries every other error that escaped before the invoke produced a result — a REPL
that fails to initialize, a FatalError propagating from below, a child invoke’s
abort passing through; the error still propagates after the event fires.
Observation-only: no effect other than BlackboardWrite is valid
here — the outcome is already final (any other effect returned here raises
InvalidEffectError on the Completed arm and is dropped with an
error log on the abnormal arms, where the in-flight exception wins). To change the terminal
result, transform it at InvokeComplete. (Unlike the per-turn *Exit events —
LLMQueryExit / REPLExecExit, which accept an Abort on every arm —
InvokeExit stays fully observation-only: an invoke aborting at its own
terminal Exit would make this event’s Completed payload diverge from the exception the
caller then receives, with no enclosing span to record the abort, and InvokeComplete
already gives full control over the final result.)
Timing: like every event, this exit carries only timestamp
(its emission time); the span’s duration is Exit.timestamp - Enter.timestamp.
Attributes
outcome(InvokeOutcome) — How the span ended, with its payload — match on the variant (Completed[Return | Raise] | Aborted | Failed).
InvokeExit.__init__
Section titled “InvokeExit.__init__”__init__(outcome: InvokeOutcome, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> NoneLLMQueryRetry
Section titled “LLMQueryRetry”Bases: Event
Fired when an LLM call fails and is about to be retried.
Not a per-turn event. It fires once per retry attempt, so a turn whose first attempt succeeds never fires it, and a turn that retries three times fires it three times.
This event is purely observational: no effect other than
BlackboardWrite is valid here.
Attributes
attempt_number(int) — Which attempt just failed, counting from 1.exception(Exception) — The error that caused the retry.wait_seconds(float) — How long the retry will wait before the next attempt.iteration(int) — The agent-loop iteration the call belongs to.
LLMQueryRetry.__init__
Section titled “LLMQueryRetry.__init__”__init__(attempt_number: int, exception: Exception, wait_seconds: float, iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None