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
119type ShutdownAckFromExt struct {
120 Type string `json:"type"`
121}
122
123type HelloAckFromHost struct {
124 Type string `json:"type"`
125 ProtocolVersion int `json:"protocol_version"`
126 ZotVersion string `json:"zot_version"`
127 Provider string `json:"provider"`
128 Model string `json:"model"`
129 CWD string `json:"cwd"`
130 ExtensionDir string `json:"extension_dir,omitempty"`
131 DataDir string `json:"data_dir,omitempty"`
132}
133
134type CommandInvokedFromHost struct {
135 Type string `json:"type"`
136 ID string `json:"id"`
137 Name string `json:"name"`
138 Args string `json:"args,omitempty"`
139}
140
141type ToolCallFromHost struct {
142 Type string `json:"type"`
143 ID string `json:"id"`
144 Name string `json:"name"`
145 Args json.RawMessage `json:"args"`
146}
147
148type EventFromHost struct {
149 Type string `json:"type"`
150 Event string `json:"event"`
151 Step int `json:"step,omitempty"`
152 Stop string `json:"stop,omitempty"`
153 Error string `json:"error,omitempty"`
154 ToolID string `json:"tool_id,omitempty"`
155 ToolName string `json:"tool_name,omitempty"`
156 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
157 Text string `json:"text,omitempty"`
158}
159
160type EventInterceptFromHost struct {
161 Type string `json:"type"`
162 ID string `json:"id"`
163 Event string `json:"event"`
164 ToolID string `json:"tool_id,omitempty"`
165 ToolName string `json:"tool_name,omitempty"`
166 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
167 Step int `json:"step,omitempty"`
168 Text string `json:"text,omitempty"`
169}
170
171type PanelKeyFromHost struct {
172 Type string `json:"type"`
173 PanelID string `json:"panel_id"`
174 Key string `json:"key"`
175 Text string `json:"text,omitempty"`
176}
177
178type PanelResizeFromHost struct {
179 Type string `json:"type"`
180 PanelID string `json:"panel_id"`
181 Width int `json:"width"`
182 Height int `json:"height"`
183}
184
185type PanelCloseFromHost struct {
186 Type string `json:"type"`
187 PanelID string `json:"panel_id"`
188}
189
190type ShutdownFromHost struct {
191 Type string `json:"type"`
192}
193
194func Encode(v any) ([]byte, error) {
195 b, err := json.Marshal(v)
196 if err != nil {
197 return nil, err
198 }
199 return append(b, '\n'), nil
200}