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
100type PanelRenderFromExt struct {
101 Type string `json:"type"`
102 PanelID string `json:"panel_id"`
103 Title string `json:"title,omitempty"`
104 Lines []string `json:"lines,omitempty"`
105 Footer string `json:"footer,omitempty"`
106}
107
108type PanelCloseFromExt struct {
109 Type string `json:"type"`
110 PanelID string `json:"panel_id"`
111}
112
113type NotifyFromExt struct {
114 Type string `json:"type"`
115 Level string `json:"level"`
116 Message string `json:"message"`
117}
118
119// ClearNotesFromExt is a spontaneous frame an extension can send to
120// retract every note it previously pushed via notify/display, so
121// transient status lines (e.g. an approval prompt) do not stack up
122// forever in the bottom-sticky notes block.
123type ClearNotesFromExt struct {
124 Type string `json:"type"`
125}
126
127// SubmitSlashFromExt is a spontaneous frame an extension can send at
128// any time (typically from a panel_key handler) to invoke a slash
129// command in the host's TUI as if the user had typed it. Text must
130// start with '/'. Reserved for internal / opt-in extensions today;
131// the wire format is stable but not yet exposed in the public docs.
132type SubmitSlashFromExt struct {
133 Type string `json:"type"`
134 Text string `json:"text"`
135}
136
137type ShutdownAckFromExt struct {
138 Type string `json:"type"`
139}
140
141type HelloAckFromHost struct {
142 Type string `json:"type"`
143 ProtocolVersion int `json:"protocol_version"`
144 ZotVersion string `json:"zot_version"`
145 Provider string `json:"provider"`
146 Model string `json:"model"`
147 CWD string `json:"cwd"`
148 ExtensionDir string `json:"extension_dir,omitempty"`
149 DataDir string `json:"data_dir,omitempty"`
150}
151
152type CommandInvokedFromHost struct {
153 Type string `json:"type"`
154 ID string `json:"id"`
155 Name string `json:"name"`
156 Args string `json:"args,omitempty"`
157}
158
159type ToolCallFromHost struct {
160 Type string `json:"type"`
161 ID string `json:"id"`
162 Name string `json:"name"`
163 Args json.RawMessage `json:"args"`
164}
165
166type EventFromHost struct {
167 Type string `json:"type"`
168 Event string `json:"event"`
169 Step int `json:"step,omitempty"`
170 Stop string `json:"stop,omitempty"`
171 Error string `json:"error,omitempty"`
172 ToolID string `json:"tool_id,omitempty"`
173 ToolName string `json:"tool_name,omitempty"`
174 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
175 Text string `json:"text,omitempty"`
176}
177
178type EventInterceptFromHost struct {
179 Type string `json:"type"`
180 ID string `json:"id"`
181 Event string `json:"event"`
182 ToolID string `json:"tool_id,omitempty"`
183 ToolName string `json:"tool_name,omitempty"`
184 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
185 Step int `json:"step,omitempty"`
186 Text string `json:"text,omitempty"`
187}
188
189type PanelKeyFromHost struct {
190 Type string `json:"type"`
191 PanelID string `json:"panel_id"`
192 Key string `json:"key"`
193 Text string `json:"text,omitempty"`
194}
195
196type PanelResizeFromHost struct {
197 Type string `json:"type"`
198 PanelID string `json:"panel_id"`
199 Width int `json:"width"`
200 Height int `json:"height"`
201}
202
203type PanelCloseFromHost struct {
204 Type string `json:"type"`
205 PanelID string `json:"panel_id"`
206}
207
208type ShutdownFromHost struct {
209 Type string `json:"type"`
210}
211
212func Encode(v any) ([]byte, error) {
213 b, err := json.Marshal(v)
214 if err != nil {
215 return nil, err
216 }
217 return append(b, '\n'), nil
218}