1package zed:extension;
2
3world extension {
4 import context-server;
5 import dap;
6 import github;
7 import http-client;
8 import platform;
9 import process;
10 import nodejs;
11 import llm-provider;
12
13 use common.{env-vars, range};
14 use context-server.{context-server-configuration};
15 use dap.{attach-request, build-task-template, debug-config, debug-adapter-binary, debug-task-definition, debug-request, debug-scenario, launch-request, resolved-task, start-debugging-request-arguments-request};
16 use lsp.{completion, symbol};
17 use process.{command};
18 use slash-command.{slash-command, slash-command-argument-completion, slash-command-output};
19 use llm-provider.{
20 provider-info, model-info, completion-request,
21 cache-configuration, completion-event, token-usage,
22 device-flow-prompt-info
23 };
24
25 /// Initializes the extension.
26 export init-extension: func();
27
28 /// The type of a downloaded file.
29 enum downloaded-file-type {
30 /// A gzipped file (`.gz`).
31 gzip,
32 /// A gzipped tar archive (`.tar.gz`).
33 gzip-tar,
34 /// A ZIP file (`.zip`).
35 zip,
36 /// An uncompressed file.
37 uncompressed,
38 }
39
40 /// The installation status for a language server.
41 variant language-server-installation-status {
42 /// The language server has no installation status.
43 none,
44 /// The language server is being downloaded.
45 downloading,
46 /// The language server is checking for updates.
47 checking-for-update,
48 /// The language server installation failed for specified reason.
49 failed(string),
50 }
51
52 record settings-location {
53 worktree-id: u64,
54 path: string,
55 }
56
57 import get-settings: func(path: option<settings-location>, category: string, key: option<string>) -> result<string, string>;
58
59 /// Downloads a file from the given URL and saves it to the given path within the extension's
60 /// working directory.
61 ///
62 /// The file will be extracted according to the given file type.
63 import download-file: func(url: string, file-path: string, file-type: downloaded-file-type) -> result<_, string>;
64
65 /// Makes the file at the given path executable.
66 import make-file-executable: func(filepath: string) -> result<_, string>;
67
68 /// Updates the installation status for the given language server.
69 import set-language-server-installation-status: func(language-server-name: string, status: language-server-installation-status);
70
71 /// A Zed worktree.
72 resource worktree {
73 /// Returns the ID of the worktree.
74 id: func() -> u64;
75 /// Returns the root path of the worktree.
76 root-path: func() -> string;
77 /// Returns the textual contents of the specified file in the worktree.
78 read-text-file: func(path: string) -> result<string, string>;
79 /// Returns the path to the given binary name, if one is present on the `$PATH`.
80 which: func(binary-name: string) -> option<string>;
81 /// Returns the current shell environment.
82 shell-env: func() -> env-vars;
83 }
84
85 /// A Zed project.
86 resource project {
87 /// Returns the IDs of all of the worktrees in this project.
88 worktree-ids: func() -> list<u64>;
89 }
90
91 /// A key-value store.
92 resource key-value-store {
93 /// Inserts an entry under the specified key.
94 insert: func(key: string, value: string) -> result<_, string>;
95 }
96
97 /// Returns the command used to start up the language server.
98 export language-server-command: func(language-server-id: string, worktree: borrow<worktree>) -> result<command, string>;
99
100 /// Returns the initialization options to pass to the language server on startup.
101 ///
102 /// The initialization options are represented as a JSON string.
103 export language-server-initialization-options: func(language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;
104
105 /// Returns the workspace configuration options to pass to the language server.
106 export language-server-workspace-configuration: func(language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;
107
108 /// Returns the initialization options to pass to the other language server.
109 export language-server-additional-initialization-options: func(language-server-id: string, target-language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;
110
111 /// Returns the workspace configuration options to pass to the other language server.
112 export language-server-additional-workspace-configuration: func(language-server-id: string, target-language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;
113
114 /// A label containing some code.
115 record code-label {
116 /// The source code to parse with Tree-sitter.
117 code: string,
118 /// The spans to display in the label.
119 spans: list<code-label-span>,
120 /// The range of the displayed label to include when filtering.
121 filter-range: range,
122 }
123
124 /// A span within a code label.
125 variant code-label-span {
126 /// A range into the parsed code.
127 code-range(range),
128 /// A span containing a code literal.
129 literal(code-label-span-literal),
130 }
131
132 /// A span containing a code literal.
133 record code-label-span-literal {
134 /// The literal text.
135 text: string,
136 /// The name of the highlight to use for this literal.
137 highlight-name: option<string>,
138 }
139
140 export labels-for-completions: func(language-server-id: string, completions: list<completion>) -> result<list<option<code-label>>, string>;
141 export labels-for-symbols: func(language-server-id: string, symbols: list<symbol>) -> result<list<option<code-label>>, string>;
142
143
144 /// Returns the completions that should be shown when completing the provided slash command with the given query.
145 export complete-slash-command-argument: func(command: slash-command, args: list<string>) -> result<list<slash-command-argument-completion>, string>;
146
147 /// Returns the output from running the provided slash command.
148 export run-slash-command: func(command: slash-command, args: list<string>, worktree: option<borrow<worktree>>) -> result<slash-command-output, string>;
149
150 /// Returns the command used to start up a context server.
151 export context-server-command: func(context-server-id: string, project: borrow<project>) -> result<command, string>;
152
153 /// Returns the configuration for a context server.
154 export context-server-configuration: func(context-server-id: string, project: borrow<project>) -> result<option<context-server-configuration>, string>;
155
156 /// Returns a list of packages as suggestions to be included in the `/docs`
157 /// search results.
158 ///
159 /// This can be used to provide completions for known packages (e.g., from the
160 /// local project or a registry) before a package has been indexed.
161 export suggest-docs-packages: func(provider-name: string) -> result<list<string>, string>;
162
163 /// Indexes the docs for the specified package.
164 export index-docs: func(provider-name: string, package-name: string, database: borrow<key-value-store>) -> result<_, string>;
165
166 /// Returns a configured debug adapter binary for a given debug task.
167 export get-dap-binary: func(adapter-name: string, config: debug-task-definition, user-installed-path: option<string>, worktree: borrow<worktree>) -> result<debug-adapter-binary, string>;
168 /// Returns the kind of a debug scenario (launch or attach).
169 export dap-request-kind: func(adapter-name: string, config: string) -> result<start-debugging-request-arguments-request, string>;
170 export dap-config-to-scenario: func(config: debug-config) -> result<debug-scenario, string>;
171 export dap-locator-create-scenario: func(locator-name: string, build-config-template: build-task-template, resolved-label: string, debug-adapter-name: string) -> option<debug-scenario>;
172 export run-dap-locator: func(locator-name: string, config: resolved-task) -> result<debug-request, string>;
173
174 /// Returns information about language model providers offered by this extension.
175 export llm-providers: func() -> list<provider-info>;
176
177 /// Returns the models available for a provider.
178 export llm-provider-models: func(provider-id: string) -> result<list<model-info>, string>;
179
180 /// Returns markdown content to display in the provider's settings UI.
181 /// This can include setup instructions, links to documentation, etc.
182 export llm-provider-settings-markdown: func(provider-id: string) -> option<string>;
183
184 /// Check if the provider is authenticated.
185 export llm-provider-is-authenticated: func(provider-id: string) -> bool;
186
187 /// Start an OAuth device flow sign-in.
188 /// This is called when the user explicitly clicks "Sign in with GitHub" or similar.
189 ///
190 /// The device flow works as follows:
191 /// 1. Extension requests a device code from the OAuth provider
192 /// 2. Extension returns prompt info including user code and verification URL
193 /// 3. Host displays a modal with the prompt info
194 /// 4. Host calls llm-provider-poll-device-flow-sign-in
195 /// 5. Extension polls for the access token while user authorizes in browser
196 /// 6. Once authorized, extension stores the credential and returns success
197 ///
198 /// Returns information needed to display the device flow prompt modal.
199 export llm-provider-start-device-flow-sign-in: func(provider-id: string) -> result<device-flow-prompt-info, string>;
200
201 /// Poll for device flow sign-in completion.
202 /// This is called after llm-provider-start-device-flow-sign-in returns the user code.
203 /// The extension should poll the OAuth provider until the user authorizes or the flow times out.
204 /// Returns Ok(()) on successful authentication, or an error message on failure.
205 export llm-provider-poll-device-flow-sign-in: func(provider-id: string) -> result<_, string>;
206
207 /// Reset credentials for the provider.
208 export llm-provider-reset-credentials: func(provider-id: string) -> result<_, string>;
209
210 /// Count tokens for a request.
211 export llm-count-tokens: func(
212 provider-id: string,
213 model-id: string,
214 request: completion-request
215 ) -> result<u64, string>;
216
217 /// Start streaming a completion from the model.
218 /// Returns a stream ID that can be used with llm-stream-next and llm-stream-close.
219 export llm-stream-completion-start: func(
220 provider-id: string,
221 model-id: string,
222 request: completion-request
223 ) -> result<string, string>;
224
225 /// Get the next event from a completion stream.
226 /// Returns None when the stream is complete.
227 export llm-stream-completion-next: func(
228 stream-id: string
229 ) -> result<option<completion-event>, string>;
230
231 /// Close a completion stream and release its resources.
232 export llm-stream-completion-close: func(
233 stream-id: string
234 );
235
236 /// Get cache configuration for a model (if prompt caching is supported).
237 export llm-cache-configuration: func(
238 provider-id: string,
239 model-id: string
240 ) -> option<cache-configuration>;
241
242}