1interface llm-provider {
2 /// Information about a language model provider.
3 record provider-info {
4 /// Unique identifier for the provider (e.g., "my-extension.my-provider").
5 id: string,
6 /// Display name for the provider.
7 name: string,
8 /// Path to an SVG icon file relative to the extension root (e.g., "icons/provider.svg").
9 icon: option<string>,
10 }
11
12 /// Capabilities of a language model.
13 record model-capabilities {
14 /// Whether the model supports image inputs.
15 supports-images: bool,
16 /// Whether the model supports tool/function calling.
17 supports-tools: bool,
18 /// Whether the model supports the "auto" tool choice.
19 supports-tool-choice-auto: bool,
20 /// Whether the model supports the "any" tool choice.
21 supports-tool-choice-any: bool,
22 /// Whether the model supports the "none" tool choice.
23 supports-tool-choice-none: bool,
24 /// Whether the model supports extended thinking/reasoning.
25 supports-thinking: bool,
26 /// The format for tool input schemas.
27 tool-input-format: tool-input-format,
28 }
29
30 /// Format for tool input schemas.
31 enum tool-input-format {
32 /// Standard JSON Schema format.
33 json-schema,
34 /// Simplified schema format for certain providers.
35 simplified,
36 }
37
38 /// Information about a specific model.
39 record model-info {
40 /// Unique identifier for the model.
41 id: string,
42 /// Display name for the model.
43 name: string,
44 /// Maximum input token count.
45 max-token-count: u64,
46 /// Maximum output tokens (optional).
47 max-output-tokens: option<u64>,
48 /// Model capabilities.
49 capabilities: model-capabilities,
50 /// Whether this is the default model for the provider.
51 is-default: bool,
52 /// Whether this is the default fast model.
53 is-default-fast: bool,
54 }
55
56 /// The role of a message participant.
57 enum message-role {
58 /// User message.
59 user,
60 /// Assistant message.
61 assistant,
62 /// System message.
63 system,
64 }
65
66 /// A message in a completion request.
67 record request-message {
68 /// The role of the message sender.
69 role: message-role,
70 /// The content of the message.
71 content: list<message-content>,
72 /// Whether to cache this message for prompt caching.
73 cache: bool,
74 }
75
76 /// Content within a message.
77 variant message-content {
78 /// Plain text content.
79 text(string),
80 /// Image content.
81 image(image-data),
82 /// A tool use request from the assistant.
83 tool-use(tool-use),
84 /// A tool result from the user.
85 tool-result(tool-result),
86 /// Thinking/reasoning content.
87 thinking(thinking-content),
88 /// Redacted/encrypted thinking content.
89 redacted-thinking(string),
90 }
91
92 /// Image data for vision models.
93 record image-data {
94 /// Base64-encoded image data.
95 source: string,
96 /// Image width in pixels (optional).
97 width: option<u32>,
98 /// Image height in pixels (optional).
99 height: option<u32>,
100 }
101
102 /// A tool use request from the model.
103 record tool-use {
104 /// Unique identifier for this tool use.
105 id: string,
106 /// The name of the tool being used.
107 name: string,
108 /// JSON string of the tool input arguments.
109 input: string,
110 /// Thought signature for providers that support it (e.g., Anthropic).
111 thought-signature: option<string>,
112 }
113
114 /// A tool result to send back to the model.
115 record tool-result {
116 /// The ID of the tool use this is a result for.
117 tool-use-id: string,
118 /// The name of the tool.
119 tool-name: string,
120 /// Whether this result represents an error.
121 is-error: bool,
122 /// The content of the result.
123 content: tool-result-content,
124 }
125
126 /// Content of a tool result.
127 variant tool-result-content {
128 /// Text result.
129 text(string),
130 /// Image result.
131 image(image-data),
132 }
133
134 /// Thinking/reasoning content from models that support extended thinking.
135 record thinking-content {
136 /// The thinking text.
137 text: string,
138 /// Signature for the thinking block (provider-specific).
139 signature: option<string>,
140 }
141
142 /// A tool definition for function calling.
143 record tool-definition {
144 /// The name of the tool.
145 name: string,
146 /// Description of what the tool does.
147 description: string,
148 /// JSON Schema for input parameters.
149 input-schema: string,
150 }
151
152 /// Tool choice preference for the model.
153 enum tool-choice {
154 /// Let the model decide whether to use tools.
155 auto,
156 /// Force the model to use at least one tool.
157 any,
158 /// Prevent the model from using tools.
159 none,
160 }
161
162 /// A completion request to send to the model.
163 record completion-request {
164 /// The messages in the conversation.
165 messages: list<request-message>,
166 /// Available tools for the model to use.
167 tools: list<tool-definition>,
168 /// Tool choice preference.
169 tool-choice: option<tool-choice>,
170 /// Stop sequences to end generation.
171 stop-sequences: list<string>,
172 /// Temperature for sampling (0.0-1.0).
173 temperature: option<f32>,
174 /// Whether thinking/reasoning is allowed.
175 thinking-allowed: bool,
176 /// Maximum tokens to generate.
177 max-tokens: option<u64>,
178 }
179
180 /// Events emitted during completion streaming.
181 variant completion-event {
182 /// Completion has started.
183 started,
184 /// Text content chunk.
185 text(string),
186 /// Thinking/reasoning content chunk.
187 thinking(thinking-content),
188 /// Redacted thinking (encrypted) chunk.
189 redacted-thinking(string),
190 /// Tool use request from the model.
191 tool-use(tool-use),
192 /// JSON parse error when parsing tool input.
193 tool-use-json-parse-error(tool-use-json-parse-error),
194 /// Completion stopped.
195 stop(stop-reason),
196 /// Token usage update.
197 usage(token-usage),
198 /// Reasoning details (provider-specific JSON).
199 reasoning-details(string),
200 }
201
202 /// Error information when tool use JSON parsing fails.
203 record tool-use-json-parse-error {
204 /// The tool use ID.
205 id: string,
206 /// The tool name.
207 tool-name: string,
208 /// The raw input that failed to parse.
209 raw-input: string,
210 /// The parse error message.
211 error: string,
212 }
213
214 /// Reason the completion stopped.
215 enum stop-reason {
216 /// The model finished generating.
217 end-turn,
218 /// Maximum tokens reached.
219 max-tokens,
220 /// The model wants to use a tool.
221 tool-use,
222 /// The model refused to respond.
223 refusal,
224 }
225
226 /// Token usage statistics.
227 record token-usage {
228 /// Number of input tokens used.
229 input-tokens: u64,
230 /// Number of output tokens generated.
231 output-tokens: u64,
232 /// Tokens used for cache creation (if supported).
233 cache-creation-input-tokens: option<u64>,
234 /// Tokens read from cache (if supported).
235 cache-read-input-tokens: option<u64>,
236 }
237
238 /// Credential types that can be requested.
239 enum credential-type {
240 /// An API key.
241 api-key,
242 /// An OAuth token.
243 oauth-token,
244 }
245
246 /// Cache configuration for prompt caching.
247 record cache-configuration {
248 /// Maximum number of cache anchors.
249 max-cache-anchors: u32,
250 /// Whether caching should be applied to tool definitions.
251 should-cache-tool-definitions: bool,
252 /// Minimum token count for a message to be cached.
253 min-total-token-count: u64,
254 }
255
256 // =========================================================================
257 // OAuth Web Auth Flow Types
258 // =========================================================================
259
260 /// Configuration for starting an OAuth web authentication flow.
261 record oauth-web-auth-config {
262 /// The URL to open in the user's browser to start authentication.
263 /// This should include client_id, redirect_uri, scope, state, etc.
264 auth-url: string,
265 /// The path to listen on for the OAuth callback (e.g., "/callback").
266 /// A localhost server will be started to receive the redirect.
267 callback-path: string,
268 /// Timeout in seconds to wait for the callback (default: 300 = 5 minutes).
269 timeout-secs: option<u32>,
270 }
271
272 /// Result of an OAuth web authentication flow.
273 record oauth-web-auth-result {
274 /// The full callback URL that was received, including query parameters.
275 /// The extension is responsible for parsing the code, state, etc.
276 callback-url: string,
277 /// The port that was used for the localhost callback server.
278 port: u32,
279 }
280
281 /// A generic HTTP request for OAuth token exchange.
282 record oauth-http-request {
283 /// The URL to request.
284 url: string,
285 /// HTTP method (e.g., "POST", "GET").
286 method: string,
287 /// Request headers as key-value pairs.
288 headers: list<tuple<string, string>>,
289 /// Request body as a string (for form-encoded or JSON bodies).
290 body: string,
291 }
292
293 /// Response from an OAuth HTTP request.
294 record oauth-http-response {
295 /// HTTP status code.
296 status: u16,
297 /// Response headers as key-value pairs.
298 headers: list<tuple<string, string>>,
299 /// Response body as a string.
300 body: string,
301 }
302}