Interface HarnessEvent
- All Known Implementing Classes:
HarnessEvent.ModelMessage, HarnessEvent.ModelThinking, HarnessEvent.ReplyRejected, HarnessEvent.ResponseTruncated, HarnessEvent.SubagentFinished, HarnessEvent.SubagentStarted, HarnessEvent.TokenSpend, HarnessEvent.ToolCallCompleted, HarnessEvent.ToolCallFailed, HarnessEvent.ToolCallRequested, HarnessEvent.TurnFinished, HarnessEvent.TurnStarted, HarnessEvent.WindowUsage
Sequence within a single conversation turn:
TurnStarted
-> (loop)
TokenSpend? // only when the chat response reported token usage
ModelThinking? // only when the model returned a reasoning trace
ModelMessage? // only when the model returned prose with its tool calls
ResponseTruncated? // only when the response hit the output-token cap
ToolCallRequested -> ToolCallCompleted | ToolCallFailed
// (if the tool is spawn_subagent, a nested
// SubagentStarted ... SubagentFinished envelope appears
// here, carrying its own TokenSpend events from the
// sub-harness's chat calls)
-> ReplyRejected? // only on a typed send whose reply failed to decode; the
// loop above then repeats for the repair attempt
-> TurnFinished
-> WindowUsage? // only when the final response reported its input size
Two events split responsibilities that look similar but are not. HarnessEvent.WindowUsage is a
point-in-time snapshot of how full the orchestrator's conversation is and is bounded by the
model's context window; consumers compare used to budget to decide whether the
conversation is near its cap. HarnessEvent.TokenSpend is a per-call delta intended for cumulative cost
reporting; consumers sum it across every event to get session spend.
When the orchestrator calls spawn_subagent, the sub-harness's events are forwarded to
the orchestrator's consumer wrapped in a HarnessEvent.SubagentStarted / HarnessEvent.SubagentFinished
envelope. Sub-harness HarnessEvent.TokenSpend events are forwarded so the orchestrator's spend total
correctly includes subagent activity — meaning a parent consumer sees one HarnessEvent.TokenSpend per
chat call across the entire orchestrator + subagent tree, not one per chat call in the
orchestrator's own loop. Sub-harness HarnessEvent.WindowUsage, HarnessEvent.TurnStarted, and HarnessEvent.TurnFinished events are dropped: the window snapshot describes the sub-harness's own window (not
the orchestrator's), and the turn envelope is already provided at the subagent granularity by
HarnessEvent.SubagentStarted / HarnessEvent.SubagentFinished, whose HarnessEvent.SubagentFinished.result()
carries the sub-harness's final text.
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic final recordEmitted when the model returns prose alongside the tool calls it is requesting.static final recordEmitted when the model's response includes a reasoning trace.static final recordEmitted when a typedAgenticHarness.send(String, Class)rejected a reply and asked again.static final recordEmitted when a chat response stopped because it hit the model's output-token limit (finish reasonLENGTH); its final text, or a tool call's arguments, may be cut off.static final recordEmitted when the sub-harness opened byHarnessEvent.SubagentStartedreturns, carrying its final response (or error message) so consumers can close out the subagent scope.static final recordEmitted byspawn_subagentimmediately before its sub-harness starts running, so downstream consumers can scope subsequent events to the subagent.static final recordEmitted after a chat response that reports token usage, carrying the input and output tokens billed for that one call.static final recordEmitted after a tool invocation completes successfully.static final recordEmitted when a tool invocation throws.static final recordEmitted when the model requests a tool invocation, before the tool runs.static final recordEmitted when the conversation turn opened byHarnessEvent.TurnStartedcompletes, carrying the model's final text reply.static final recordEmitted at the start of each conversation turn, immediately after the user's message has been accepted but before the first request is sent to the model.static final recordEmitted at most once after eachHarnessEvent.TurnFinished, reporting how full the orchestrator's conversation is as of the request that produced the final reply.