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// EvRequestStarted reports an outbound provider request attempt.
42type EvRequestStarted struct {
43	Provider    string
44	Model       string
45	Scope       RetryScope
46	Attempt     int
47	MaxAttempts int
48}
49
50func (EvRequestStarted) Type() string { return "request_started" }
51
52// EvRetryScheduled reports a retry delay before its upcoming attempt.
53type EvRetryScheduled struct {
54	Scope       RetryScope
55	Attempt     int
56	MaxAttempts int
57	Delay       time.Duration
58}
59
60func (EvRetryScheduled) Type() string { return "retry_scheduled" }
61
62type EvTextDelta struct {
63	Delta string
64}
65
66func (EvTextDelta) Type() string { return "text_delta" }
67
68type EvToolCall struct {
69	ID   string
70	Name string
71	Args json.RawMessage
72}
73
74func (EvToolCall) Type() string { return "tool_call" }
75
76// EvToolExecutionStarted fires after guards and confirmation allow a call,
77// immediately before the tool starts executing.
78type EvToolExecutionStarted struct {
79	ID   string
80	Name string
81}
82
83func (EvToolExecutionStarted) Type() string { return "tool_execution_started" }
84
85// EvToolUseStart fires the moment the provider announces a new
86// tool_use block during streaming, before any arg JSON has
87// arrived. Gives UIs a hook to pre-render a live "tool is being
88// composed" panel so the user sees the model typing the call in
89// real time. Name is already final at this point; Args is empty.
90type EvToolUseStart struct {
91	ID   string
92	Name string
93}
94
95func (EvToolUseStart) Type() string { return "tool_use_start" }
96
97// EvToolUseArgs fires for each delta fragment of the tool_use
98// block's argument JSON. Concatenating every delta for a given
99// ID produces the full JSON string; during streaming it's likely
100// truncated mid-value. UIs can extract partial string fields
101// (e.g. the `content` arg of `write`) with an escape-aware scan.
102type EvToolUseArgs struct {
103	ID    string
104	Delta string
105}
106
107func (EvToolUseArgs) Type() string { return "tool_use_args" }
108
109// EvToolUseEnd fires when the provider marks the tool_use block
110// complete. At this point the full args JSON is known; a separate
111// EvToolCall follows once the assistant message is assembled,
112// carrying the parsed block that actually runs.
113type EvToolUseEnd struct {
114	ID string
115}
116
117func (EvToolUseEnd) Type() string { return "tool_use_end" }
118
119type EvToolProgress struct {
120	ID   string
121	Text string
122}
123
124func (EvToolProgress) Type() string { return "tool_progress" }
125
126type EvToolResult struct {
127	ID     string
128	Result ToolResult
129}
130
131func (EvToolResult) Type() string { return "tool_result" }
132
133type EvUsage struct {
134	Usage      provider.Usage
135	Cumulative provider.Usage
136}
137
138func (EvUsage) Type() string { return "usage" }
139
140type EvAssistantMessage struct {
141	Message provider.Message
142}
143
144func (EvAssistantMessage) Type() string { return "assistant_message" }
145
146type EvTurnEnd struct {
147	Stop provider.StopReason
148	Err  error
149}
150
151func (EvTurnEnd) Type() string { return "turn_end" }
152
153type EvDone struct{}
154
155func (EvDone) Type() string { return "done" }
156
157type EvError struct {
158	Err error
159}
160
161func (EvError) Type() string { return "error" }