events.go RawHistoryFolder
1package core
2
3import (
4 "encoding/json"
5 "time"
6
7 "github.com/bnema/zut/packages/provider"
8)
9
10// AgentEvent is the superset of events emitted by an Agent run.
11// Consumers discriminate via a type switch. Each concrete type has a
12// Type() method for JSON serialization.
13type AgentEvent interface {
14 Type() string
15}
16
17type EvTurnStart struct {
18 Step int
19 TurnID string
20}
21
22func (EvTurnStart) Type() string { return "turn_start" }
23
24type EvUserMessage struct {
25 Message provider.Message
26}
27
28func (EvUserMessage) Type() string { return "user_message" }
29
30type EvAssistantStart struct{}
31
32func (EvAssistantStart) Type() string { return "assistant_start" }
33
34// RetryScope identifies the retry layer that issued an activity event.
35type RetryScope string
36
37const (
38 RetryScopeProvider RetryScope = "provider"
39 RetryScopeAgent RetryScope = "agent"
40)
41
42// RetryLifecycleEvent identifies a sanitized retry audit record.
43type RetryLifecycleEvent string
44
45const (
46 RetryLifecycleRequestFailed RetryLifecycleEvent = "request_failed"
47 RetryLifecycleRetryScheduled RetryLifecycleEvent = "retry_scheduled"
48)
49
50// RetryReason is an allowlisted failure category safe for session persistence.
51type RetryReason string
52
53const (
54 RetryReasonOverload RetryReason = "overload"
55 RetryReasonRateLimit RetryReason = "rate_limit"
56 RetryReasonQuota RetryReason = "quota"
57 RetryReasonServer RetryReason = "server"
58 RetryReasonNetwork RetryReason = "network"
59 RetryReasonTimeout RetryReason = "timeout"
60 RetryReasonAuth RetryReason = "auth"
61 RetryReasonContextWindow RetryReason = "context_window"
62 RetryReasonClient RetryReason = "client"
63 RetryReasonUnknown RetryReason = "unknown"
64)
65
66// RetryLifecycleRecord contains only bounded, privacy-safe retry metadata.
67// Raw provider errors and response bodies must never be added to this type.
68type RetryLifecycleRecord struct {
69 Event RetryLifecycleEvent `json:"event"`
70 Scope RetryScope `json:"scope"`
71 Attempt int `json:"attempt"`
72 MaxAttempts int `json:"max_attempts"`
73 Reason RetryReason `json:"reason"`
74 Terminal bool `json:"terminal,omitempty"`
75 DelayMS int64 `json:"delay_ms,omitempty"`
76}
77
78// EvRequestStarted reports an outbound provider request attempt.
79type EvRequestStarted struct {
80 Provider string
81 Model string
82 Scope RetryScope
83 Attempt int
84 MaxAttempts int
85}
86
87func (EvRequestStarted) Type() string { return "request_started" }
88
89// EvCacheDiagnostics reports sanitized provider cache-routing state. It never
90// includes prompt text, durable IDs, request bodies, or credentials.
91type EvCacheDiagnostics struct {
92 Eligible bool
93 Mode string
94 Transport string
95 Continuation string
96}
97
98func (EvCacheDiagnostics) Type() string { return "cache_diagnostics" }
99
100// EvRetryScheduled reports a retry delay before its upcoming attempt.
101type EvRetryScheduled struct {
102 Scope RetryScope
103 Attempt int
104 MaxAttempts int
105 Delay time.Duration
106}
107
108func (EvRetryScheduled) Type() string { return "retry_scheduled" }
109
110type EvTextDelta struct {
111 Delta string
112}
113
114func (EvTextDelta) Type() string { return "text_delta" }
115
116type EvToolCall struct {
117 ID string
118 Name string
119 Args json.RawMessage
120}
121
122func (EvToolCall) Type() string { return "tool_call" }
123
124// EvToolExecutionStarted fires after guards and confirmation allow a call,
125// immediately before the tool starts executing.
126type EvToolExecutionStarted struct {
127 ID string
128 Name string
129}
130
131func (EvToolExecutionStarted) Type() string { return "tool_execution_started" }
132
133// EvToolUseStart fires the moment the provider announces a new
134// tool_use block during streaming, before any arg JSON has
135// arrived. Gives UIs a hook to pre-render a live "tool is being
136// composed" panel so the user sees the model typing the call in
137// real time. Name is already final at this point; Args is empty.
138type EvToolUseStart struct {
139 ID string
140 Name string
141}
142
143func (EvToolUseStart) Type() string { return "tool_use_start" }
144
145// EvToolUseArgs fires for each delta fragment of the tool_use
146// block's argument JSON. Concatenating every delta for a given
147// ID produces the full JSON string; during streaming it's likely
148// truncated mid-value. UIs can extract partial string fields
149// (e.g. the `content` arg of `write`) with an escape-aware scan.
150type EvToolUseArgs struct {
151 ID string
152 Delta string
153}
154
155func (EvToolUseArgs) Type() string { return "tool_use_args" }
156
157// EvToolUseEnd fires when the provider marks the tool_use block
158// complete. At this point the full args JSON is known; a separate
159// EvToolCall follows once the assistant message is assembled,
160// carrying the parsed block that actually runs.
161type EvToolUseEnd struct {
162 ID string
163}
164
165func (EvToolUseEnd) Type() string { return "tool_use_end" }
166
167type EvToolProgress struct {
168 ID string
169 Text string
170}
171
172func (EvToolProgress) Type() string { return "tool_progress" }
173
174type EvToolResult struct {
175 ID string
176 Result ToolResult
177}
178
179func (EvToolResult) Type() string { return "tool_result" }
180
181type EvUsage struct {
182 Usage provider.Usage
183 Cumulative provider.Usage
184}
185
186func (EvUsage) Type() string { return "usage" }
187
188type EvAssistantMessage struct {
189 Message provider.Message
190}
191
192func (EvAssistantMessage) Type() string { return "assistant_message" }
193
194type EvTurnEnd struct {
195 Stop provider.StopReason
196 Err error
197}
198
199func (EvTurnEnd) Type() string { return "turn_end" }
200
201type EvDone struct{}
202
203func (EvDone) Type() string { return "done" }
204
205type EvError struct {
206 Err error
207}
208
209func (EvError) Type() string { return "error" }