loop: emit per-turn Usage event for a live cost/usage HUD (M4)

Dispatch a durable EventUsage after each turn with the turn's token usage
and the running session total, so an embedder can render a cost/usage
HUD. Add the hooks.UsagePayload + public topos.EventUsage constant.

Author: changkun

harness/hooks/events.go

@@ -132,6 +132,21 @@ type AssistantMessagePayload struct {
 	Turn      int    `json:"turn"`
 }
 
+// EventUsage carries the running token usage after a turn completes, so an
+// embedder can render a live cost/usage HUD. Durable (one per turn).
+const EventUsage EventName = "Usage"
+
+// UsagePayload is the versioned payload for EventUsage: the just-completed
+// turn's usage and the session's running total.
+type UsagePayload struct {
+	Version   string       `json:"version"`
+	SessionID string       `json:"session_id"`
+	AgentID   string       `json:"agent_id"`
+	Turn      int          `json:"turn"`
+	TurnUsage models.Usage `json:"turn_usage"`
+	Total     models.Usage `json:"total"`
+}
+
 // TextDeltaPayload is the versioned payload for EventTextDelta: one streamed
 // fragment of assistant text within a turn. SessionID and AgentID let a consumer
 // route the fragment to the right transcript and lineage node; Turn is the

runtime/loop/loop.go

@@ -305,8 +305,19 @@ func Run(ctx context.Context, cfg Config) (*Result, error) {
 		}
 		_ = stream.Close()
 
-		// Accumulate usage.
+		// Accumulate usage and emit it so embedders can render a live cost/usage
+		// HUD (durable: one per turn, present on reattach).
 		result.TotalUsage.Add(turnUsage)
+		if turnUsage != (models.Usage{}) {
+			cfg.Bus.Dispatch(hooks.EventUsage, &hooks.UsagePayload{
+				Version:   "1",
+				SessionID: cfg.SessionID,
+				AgentID:   cfg.AgentID,
+				Turn:      iter + 1,
+				TurnUsage: turnUsage,
+				Total:     result.TotalUsage,
+			})
+		}
 
 		finalStopReason = stopReason
 

runtime/loop/loop_test.go

@@ -762,6 +762,50 @@ func TestLoopEmitsTokenDeltasEphemerally(t *testing.T) {
 	}
 }
 
+// TestLoopEmitsUsageEvent asserts the loop dispatches a durable Usage event per
+// turn carrying the turn and running-total token usage.
+func TestLoopEmitsUsageEvent(t *testing.T) {
+	p := local.New()
+	ctx := context.Background()
+	sb, _ := p.Create(ctx, sandbox.CreateOptions{})
+	defer p.Destroy(ctx, sb.ID) //nolint:errcheck
+
+	bus := hooks.New()
+	var totals []models.Usage
+	bus.Register("usage-sink", []hooks.EventName{hooks.EventUsage}, func(_ hooks.EventName, payload any) hooks.Decision {
+		if p, ok := payload.(*hooks.UsagePayload); ok {
+			totals = append(totals, p.Total)
+		}
+		return hooks.Allow()
+	})
+
+	cfg := loop.Config{
+		Model: &fakeModel{prompt: "hi"}, Sandbox: p, SandboxID: sb.ID,
+		Tools: tools.Builtins(), Bus: bus, SessionID: "usage-test", UserPrompt: "hi",
+	}
+	if _, err := loop.Run(ctx, cfg); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if len(totals) == 0 {
+		t.Fatal("no Usage events emitted")
+	}
+	// The running total must be non-decreasing and end positive.
+	last := totals[len(totals)-1]
+	if last.InputTokens == 0 && last.OutputTokens == 0 {
+		t.Fatalf("final usage total is zero: %+v", last)
+	}
+	// Usage events are durable (recorded in the bus log).
+	durable := false
+	for _, e := range bus.EventLog() {
+		if e.EventName == hooks.EventUsage {
+			durable = true
+		}
+	}
+	if !durable {
+		t.Fatal("Usage event should be durable (in the event log)")
+	}
+}
+
 // hasErrorResultContaining reports whether the transcript holds a tool-role
 // message with an error result whose content contains sub.
 func hasErrorResultContaining(transcript []models.Message, sub string) bool {

topos.go

@@ -165,7 +165,9 @@ const (
 	// EventTextDelta carries one streamed fragment of assistant text (a token or
 	// few). An observer receives many of these per turn for token-by-token
 	// rendering, followed by the assembled EventAssistantMessage for the turn.
-	EventTextDelta     = "TextDelta"
+	EventTextDelta = "TextDelta"
+	// EventUsage carries running token usage after each turn (for a cost/usage HUD).
+	EventUsage         = "Usage"
 	EventPostToolUse   = "PostToolUse"
 	EventSubagentStart = "SubagentStart"
 	EventSubagentStop  = "SubagentStop"