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 {
  /**
   * Selects the scope in which this provider should be called.
   *
   * If one or more selectors are given, all must be satisfied for the
   * provider to be called. If undefined, the provider is called on all resources.
   * If empty, the provider is never invoked.
   */
  selector?: Selector[]
}
/**
 * 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 Selector {
  /**
   * A glob that must match the resource's hostname and path.
   */
  path?: string
  /**
   * A literal string that must be present in the resource's content for the
   * provider to be called.
   */
  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
}

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
}