Commands

Commands are JSON-RPC requests from the client to the server. They return a result or a JSON-RPC error.

JSON Schema: commands.schema.json

`initialize` 📄

Establishes a new connection and negotiates the protocol version. This MUST be the first message sent by the client.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`protocolVersions`	`string[]`	Yes	Protocol versions the client is willing to speak, ordered from most
preferred to least preferred. Each entry is a SemVer
`MAJOR.MINOR.PATCH` string (e.g. `"0.1.0"`).

Result:

Field	Type	Required	Description
`protocolVersion`	`string`	Yes	Protocol version selected by the server. MUST be one of the entries in
`InitializeParams.protocolVersions`. Formatted as a SemVer
`MAJOR.MINOR.PATCH` string (e.g. `"0.1.0"`).
`serverSeq`	`number`	Yes	Current server sequence number
`snapshots`	`Snapshot[]`	Yes	Snapshots for each `initialSubscriptions` URI
`defaultDirectory`	URI	No	Suggested default directory for remote filesystem browsing
`completionTriggerCharacters`	`string[]`	No	Characters that, when typed in a {@link UserMessage} input, SHOULD cause
the client to issue a `completions` request with
{@link CompletionItemKind.UserMessage}. Typically includes characters like
`'@'` or `'/'`.

See Lifecycle for details.

`reconnect` 📄

Re-establishes a dropped connection. The server replays missed actions or provides fresh snapshots.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Description
`clientId`	`string`	Client identifier from the original connection
`lastSeenServerSeq`	`number`	Last `serverSeq` the client received
`subscriptions`	URI[]	URIs the client was subscribed to

Result (replay): When the server can replay from the requested sequence:

Field	Type	Description
`type`	`ReconnectResultType.Replay`	Discriminant
`actions`	`ActionEnvelope[]`	Missed action envelopes since `lastSeenServerSeq`
`missing`	URI[]	URIs from `ReconnectParams.subscriptions` that the server cannot resume.
This includes resources that no longer exist (e.g. disposed sessions or
terminals) as well as resources the client is no longer permitted to
observe. Clients SHOULD drop these from their local subscription set.

Result (snapshot): When the gap exceeds the replay buffer:

Field	Type	Description
`type`	`ReconnectResultType.Snapshot`	Discriminant
`snapshots`	`Snapshot[]`	Fresh snapshots for each subscription

Reconnect result when the server can replay from the requested sequence.

The server MUST include all replayed data in the response.

See Lifecycle for details.

`createSession` 📄

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`session`	URI	Yes	Session URI (client-chosen, e.g. `copilot:/<uuid>`)
`provider`	`string`	No	Agent provider ID
`model`	`ModelSelection`	No	Model selection (ID and optional model-specific configuration)
`workingDirectory`	URI	No	Working directory for the session
`fork`	`SessionForkSource`	No	Fork from an existing session. The new session is populated with content
from the source session up to and including the specified turn's response.
`config`	`Record<string, unknown>`	No	Agent-specific configuration values collected via `resolveSessionConfig`.
Keys and values correspond to the schema returned by the server.
`activeClient`	`SessionActiveClient`	No	Eagerly claim the active client role for the new session.

When provided, the server initializes the session with this client as the active client, equivalent to dispatching a session/activeClientChanged action immediately after creation. The clientId MUST match the clientId the creating client supplied in initialize. |

Result: null on success.

`disposeSession` 📄

Disposes a session and cleans up server-side resources.

The server broadcasts a notify/sessionRemoved notification to all clients.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Description
`session`	URI	Session URI to dispose

Result: null on success.

The server broadcasts a notify/sessionRemoved notification to all clients.

`listSessions` 📄

Returns a list of session summaries. Used to populate session lists and sidebars.

The session list is not part of the state tree because it can be arbitrarily large. Clients fetch it imperatively and maintain a local cache updated by notify/sessionAdded and notify/sessionRemoved notifications.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`filter`	`object`	No	Optional filter criteria

Result:

Field	Type	Description
`items`	`SessionSummary[]`	The list of session summaries.

`resourceRead` 📄

Reads the content of a resource by URI.

Content references keep the state tree small by storing large data (images, long tool outputs) by reference rather than inline.

Binary content (images, etc.) MUST use base64 encoding. Text content MAY use utf-8 encoding.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`uri`	`string`	Yes	Content URI from a `ContentRef`
`encoding`	`ContentEncoding`	No	Preferred encoding for the returned data (default: server-chosen)

Result:

