1// Package extproto defines the JSON-over-stdin/stdout wire format
2// spoken between zut 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 zut.
11// - Type names ending in "FromHost" are sent by zut 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
22// ProtocolVersion is the extension protocol major. Version 2 introduces the
23// zut_version wire key and requires both sides to reject mismatched majors.
24const ProtocolVersion = 2
25
26type Frame struct {
27 Type string `json:"type"`
28 ID string `json:"id,omitempty"`
29}
30
31type HelloFromExt struct {
32 Type string `json:"type"`
33 ProtocolVersion int `json:"protocol_version"`
34 Name string `json:"name"`
35 Version string `json:"version"`
36 Capabilities []string `json:"capabilities,omitempty"`
37}
38
39type RegisterCommandFromExt struct {
40 Type string `json:"type"`
41 Name string `json:"name"`
42 Description string `json:"description,omitempty"`
43}
44
45type RegisterToolFromExt struct {
46 Type string `json:"type"`
47 Name string `json:"name"`
48 Description string `json:"description,omitempty"`
49 Schema json.RawMessage `json:"schema"`
50 Deferred bool `json:"deferred,omitempty"`
51}
52
53type ReadyFromExt struct {
54 Type string `json:"type"`
55}
56
57type SubscribeFromExt struct {
58 Type string `json:"type"`
59 Events []string `json:"events,omitempty"`
60 Intercept []string `json:"intercept,omitempty"`
61}
62
63type EventInterceptResponseFromExt struct {
64 Type string `json:"type"`
65 ID string `json:"id"`
66 Block bool `json:"block,omitempty"`
67 Reason string `json:"reason,omitempty"`
68 ModifiedArgs json.RawMessage `json:"modified_args,omitempty"`
69 ReplaceText string `json:"replace_text,omitempty"`
70 // Context is hidden, bounded context for the upcoming model turn. It is
71 // not appended to the transcript or shown as a user message.
72 Context string `json:"context,omitempty"`
73}
74
75type ToolResultFromExt struct {
76 Type string `json:"type"`
77 ID string `json:"id"`
78 Content []ContentBlock `json:"content"`
79 IsError bool `json:"is_error,omitempty"`
80 ActivateTools []string `json:"activate_tools,omitempty"`
81 // Details is extension-owned metadata. The host never includes it in
82 // provider requests, but may persist it with the active session.
83 Details json.RawMessage `json:"details,omitempty"`
84}
85
86type ContentBlock struct {
87 Type string `json:"type"`
88 Text string `json:"text,omitempty"`
89 MimeType string `json:"mime_type,omitempty"`
90 Data string `json:"data,omitempty"`
91}
92
93type CommandResponseFromExt struct {
94 Type string `json:"type"`
95 ID string `json:"id"`
96 Action string `json:"action"`
97 Prompt string `json:"prompt,omitempty"`
98 Insert string `json:"insert,omitempty"`
99 Display string `json:"display,omitempty"`
100 OpenPanel *PanelSpec `json:"open_panel,omitempty"`
101 Error string `json:"error,omitempty"`
102}
103
104type PanelSpec struct {
105 ID string `json:"id"`
106 Title string `json:"title,omitempty"`
107 Lines []string `json:"lines,omitempty"`
108 Footer string `json:"footer,omitempty"`
109}
110
111// OpenPanelFromExt is a spontaneous one-way frame an extension can send at
112// any time to open an interactive panel. Unlike the open_panel action inside
113// CommandResponseFromExt, this form is uncoupled from any command invocation
114// and may be sent from a tool handler goroutine or any background context.
115type OpenPanelFromExt struct {
116 Type string `json:"type"` // "open_panel"
117 Panel PanelSpec `json:"panel"`
118}
119
120type PanelRenderFromExt struct {
121 Type string `json:"type"`
122 PanelID string `json:"panel_id"`
123 Title string `json:"title,omitempty"`
124 Lines []string `json:"lines,omitempty"`
125 Footer string `json:"footer,omitempty"`
126}
127
128type PanelCloseFromExt struct {
129 Type string `json:"type"`
130 PanelID string `json:"panel_id"`
131}
132
133// StatusFromExt sets or replaces one persistent status item owned by an
134// extension. An empty text clears the item.
135type StatusFromExt struct {
136 Type string `json:"type"`
137 Key string `json:"key"`
138 Level string `json:"level,omitempty"`
139 Text string `json:"text,omitempty"`
140}
141
142const (
143 WidgetPositionAboveInput = "above_input"
144 // WidgetPositionRightBar is retained for source compatibility. The right
145 // sidebar no longer exists, so this placement resolves above the input.
146 WidgetPositionRightBar = WidgetPositionAboveInput
147)
148
149// NormalizeWidgetPosition keeps extension widgets in the single supported
150// above-input placement. Unknown and removed placement hints remain compatible.
151func NormalizeWidgetPosition(string) string { return WidgetPositionAboveInput }
152
153// WidgetFromExt sets or replaces one persistent widget owned by an
154// extension. Position is a host-defined placement hint. Interactive hosts
155// render widgets above the input; empty and unknown values use that placement.
156type WidgetFromExt struct {
157 Type string `json:"type"`
158 ID string `json:"id"`
159 Position string `json:"position,omitempty"`
160 Title string `json:"title,omitempty"`
161 Lines []string `json:"lines,omitempty"`
162}
163
164type ClearWidgetFromExt struct {
165 Type string `json:"type"`
166 ID string `json:"id"`
167}
168
169const AlertKindBell = "bell"
170
171// AlertRequest is a host-owned alert request. Extensions provide semantic
172// metadata; the host decides whether and how to render it.
173type AlertRequest struct {
174 Kind string `json:"kind"`
175 Reason string `json:"reason,omitempty"`
176}
177
178// AlertFromExt is a spontaneous one-way frame an extension can send at any
179// time to request a host alert.
180type AlertFromExt struct {
181 Type string `json:"type"`
182 AlertRequest
183}
184
185type NotifyFromExt struct {
186 Type string `json:"type"`
187 Level string `json:"level"`
188 Message string `json:"message"`
189}
190
191// ClearNotesFromExt is a spontaneous frame an extension can send to
192// retract every note it previously pushed via notify/display, so
193// transient status lines (e.g. an approval prompt) do not stack up
194// forever in the bottom-sticky notes block.
195type ClearNotesFromExt struct {
196 Type string `json:"type"`
197}
198
199// SubmitSlashFromExt is a spontaneous frame an extension can send at
200// any time (typically from a panel_key handler) to invoke a slash
201// command in the host's TUI as if the user had typed it. Text must
202// start with '/'. Reserved for internal / opt-in extensions today;
203// the wire format is stable but not yet exposed in the public docs.
204type SubmitSlashFromExt struct {
205 Type string `json:"type"`
206 Text string `json:"text"`
207}
208
209// SubmitFromExt is a spontaneous frame an extension can send to queue
210// a model prompt in the interactive host. The manager routes it through
211// HostHooks.Submit, so the TUI handles busy state and turn startup.
212type SubmitFromExt struct {
213 Type string `json:"type"`
214 Text string `json:"text"`
215}
216
217type ShutdownAckFromExt struct {
218 Type string `json:"type"`
219}
220
221type HelloAckFromHost struct {
222 Type string `json:"type"`
223 ProtocolVersion int `json:"protocol_version"`
224 ZutVersion string `json:"zut_version"`
225 Provider string `json:"provider"`
226 Model string `json:"model"`
227 CWD string `json:"cwd"`
228 ExtensionDir string `json:"extension_dir,omitempty"`
229 DataDir string `json:"data_dir,omitempty"`
230 Session *SessionContext `json:"session,omitempty"`
231}
232
233// SessionContext identifies the active transcript branch. ID is the current
234// session/branch id; ParentID is empty for a root session.
235type SessionContext struct {
236 ID string `json:"id"`
237 ParentID string `json:"parent_id,omitempty"`
238 Path string `json:"path,omitempty"`
239 CWD string `json:"cwd,omitempty"`
240 ForkPoint int `json:"fork_point,omitempty"`
241}
242
243type CommandInvokedFromHost struct {
244 Type string `json:"type"`
245 ID string `json:"id"`
246 Name string `json:"name"`
247 Args string `json:"args,omitempty"`
248}
249
250type ToolCallFromHost struct {
251 Type string `json:"type"`
252 ID string `json:"id"`
253 Name string `json:"name"`
254 Args json.RawMessage `json:"args"`
255}
256
257type EventFromHost struct {
258 Type string `json:"type"`
259 Event string `json:"event"`
260 Step int `json:"step,omitempty"`
261 Stop string `json:"stop,omitempty"`
262 Error string `json:"error,omitempty"`
263 ToolID string `json:"tool_id,omitempty"`
264 ToolName string `json:"tool_name,omitempty"`
265 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
266 ToolPreview string `json:"tool_preview,omitempty"`
267 Text string `json:"text,omitempty"`
268 Session *SessionContext `json:"session,omitempty"`
269 // State is private to the receiving extension. The manager selects the
270 // matching extension-owned snapshot before sending the event.
271 State json.RawMessage `json:"state,omitempty"`
272}
273
274type EventInterceptFromHost struct {
275 Type string `json:"type"`
276 ID string `json:"id"`
277 Event string `json:"event"`
278 ToolID string `json:"tool_id,omitempty"`
279 ToolName string `json:"tool_name,omitempty"`
280 ToolArgs json.RawMessage `json:"tool_args,omitempty"`
281 Step int `json:"step,omitempty"`
282 Text string `json:"text,omitempty"`
283}
284
285type PanelKeyFromHost struct {
286 Type string `json:"type"`
287 PanelID string `json:"panel_id"`
288 Key string `json:"key"`
289 Text string `json:"text,omitempty"`
290}
291
292type PanelResizeFromHost struct {
293 Type string `json:"type"`
294 PanelID string `json:"panel_id"`
295 Width int `json:"width"`
296 Height int `json:"height"`
297}
298
299type PanelCloseFromHost struct {
300 Type string `json:"type"`
301 PanelID string `json:"panel_id"`
302}
303
304type ShutdownFromHost struct {
305 Type string `json:"type"`
306}
307
308func Encode(v any) ([]byte, error) {
309 b, err := json.Marshal(v)
310 if err != nil {
311 return nil, err
312 }
313 return append(b, '\n'), nil
314}