1// Package extproto defines the JSON-over-stdin/stdout wire format
2// spoken between zot and its extension subprocesses. Both the host
3// (internal/agent/extensions) and the SDK (pkg/zotext) 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// SubmitSlashFromExt is a spontaneous frame an extension can send at
120// any time (typically from a panel_key handler) to invoke a slash
121// command in the host's TUI as if the user had typed it. Text must
122// start with '/'. Reserved for internal / opt-in extensions today;
123// the wire format is stable but not yet exposed in the public docs.
124type SubmitSlashFromExt struct {
125 Type string `json:"type"`
126 Text string `json:"text"`
127}
128
129type ShutdownAckFromExt struct {
130 Type string `json:"type"`
131}
132
133type HelloAckFromHost struct {
134 Type string `json:"type"`
135 ProtocolVersion int `json:"protocol_version"`
136 ZotVersion string `json:"zot_version"`
137 Provider string `json:"provider"`
138 Model string `json:"model"`
139 CWD string `json:"cwd"`
140 ExtensionDir string `json:"extension_dir,omitempty"`
141 DataDir string `json:"data_dir,omitempty"`
142}
143
144type CommandInvokedFromHost struct {
145 Type string `json:"type"`
146 ID string `json:"id"`
147 Name string `json:"name"`
148 Args string `json:"args,omitempty"`
149}
150
151type ToolCallFromHost struct {
152 Type string `json:"type"`
153 ID string `json:"id"`
154 Name string `json:"name"`
155 Args json.RawMessage `json:"args"`
156}
157
158type EventFromHost struct {
159 Type string `json:"type"`
160 Event string `json:"event"`
161 Step int `json:"step,omitempty"`
162 Stop string `json:"stop,omitempty"`
163 Error string `json:"error,omitempty"`
164 ToolID string `json:"tool_id,omitempty"`
165 ToolName string `json:"tool_name,omitempty"`
166 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
167 Text string `json:"text,omitempty"`
168}
169
170type EventInterceptFromHost struct {
171 Type string `json:"type"`
172 ID string `json:"id"`
173 Event string `json:"event"`
174 ToolID string `json:"tool_id,omitempty"`
175 ToolName string `json:"tool_name,omitempty"`
176 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
177 Step int `json:"step,omitempty"`
178 Text string `json:"text,omitempty"`
179}
180
181type PanelKeyFromHost struct {
182 Type string `json:"type"`
183 PanelID string `json:"panel_id"`
184 Key string `json:"key"`
185 Text string `json:"text,omitempty"`
186}
187
188type PanelResizeFromHost struct {
189 Type string `json:"type"`
190 PanelID string `json:"panel_id"`
191 Width int `json:"width"`
192 Height int `json:"height"`
193}
194
195type PanelCloseFromHost struct {
196 Type string `json:"type"`
197 PanelID string `json:"panel_id"`
198}
199
200type ShutdownFromHost struct {
201 Type string `json:"type"`
202}
203
204func Encode(v any) ([]byte, error) {
205 b, err := json.Marshal(v)
206 if err != nil {
207 return nil, err
208 }
209 return append(b, '\n'), nil
210}