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// EvRetryScheduled reports a retry delay before its upcoming attempt.
90type EvRetryScheduled struct {
91	Scope       RetryScope
92	Attempt     int
93	MaxAttempts int
94	Delay       time.Duration
95}
96
97func (EvRetryScheduled) Type() string { return "retry_scheduled" }
98
99type EvTextDelta struct {
100	Delta string
101}
102
103func (EvTextDelta) Type() string { return "text_delta" }
104
105type EvToolCall struct {
106	ID   string
107	Name string
108	Args json.RawMessage
109}
110
111func (EvToolCall) Type() string { return "tool_call" }
112
113// EvToolExecutionStarted fires after guards and confirmation allow a call,
114// immediately before the tool starts executing.
115type EvToolExecutionStarted struct {
116	ID   string
117	Name string
118}
119
120func (EvToolExecutionStarted) Type() string { return "tool_execution_started" }
121
122// EvToolUseStart fires the moment the provider announces a new
123// tool_use block during streaming, before any arg JSON has
124// arrived. Gives UIs a hook to pre-render a live "tool is being
125// composed" panel so the user sees the model typing the call in
126// real time. Name is already final at this point; Args is empty.
127type EvToolUseStart struct {
128	ID   string
129	Name string
130}
131
132func (EvToolUseStart) Type() string { return "tool_use_start" }
133
134// EvToolUseArgs fires for each delta fragment of the tool_use
135// block's argument JSON. Concatenating every delta for a given
136// ID produces the full JSON string; during streaming it's likely
137// truncated mid-value. UIs can extract partial string fields
138// (e.g. the `content` arg of `write`) with an escape-aware scan.
139type EvToolUseArgs struct {
140	ID    string
141	Delta string
142}
143
144func (EvToolUseArgs) Type() string { return "tool_use_args" }
145
146// EvToolUseEnd fires when the provider marks the tool_use block
147// complete. At this point the full args JSON is known; a separate
148// EvToolCall follows once the assistant message is assembled,
149// carrying the parsed block that actually runs.
150type EvToolUseEnd struct {
151	ID string
152}
153
154func (EvToolUseEnd) Type() string { return "tool_use_end" }
155
156type EvToolProgress struct {
157	ID   string
158	Text string
159}
160
161func (EvToolProgress) Type() string { return "tool_progress" }
162
163type EvToolResult struct {
164	ID     string
165	Result ToolResult
166}
167
168func (EvToolResult) Type() string { return "tool_result" }
169
170type EvUsage struct {
171	Usage      provider.Usage
172	Cumulative provider.Usage
173}
174
175func (EvUsage) Type() string { return "usage" }
176
177type EvAssistantMessage struct {
178	Message provider.Message
179}
180
181func (EvAssistantMessage) Type() string { return "assistant_message" }
182
183type EvTurnEnd struct {
184	Stop provider.StopReason
185	Err  error
186}
187
188func (EvTurnEnd) Type() string { return "turn_end" }
189
190type EvDone struct{}
191
192func (EvDone) Type() string { return "done" }
193
194type EvError struct {
195	Err error
196}
197
198func (EvError) Type() string { return "error" }