Field	Type	Required	Description
`data`	`string`	Yes	Content encoded as a string
`encoding`	`ContentEncoding`	Yes	How `data` is encoded
`contentType`	`string`	No	Content type (e.g. `"image/png"`, `"text/plain"`)

Example:

jsonc

// Client → Server
{ "jsonrpc": "2.0", "id": 10, "method": "resourceRead",
  "params": { "uri": "copilot:/<uuid>/content/img-1" } }

// Server → Client
{ "jsonrpc": "2.0", "id": 10, "result": {
  "data": "iVBORw0KGgo...",
  "encoding": "base64",
  "contentType": "image/png"
}}

Content references keep the state tree small by storing large data (images, long tool outputs) by reference rather than inline.

Binary content (images, etc.) MUST use base64 encoding. Text content MAY use utf-8 encoding.

`resourceWrite` 📄

Writes content to a file on the server's filesystem.

Binary content (images, etc.) MUST use base64 encoding. Text content MAY use utf-8 encoding.

If the file does not exist, it is created. If the file already exists, it is overwritten unless createOnly is set.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`uri`	URI	Yes	Target file URI on the server filesystem
`data`	`string`	Yes	Content encoded as a string
`encoding`	`ContentEncoding`	Yes	How `data` is encoded
`contentType`	`string`	No	Content type (e.g. `"text/plain"`, `"image/png"`)
`createOnly`	`boolean`	No	If `true`, the server MUST fail if the file already exists instead of
overwriting it. Useful for safe creation of new files.

Result:

Field	Type	Description

Example:

jsonc

// Client → Server
{ "jsonrpc": "2.0", "id": 11, "method": "resourceWrite",
  "params": { "uri": "file:///workspace/hello.txt", "data": "SGVsbG8=",
             "encoding": "base64", "contentType": "text/plain" } }

// Server → Client
{ "jsonrpc": "2.0", "id": 11, "result": {} }

Binary content (images, etc.) MUST use base64 encoding. Text content MAY use utf-8 encoding.

If the file does not exist, it is created. If the file already exists, it is overwritten unless createOnly is set.

`resourceList` 📄

Lists directory entries at a file URI on the server's filesystem.

This is intended for remote folder pickers and similar UI that needs to let users navigate the server's local filesystem.

The server MUST return success only if the target exists and is a directory. If the target does not exist, is not a directory, or cannot be accessed, the server MUST return a JSON-RPC error.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Description
`uri`	URI	Directory URI on the server filesystem

Result:

Field	Type	Description
`entries`	`DirectoryEntry[]`	Entries directly contained in the requested directory

This is intended for remote folder pickers and similar UI that needs to let users navigate the server's local filesystem.

The server MUST return success only if the target exists and is a directory. If the target does not exist, is not a directory, or cannot be accessed, the server MUST return a JSON-RPC error.

`resourceCopy` 📄

Copies a resource from one URI to another on the server's filesystem.

If the destination already exists, it is overwritten unless failIfExists is set.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`source`	URI	Yes	Source URI to copy from
`destination`	URI	Yes	Destination URI to copy to
`failIfExists`	`boolean`	No	If `true`, the server MUST fail if the destination already exists instead
of overwriting it.

Result:

Field	Type	Description

If the destination already exists, it is overwritten unless failIfExists is set.

`resourceDelete` 📄

Deletes a resource at a URI on the server's filesystem.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`uri`	URI	Yes	URI of the resource to delete
`recursive`	`boolean`	No	If `true` and the target is a directory, delete it and all its contents
recursively. If `false` (default), deleting a non-empty directory MUST fail.

Result:

Field	Type	Description

`resourceMove` 📄

Moves (renames) a resource from one URI to another on the server's filesystem.

If the destination already exists, it is overwritten unless failIfExists is set.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`source`	URI	Yes	Source URI to move from
`destination`	URI	Yes	Destination URI to move to
`failIfExists`	`boolean`	No	If `true`, the server MUST fail if the destination already exists instead
of overwriting it.

Result:

Field	Type	Description

If the destination already exists, it is overwritten unless failIfExists is set.

`resourceRequest` 📄

Requests permission to access a resource on the receiver's filesystem.

resourceRequest is symmetrical and MAY be sent in either direction: a client asks the server to grant access to a server-side resource, or a server asks the client to grant access to a client-side resource. The receiver decides whether to allow, deny, or prompt the user for the requested access.

If the receiver denies access, it MUST respond with PermissionDenied (-32009). The error data MAY include a ResourceRequestParams value describing the access the caller would need to be granted for the operation to succeed; see PermissionDeniedErrorData in types/errors.ts.

