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
146// SubmitFromExt is a spontaneous frame an extension can send to queue
147// a model prompt in the interactive host. The manager routes it through
148// HostHooks.Submit, so the TUI handles busy state and turn startup.
149type SubmitFromExt struct {
150 Type string `json:"type"`
151 Text string `json:"text"`
152}
153
154type ShutdownAckFromExt struct {
155 Type string `json:"type"`
156}
157
158type HelloAckFromHost struct {
159 Type string `json:"type"`
160 ProtocolVersion int `json:"protocol_version"`
161 ZotVersion string `json:"zot_version"`
162 Provider string `json:"provider"`
163 Model string `json:"model"`
164 CWD string `json:"cwd"`
165 ExtensionDir string `json:"extension_dir,omitempty"`
166 DataDir string `json:"data_dir,omitempty"`
167}
168
169type CommandInvokedFromHost struct {
170 Type string `json:"type"`
171 ID string `json:"id"`
172 Name string `json:"name"`
173 Args string `json:"args,omitempty"`
174}
175
176type ToolCallFromHost struct {
177 Type string `json:"type"`
178 ID string `json:"id"`
179 Name string `json:"name"`
180 Args json.RawMessage `json:"args"`
181}
182
183type EventFromHost struct {
184 Type string `json:"type"`
185 Event string `json:"event"`
186 Step int `json:"step,omitempty"`
187 Stop string `json:"stop,omitempty"`
188 Error string `json:"error,omitempty"`
189 ToolID string `json:"tool_id,omitempty"`
190 ToolName string `json:"tool_name,omitempty"`
191 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
192 Text string `json:"text,omitempty"`
193}
194
195type EventInterceptFromHost struct {
196 Type string `json:"type"`
197 ID string `json:"id"`
198 Event string `json:"event"`
199 ToolID string `json:"tool_id,omitempty"`
200 ToolName string `json:"tool_name,omitempty"`
201 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
202 Step int `json:"step,omitempty"`
203 Text string `json:"text,omitempty"`
204}
205
206type PanelKeyFromHost struct {
207 Type string `json:"type"`
208 PanelID string `json:"panel_id"`
209 Key string `json:"key"`
210 Text string `json:"text,omitempty"`
211}
212
213type PanelResizeFromHost struct {
214 Type string `json:"type"`
215 PanelID string `json:"panel_id"`
216 Width int `json:"width"`
217 Height int `json:"height"`
218}
219
220type PanelCloseFromHost struct {
221 Type string `json:"type"`
222 PanelID string `json:"panel_id"`
223}
224
225type ShutdownFromHost struct {
226 Type string `json:"type"`
227}
228
229func Encode(v any) ([]byte, error) {
230 b, err := json.Marshal(v)
231 if err != nil {
232 return nil, err
233 }
234 return append(b, '\n'), nil
235}