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
174// PlanStepStatus is the state of one plan checklist step.
175type PlanStepStatus string
176
177const (
178 PlanPending PlanStepStatus = "pending"
179 PlanInProgress PlanStepStatus = "in_progress"
180 PlanCompleted PlanStepStatus = "completed"
181)
182
183// PlanStep is one model-maintained task in a plan update.
184type PlanStep struct {
185 Step string `json:"step"`
186 Status PlanStepStatus `json:"status"`
187}
188
189// PlanUpdate replaces the model's current task checklist for a turn.
190type PlanUpdate struct {
191 Explanation *string `json:"explanation"`
192 Plan []PlanStep `json:"plan"`
193}
194
195// EvPlanUpdate reports a successful plan call before its tool result.
196type EvPlanUpdate struct {
197 // CallID identifies the tool call that produced this update. It is
198 // optional for compatibility with hosts that predate persisted plans.
199 CallID string
200 Update PlanUpdate
201}
202
203func (EvPlanUpdate) Type() string { return "plan_update" }
204
205type EvToolResult struct {
206 ID string
207 Result ToolResult
208}
209
210func (EvToolResult) Type() string { return "tool_result" }
211
212type EvUsage struct {
213 Usage provider.Usage
214 Cumulative provider.Usage
215}
216
217func (EvUsage) Type() string { return "usage" }
218
219type EvAssistantMessage struct {
220 Message provider.Message
221}
222
223func (EvAssistantMessage) Type() string { return "assistant_message" }
224
225type EvTurnEnd struct {
226 Stop provider.StopReason
227 Err error
228}
229
230func (EvTurnEnd) Type() string { return "turn_end" }
231
232type EvTurnRecovery struct {
233 // Reason is missing_answer or commentary_only.
234 Reason string
235 // Attempt is always 1: one recovery allowance per top-level invocation.
236 Attempt int
237}
238
239func (EvTurnRecovery) Type() string { return "turn_recovery" }
240
241type EvDone struct{}
242
243func (EvDone) Type() string { return "done" }
244
245type EvError struct {
246 Err error
247}
248
249func (EvError) Type() string { return "error" }