After a successful resourceRequest, the caller MAY use the corresponding resource* commands (e.g. resourceRead, resourceWrite) to perform the operation. Receivers MAY rescind access at any time by returning PermissionDenied on subsequent operations.

Either read, write, or both SHOULD be set to true. A request with neither flag set is treated as read: true by receivers.

Property	Value
Direction	Client ↔ Server
Type	Request

Parameters:

Field	Type	Required	Description
`uri`	URI	Yes	Resource URI being requested. Typically a `file:` URI on the receiver's
filesystem, but any URI scheme that the receiver mediates access to is
allowed.
`read`	`boolean`	No	Whether the caller needs read access to the resource.
`write`	`boolean`	No	Whether the caller needs write access to the resource.

Result:

Field	Type	Description

Either read, write, or both SHOULD be set to true. A request with neither flag set is treated as read: true by receivers.

`fetchTurns` 📄

Fetches historical turns for a session. Used for lazy loading of conversation history.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Required	Description
`session`	URI	Yes	Session URI
`before`	`string`	No	Turn ID to fetch before (exclusive). Omit to fetch from the most recent turn.
`limit`	`number`	No	Maximum number of turns to return. Server MAY impose its own upper bound.

Result:

Field	Type	Description
`turns`	`Turn[]`	The requested turns, ordered oldest-first
`hasMore`	`boolean`	Whether more turns exist before the returned range

Example:

jsonc

// Client → Server (fetch the 20 most recent turns)
{ "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
  "params": { "session": "copilot:/<uuid>", "limit": 20 } }

// Server → Client
{ "jsonrpc": "2.0", "id": 8, "result": {
  "turns": [ { "id": "t1", ... }, { "id": "t2", ... } ],
  "hasMore": true
}}

// Client → Server (fetch 20 turns before t1)
{ "jsonrpc": "2.0", "id": 9, "method": "fetchTurns",
  "params": { "session": "copilot:/<uuid>", "before": "t1", "limit": 20 } }

`completions` 📄

Requests completion items for a partially-typed input (e.g. a user message the user is currently composing). Used to power @-mention pickers, file/symbol references, and similar inline-completion experiences.

Servers SHOULD treat this command as best-effort and return promptly. The client SHOULD debounce calls to avoid flooding the server with requests on every keystroke.

Property	Value
Direction	Client → Server
Type	Request

Parameters:

Field	Type	Description
`kind`	`CompletionItemKind`	What kind of completion is being requested.
`session`	URI	The session URI the completion is being requested for.
`text`	`string`	The complete text of the input being completed (e.g. the full user
message text typed so far).
`offset`	`number`	The character offset within `text` at which the completion is requested,
measured in UTF-16 code units. MUST satisfy `0 <= offset <= text.length`.

Result:

Field	Type	Description
`items`	`CompletionItem[]`	The completion items, in the order the server suggests displaying them.

Example:

jsonc

// User has typed "look at

Servers SHOULD treat this command as best-effort and return promptly. The
client SHOULD debounce calls to avoid flooding the server with requests on
every keystroke.

---

## Client-Dispatched Actions

In addition to commands, clients interact with the server by **dispatching actions** as fire-and-forget notifications:

```jsonc
// Client → Server
{
  "jsonrpc": "2.0",
  "method": "dispatchAction",
  "params": {
    "clientSeq": 1,
    "action": { "type": "session/turnStarted", "session": "copilot:/<uuid>", ... }
  }
}

These are write-ahead: the client applies them optimistically to local state. See Actions for the full list of client-dispatchable actions.

Action	Server-side effect
`session/turnStarted`	Begins agent processing for the new turn
`session/permissionResolved`	Unblocks the pending tool execution
`session/turnCancelled`	Aborts the in-progress turn
`session/modelChanged`	Changes the model for subsequent turns

Commands ​

initialize 📄 ​

reconnect 📄 ​

createSession 📄 ​

disposeSession 📄 ​

listSessions 📄 ​

resourceRead 📄 ​

resourceWrite 📄 ​

resourceList 📄 ​

resourceCopy 📄 ​

resourceDelete 📄 ​

resourceMove 📄 ​

resourceRequest 📄 ​

fetchTurns 📄 ​

completions 📄 ​

Commands

`initialize` 📄

`reconnect` 📄

`createSession` 📄

`disposeSession` 📄

`listSessions` 📄

`resourceRead` 📄

`resourceWrite` 📄

`resourceList` 📄

`resourceCopy` 📄

`resourceDelete` 📄

`resourceMove` 📄

`resourceRequest` 📄

`fetchTurns` 📄

`completions` 📄