Protocol specification
The current protocol version is 0.1.
Provider API
Providers can be implemented:
- as an HTTP endpoint.
- as a JavaScript file (with a
default
export). See "Creating a provider".
Both ways of implementing a provider use the same methods and types for communication. For simplicity, this document describes the protocol as implemented over HTTP.
A provider is specified by a URL that responds to HTTP POST requests.
- Request body (JSON):
interface RequestMessage { method: string, params?: object, settings?: object }
- Response body (JSON):
interface ResponseMessage { result?: object, error?: { code: integer, message: string, data?: any } }
Providers are stateless.
Providers implement the following API methods:
- Meta: report the provider's name, features, and other metadata (required)
- Mentions: search for @-mentionable items
- Items: fetch documents and other content from the provider
- Annotations: get annotations for a code file
Meta
The meta request is sent by the client to the provider to retrieve the provider's name, features, other metadata, and when it should be invoked. This avoids unnecessary invocations of the provider on resources where it would not have any results.
Request: { method: "meta", params: MetaParams, settings?: object }
interface MetaParams { // empty for now}
Response: { result: MetaResult }
or { error: { code, integer, data? } }
interface MetaResult { /** * The name of the provider. */ name: string /** * Configuration for providing context items. */ items?: { /** * The list of regex patterns for matching with a message for which the provider can return context items */ messageSelectors?: MessageSelector[] } /** * Configuration for the mentions feature. */ mentions?: { /** * The label that is shown when a user wants to query mentions. For example `Search...` or `Paste Linear URL`. */ label?: string /** * EXPERIMENTAL: Whether to automatically include the returned mention items as initial context for new messages. */ autoInclude?: string } /** * Configuration for the annotations feature. */ annotations?: { /** * A list of patterns matching the mention text for which the provider can return mentions */ selectors?: AnnotationSelector[] }}/** * List of regex patterns matching a message for which the provider can return context items. */interface MessageSelector { /** * The regex pattern matching a message for which the provider can return context items */ pattern: string}/** * Defines a scope in which a provider is called. * * To satisfy a selector, all of the selector's conditions must be met. For example, if both `path` and `content` are specified, the resource must satisfy both conditions. */interface AnnotationSelector { /** * A glob that must match the resource's hostname and path. * * Use `** /` before the glob to match in any parent directory. Use `/**` after the glob to match any resources under a directory. Leading slashes are stripped from the path before being matched against the glob. */ path?: string /** * A literal string that must be present in the resource's content. */ contentContains?: string}
Mentions
The mentions request is sent by the client to the provider to search for @-mentionable items in the resource.
Request: { method: "mentions", params: MentionsParams, settings?: object }
export interface MentionsParams { /** * A search query that is interpreted by providers to filter the items in the result set. */ query?: string /** * URI of the active document. */ uri?: string /** * Name of the active codebase. */ codebase?: string /** * Whether the request if to get automatically include default context. */ autoInclude?: string}
Response: { result: MentionsResult }
or { error: { code, integer, data? } }
type MentionsResult = Mention[]/** * A mention contains presentation information relevant to a resource. */export interface Mention { /** * A descriptive title. */ title: string /** * An item description. */ description?: string /** * A URI for the mention item. */ uri: string data?: { [k: string]: unknown | undefined }}
Items
The items request is sent by the client to the provider to fetch items from a resource.
Request: { method: "items", params: ItemsParams, settings?: object }
interface ItemsParams { /** * A message that is interpreted by providers to return relevant items. */ message?: string /** * A mention interpreted by providers to return items for the specified mention. */ mention?: Mention}
Response: { result: ItemsResult }
or { error: { code, integer, data? } }
type ItemsResult = Item[]/** * An item describes information relevant to a resource (or a range within a resource). */interface Item { /** * A descriptive title of the item. */ title: string /** * An external URL with more information about the item. */ url?: string /** * The human user interface of the item, with information for human consumption. */ ui?: UserInterface /** * Information from the item intended for consumption by AI, not humans. */ ai?: AssistantInfo}/** * The human user interface of the item, with information for human consumption. */interface UserInterface { /** * Additional information for the human, shown in a tooltip-like widget when they interact with the item. */ hover?: { markdown?: string, text?: string }}/** * Information from the item intended for consumption by AI, not humans. */interface AssistantInfo { /** * Text content for AI to consume. */ content?: string}interface Position { /** Line number (0-indexed). */ line: number /** Character offset on line (0-indexed). */ character: number}
Annotations
The annotations request is sent by the client to the provider to fetch a list of annotations for a resource (such as a code file).
Request: { method: "annotations", params: AnnotationsParams, settings?: object }
interface AnnotationsParams { /** The resource's URI (e.g., `file:///home/alice/foo.js`). **/ uri: string /** The resource's content. **/ content: string}
Response: { result: AnnotationsResult }
or { error: { code, integer, data? } }
type AnnotationsResult = Annotation[]/** * An annotation attaches an Item to a range in a document. */interface Annotation { /** The URI of the document. */ uri: string /** * The range in the resource that this item applies to. If not set, the item applies to the entire resource. */ range?: { start: Position; end: Position } /** The item containing the content to annotate at the range. */ item: Item}