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

Event emitted by the agentic harness at the natural boundaries of its tool-calling loop. Consumers receive events synchronously on the thread driving the conversation; UI consumers must marshal back to their own event thread.

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.