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
22// ProtocolVersion is the major version of this wire format. Bumped
23// for breaking changes; minor additions don't bump.
24const ProtocolVersion = 1
25
26// Frame is the lowest-common-denominator parse target so a reader can
27// peek at the type before unmarshalling the full payload.
28type Frame struct {
29 Type string `json:"type"`
30 ID string `json:"id,omitempty"`
31}
32
33// ---- extension -> host ----
34
35// HelloFromExt is the first frame the extension sends after start.
36// Zot replies with HelloAckFromHost, then registration frames
37// (RegisterCommandFromExt, etc.) flow.
38type HelloFromExt struct {
39 Type string `json:"type"` // "hello"
40 Name string `json:"name"`
41 Version string `json:"version"`
42 Capabilities []string `json:"capabilities,omitempty"`
43}
44
45// RegisterCommandFromExt asks zot to bind /name to this extension.
46// Description appears in the slash autocomplete + /help.
47type RegisterCommandFromExt struct {
48 Type string `json:"type"` // "register_command"
49 Name string `json:"name"`
50 Description string `json:"description,omitempty"`
51}
52
53// RegisterToolFromExt asks zot to expose a tool to the LLM. The
54// schema is a JSON Schema object describing Args; zot doesn't validate
55// the model's arguments against it (the model providers do that), but
56// it must parse as valid JSON or registration is rejected.
57//
58// Tool names live in the same namespace as built-in tools (read,
59// write, edit, bash, skill). Conflicts are silently shadowed by the
60// built-in; check the extension's log for a warning.
61type RegisterToolFromExt struct {
62 Type string `json:"type"` // "register_tool"
63 Name string `json:"name"`
64 Description string `json:"description,omitempty"`
65 Schema json.RawMessage `json:"schema"`
66}
67
68// ReadyFromExt signals "all initial registrations sent". The host
69// waits for this (with a short timeout) before building the agent's
70// tool registry, so model calls don't race extension tool
71// registration.
72type ReadyFromExt struct {
73 Type string `json:"type"` // "ready"
74}
75
76// ToolResultFromExt is the extension's reply to a ToolCallFromHost.
77// Content[] follows the same shape as elsewhere in zot:
78//
79// {"type":"text", "text":"..."}
80// {"type":"image", "mime_type":"image/png", "data":"<base64>"}
81//
82// Set IsError true to mark the tool call as failed; the model sees
83// the content as the error explanation.
84type ToolResultFromExt struct {
85 Type string `json:"type"` // "tool_result"
86 ID string `json:"id"`
87 Content []ContentBlock `json:"content"`
88 IsError bool `json:"is_error,omitempty"`
89}
90
91// ContentBlock is one entry in a tool result's content array.
92type ContentBlock struct {
93 Type string `json:"type"` // "text" | "image"
94 Text string `json:"text,omitempty"`
95 MimeType string `json:"mime_type,omitempty"`
96 Data string `json:"data,omitempty"` // base64
97}
98
99// CommandResponseFromExt is the extension's answer to a
100// CommandInvokedFromHost. Action drives what zot does next:
101//
102// - "prompt" → submit Prompt as a fresh user message to the agent
103// - "insert" → insert Insert into the editor buffer at the cursor
104// - "display" → append Display to the chat as a one-shot note
105// (no model call, no transcript entry)
106// - "noop" → command handled internally, no UI change
107type CommandResponseFromExt struct {
108 Type string `json:"type"` // "command_response"
109 ID string `json:"id"`
110 Action string `json:"action"` // see above
111 Prompt string `json:"prompt,omitempty"` // for action=prompt
112 Insert string `json:"insert,omitempty"` // for action=insert
113 Display string `json:"display,omitempty"` // for action=display
114 Error string `json:"error,omitempty"` // command failed; render to user
115}
116
117// NotifyFromExt is a one-way status message the extension can push at
118// any time. Zot renders it in the chat as a styled note.
119type NotifyFromExt struct {
120 Type string `json:"type"` // "notify"
121 Level string `json:"level"` // "info" | "warn" | "error" | "success"
122 Message string `json:"message"`
123}
124
125// ShutdownAckFromExt acknowledges the host's shutdown request. The
126// extension should exit shortly after sending this; zot waits a few
127// seconds before SIGTERM.
128type ShutdownAckFromExt struct {
129 Type string `json:"type"` // "shutdown_ack"
130}
131
132// ---- host -> extension ----
133
134// HelloAckFromHost is zot's reply to HelloFromExt. The extension may
135// inspect the host version + currently-active provider/model to decide
136// whether to register particular commands.
137type HelloAckFromHost struct {
138 Type string `json:"type"` // "hello_ack"
139 ProtocolVersion int `json:"protocol_version"`
140 ZotVersion string `json:"zot_version"`
141 Provider string `json:"provider"`
142 Model string `json:"model"`
143 CWD string `json:"cwd"`
144}
145
146// CommandInvokedFromHost is sent when the user runs a slash command
147// the extension previously registered. Args contains everything after
148// the command name (already trimmed).
149type CommandInvokedFromHost struct {
150 Type string `json:"type"` // "command_invoked"
151 ID string `json:"id"`
152 Name string `json:"name"`
153 Args string `json:"args,omitempty"`
154}
155
156// ToolCallFromHost is sent when the LLM invokes a tool the extension
157// registered. Args is the raw JSON object the model produced; the
158// extension is responsible for validating/coercing it. Reply with
159// ToolResultFromExt within the host's tool timeout (default 60s).
160type ToolCallFromHost struct {
161 Type string `json:"type"` // "tool_call"
162 ID string `json:"id"`
163 Name string `json:"name"`
164 Args json.RawMessage `json:"args"`
165}
166
167// ShutdownFromHost asks the extension to clean up and exit. Zot
168// sends this when the user runs /reload-ext or zot itself is exiting
169// gracefully. Extensions that don't reply within a few seconds get
170// SIGTERM; SIGKILL after a few more.
171type ShutdownFromHost struct {
172 Type string `json:"type"` // "shutdown"
173}
174
175// ---- error frame (either direction) ----
176
177// Error is a generic failure response. Used by either side when a
178// frame can't be processed (malformed JSON, unknown type, etc.).
179type Error struct {
180 Type string `json:"type"` // "error"
181 ID string `json:"id,omitempty"`
182 Message string `json:"message"`
183}
184
185// ---- helpers ----
186
187// Encode marshals v and appends a trailing LF, ready to write to the
188// peer's pipe. Returns the marshalling error, if any.
189func Encode(v any) ([]byte, error) {
190 b, err := json.Marshal(v)
191 if err != nil {
192 return nil, err
193 }
194 return append(b, '\n'), nil
195}