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