1// Package extproto defines the JSON-over-stdin/stdout wire format
2// spoken between zot and its extension subprocesses. Both the host
3// (packages/agent/extensions) and the SDK (packages/agent/ext) marshal/
4// unmarshal the same types, so changes here ripple through both.
5//
6// All frames are one JSON object terminated by a single LF. Object
7// boundaries follow newline boundaries; no multi-line JSON.
8//
9// Direction conventions in this file:
10// - Type names ending in "FromExt" are sent by the extension to zot.
11// - Type names ending in "FromHost" are sent by zot to the extension.
12// - Names without a suffix are direction-neutral payloads or shared
13// value types.
14//
15// Every frame has a top-level Type discriminator. Optional ID is
16// present on commands and on responses to commands so the sender can
17// correlate; events and notifications never carry an ID.
18package extproto
19
20import "encoding/json"
21
22const ProtocolVersion = 1
23
24type Frame struct {
25 Type string `json:"type"`
26 ID string `json:"id,omitempty"`
27}
28
29type HelloFromExt struct {
30 Type string `json:"type"`
31 Name string `json:"name"`
32 Version string `json:"version"`
33 Capabilities []string `json:"capabilities,omitempty"`
34}
35
36type RegisterCommandFromExt struct {
37 Type string `json:"type"`
38 Name string `json:"name"`
39 Description string `json:"description,omitempty"`
40}
41
42type RegisterToolFromExt struct {
43 Type string `json:"type"`
44 Name string `json:"name"`
45 Description string `json:"description,omitempty"`
46 Schema json.RawMessage `json:"schema"`
47}
48
49type ReadyFromExt struct {
50 Type string `json:"type"`
51}
52
53type SubscribeFromExt struct {
54 Type string `json:"type"`
55 Events []string `json:"events,omitempty"`
56 Intercept []string `json:"intercept,omitempty"`
57}
58
59type EventInterceptResponseFromExt struct {
60 Type string `json:"type"`
61 ID string `json:"id"`
62 Block bool `json:"block,omitempty"`
63 Reason string `json:"reason,omitempty"`
64 ModifiedArgs json.RawMessage `json:"modified_args,omitempty"`
65 ReplaceText string `json:"replace_text,omitempty"`
66}
67
68type ToolResultFromExt struct {
69 Type string `json:"type"`
70 ID string `json:"id"`
71 Content []ContentBlock `json:"content"`
72 IsError bool `json:"is_error,omitempty"`
73}
74
75type ContentBlock struct {
76 Type string `json:"type"`
77 Text string `json:"text,omitempty"`
78 MimeType string `json:"mime_type,omitempty"`
79 Data string `json:"data,omitempty"`
80}
81
82type CommandResponseFromExt struct {
83 Type string `json:"type"`
84 ID string `json:"id"`
85 Action string `json:"action"`
86 Prompt string `json:"prompt,omitempty"`
87 Insert string `json:"insert,omitempty"`
88 Display string `json:"display,omitempty"`
89 OpenPanel *PanelSpec `json:"open_panel,omitempty"`
90 Error string `json:"error,omitempty"`
91}
92
93type PanelSpec struct {
94 ID string `json:"id"`
95 Title string `json:"title,omitempty"`
96 Lines []string `json:"lines,omitempty"`
97 Footer string `json:"footer,omitempty"`
98}
99
100// OpenPanelFromExt is a spontaneous one-way frame an extension can send at
101// any time to open an interactive panel. Unlike the open_panel action inside
102// CommandResponseFromExt, this form is uncoupled from any command invocation
103// and may be sent from a tool handler goroutine or any background context.
104type OpenPanelFromExt struct {
105 Type string `json:"type"` // "open_panel"
106 Panel PanelSpec `json:"panel"`
107}
108
109type PanelRenderFromExt struct {
110 Type string `json:"type"`
111 PanelID string `json:"panel_id"`
112 Title string `json:"title,omitempty"`
113 Lines []string `json:"lines,omitempty"`
114 Footer string `json:"footer,omitempty"`
115}
116
117type PanelCloseFromExt struct {
118 Type string `json:"type"`
119 PanelID string `json:"panel_id"`
120}
121
122type NotifyFromExt struct {
123 Type string `json:"type"`
124 Level string `json:"level"`
125 Message string `json:"message"`
126}
127
128// ClearNotesFromExt is a spontaneous frame an extension can send to
129// retract every note it previously pushed via notify/display, so
130// transient status lines (e.g. an approval prompt) do not stack up
131// forever in the bottom-sticky notes block.
132type ClearNotesFromExt struct {
133 Type string `json:"type"`
134}
135
136// SubmitSlashFromExt is a spontaneous frame an extension can send at
137// any time (typically from a panel_key handler) to invoke a slash
138// command in the host's TUI as if the user had typed it. Text must
139// start with '/'. Reserved for internal / opt-in extensions today;
140// the wire format is stable but not yet exposed in the public docs.
141type SubmitSlashFromExt struct {
142 Type string `json:"type"`
143 Text string `json:"text"`
144}
145
146type ShutdownAckFromExt struct {
147 Type string `json:"type"`
148}
149
150type HelloAckFromHost struct {
151 Type string `json:"type"`
152 ProtocolVersion int `json:"protocol_version"`
153 ZotVersion string `json:"zot_version"`
154 Provider string `json:"provider"`
155 Model string `json:"model"`
156 CWD string `json:"cwd"`
157 ExtensionDir string `json:"extension_dir,omitempty"`
158 DataDir string `json:"data_dir,omitempty"`
159}
160
161type CommandInvokedFromHost struct {
162 Type string `json:"type"`
163 ID string `json:"id"`
164 Name string `json:"name"`
165 Args string `json:"args,omitempty"`
166}
167
168type ToolCallFromHost struct {
169 Type string `json:"type"`
170 ID string `json:"id"`
171 Name string `json:"name"`
172 Args json.RawMessage `json:"args"`
173}
174
175type EventFromHost struct {
176 Type string `json:"type"`
177 Event string `json:"event"`
178 Step int `json:"step,omitempty"`
179 Stop string `json:"stop,omitempty"`
180 Error string `json:"error,omitempty"`
181 ToolID string `json:"tool_id,omitempty"`
182 ToolName string `json:"tool_name,omitempty"`
183 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
184 Text string `json:"text,omitempty"`
185}
186
187type EventInterceptFromHost struct {
188 Type string `json:"type"`
189 ID string `json:"id"`
190 Event string `json:"event"`
191 ToolID string `json:"tool_id,omitempty"`
192 ToolName string `json:"tool_name,omitempty"`
193 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
194 Step int `json:"step,omitempty"`
195 Text string `json:"text,omitempty"`
196}
197
198type PanelKeyFromHost struct {
199 Type string `json:"type"`
200 PanelID string `json:"panel_id"`
201 Key string `json:"key"`
202 Text string `json:"text,omitempty"`
203}
204
205type PanelResizeFromHost struct {
206 Type string `json:"type"`
207 PanelID string `json:"panel_id"`
208 Width int `json:"width"`
209 Height int `json:"height"`
210}
211
212type PanelCloseFromHost struct {
213 Type string `json:"type"`
214 PanelID string `json:"panel_id"`
215}
216
217type ShutdownFromHost struct {
218 Type string `json:"type"`
219}
220
221func Encode(v any) ([]byte, error) {
222 b, err := json.Marshal(v)
223 if err != nil {
224 return nil, err
225 }
226 return append(b, '\n'), nil
227}