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