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 /// Cache configuration for prompt caching.
239 record cache-configuration {
240 /// Maximum number of cache anchors.
241 max-cache-anchors: u32,
242 /// Whether caching should be applied to tool definitions.
243 should-cache-tool-definitions: bool,
244 /// Minimum token count for a message to be cached.
245 min-total-token-count: u64,
246 }
247
248 /// Configuration for starting an OAuth web authentication flow.
249 record oauth-web-auth-config {
250 /// The URL to open in the user's browser to start authentication.
251 /// This should include client_id, redirect_uri, scope, state, etc.
252 /// Use `{port}` as a placeholder in the URL - it will be replaced with
253 /// the actual localhost port before opening the browser.
254 /// Example: "https://example.com/oauth?redirect_uri=http://127.0.0.1:{port}/callback"
255 auth-url: string,
256 /// The path to listen on for the OAuth callback (e.g., "/callback").
257 /// A localhost server will be started to receive the redirect.
258 callback-path: string,
259 /// Timeout in seconds to wait for the callback (default: 300 = 5 minutes).
260 timeout-secs: option<u32>,
261 }
262
263 /// Result of an OAuth web authentication flow.
264 record oauth-web-auth-result {
265 /// The full callback URL that was received, including query parameters.
266 /// The extension is responsible for parsing the code, state, etc.
267 callback-url: string,
268 /// The port that was used for the localhost callback server.
269 port: u32,
270 }
271
272 /// A generic HTTP request for OAuth token exchange.
273 record oauth-http-request {
274 /// The URL to request.
275 url: string,
276 /// HTTP method (e.g., "POST", "GET").
277 method: string,
278 /// Request headers as key-value pairs.
279 headers: list<tuple<string, string>>,
280 /// Request body as a string (for form-encoded or JSON bodies).
281 body: string,
282 }
283
284 /// Response from an OAuth HTTP request.
285 record oauth-http-response {
286 /// HTTP status code.
287 status: u16,
288 /// Response headers as key-value pairs.
289 headers: list<tuple<string, string>>,
290 /// Response body as a string.
291 body: string,
292 }
293
294 /// Get a stored credential for this provider.
295 get-credential: func(provider-id: string) -> option<string>;
296
297 /// Store a credential for this provider.
298 store-credential: func(provider-id: string, value: string) -> result<_, string>;
299
300 /// Delete a stored credential for this provider.
301 delete-credential: func(provider-id: string) -> result<_, string>;
302
303 /// Read an environment variable.
304 get-env-var: func(name: string) -> option<string>;
305
306 /// Start an OAuth web authentication flow.
307 ///
308 /// This will:
309 /// 1. Start a localhost server to receive the OAuth callback
310 /// 2. Open the auth URL in the user's default browser
311 /// 3. Wait for the callback (up to the timeout)
312 /// 4. Return the callback URL with query parameters
313 ///
314 /// The extension is responsible for:
315 /// - Constructing the auth URL with client_id, redirect_uri, scope, state, etc.
316 /// - Parsing the callback URL to extract the authorization code
317 /// - Exchanging the code for tokens using oauth-http-request
318 oauth-start-web-auth: func(config: oauth-web-auth-config) -> result<oauth-web-auth-result, string>;
319
320 /// Make an HTTP request for OAuth token exchange.
321 ///
322 /// This is a simple HTTP client for OAuth flows, allowing the extension
323 /// to handle token exchange with full control over serialization.
324 oauth-send-http-request: func(request: oauth-http-request) -> result<oauth-http-response, string>;
325
326 /// Open a URL in the user's default browser.
327 ///
328 /// Useful for OAuth flows that need to open a browser but handle the
329 /// callback differently (e.g., polling-based flows).
330 oauth-open-browser: func(url: string) -> result<_, string>;
331}