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 update_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 update_plan call before its tool result.
196type EvPlanUpdate struct {
197 Update PlanUpdate
198}
199
200func (EvPlanUpdate) Type() string { return "plan_update" }
201
202type EvToolResult struct {
203 ID string
204 Result ToolResult
205}
206
207func (EvToolResult) Type() string { return "tool_result" }
208
209type EvUsage struct {
210 Usage provider.Usage
211 Cumulative provider.Usage
212}
213
214func (EvUsage) Type() string { return "usage" }
215
216type EvAssistantMessage struct {
217 Message provider.Message
218}
219
220func (EvAssistantMessage) Type() string { return "assistant_message" }
221
222type EvTurnEnd struct {
223 Stop provider.StopReason
224 Err error
225}
226
227func (EvTurnEnd) Type() string { return "turn_end" }
228
229type EvTurnRecovery struct {
230 // Reason is missing_answer or commentary_only.
231 Reason string
232 // Attempt is always 1: one recovery allowance per top-level invocation.
233 Attempt int
234}
235
236func (EvTurnRecovery) Type() string { return "turn_recovery" }
237
238type EvDone struct{}
239
240func (EvDone) Type() string { return "done" }
241
242type EvError struct {
243 Err error
244}
245
246func (EvError) Type() string { return "error" }