From c7fa82d2e94fc7135bb79248cfc333395aa89684 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Fri, 20 Mar 2026 12:47:35 +0100 Subject: [PATCH 1/4] add workspace methods rfd --- docs/docs.json | 3 +- docs/rfds/client-editor-state-methods.mdx | 181 ++++++++++++++++++++++ 2 files changed, 183 insertions(+), 1 deletion(-) create mode 100644 docs/rfds/client-editor-state-methods.mdx diff --git a/docs/docs.json b/docs/docs.json index 0a745390..79e5d37c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -125,7 +125,8 @@ "rfds/boolean-config-option", "rfds/elicitation", "rfds/session-close", - "rfds/next-edit-suggestions" + "rfds/next-edit-suggestions", + "rfds/client-editor-state-methods" ] }, { diff --git a/docs/rfds/client-editor-state-methods.mdx b/docs/rfds/client-editor-state-methods.mdx new file mode 100644 index 00000000..8c4fe97e --- /dev/null +++ b/docs/rfds/client-editor-state-methods.mdx @@ -0,0 +1,181 @@ +--- +title: "Client Editor State Methods" +--- + +- Author(s): [@anna239](https://github.com/anna239) + +## Elevator pitch + +Add three optional client methods that expose the current editor state to the agent: + +1. `workspace/open_documents` for opened files +2. `workspace/recent_documents` for recent files +3. `workspace/active_document` for the currently focused file + +These methods are intentionally shaped to match VS Code concepts (`workspace.textDocuments`, `window.activeTextEditor`, and VS Code's internal recently-opened model) while preserving ACP conventions and capability-based opt-in. All three methods live under the `workspace/` prefix for consistency. + +## Status quo + +Today ACP lets an agent read and write files (`fs/read_text_file`, `fs/write_text_file`) when it already knows a path, but there is no standard way to ask: + +1. Which files are currently opened in the editor? +2. Which files were recently opened? +3. Which file currently has focus? + +This causes practical issues: + +1. Agents must infer context from prompt text or external heuristics. +2. Clients add context unconditionally, which can decrease the agent's performance. + +## What we propose to do about it + +Introduce three optional `client` methods and corresponding capabilities: + +1. `workspace/open_documents` +2. `workspace/recent_documents` +3. `workspace/active_document` + +Agents must check capability flags before calling these methods. + +### Capability advertisement + +```json +{ + "clientCapabilities": { + "workspace": { + "openDocuments": {}, + "recentDocuments": {}, + "activeDocument": {} + } + } +} +``` + +### URI rules + +All returned `uri` values **MUST** use the `file:///` scheme with absolute paths. + +### Method: `workspace/open_documents` + +Returns currently open text documents that map to absolute file paths. + +#### Request + +```json +{ + "jsonrpc": "2.0", + "id": 11, + "method": "workspace/open_documents", + "params": { + "sessionId": "sess_abc123def456" + } +} +``` + +#### Response + +```json +{ + "jsonrpc": "2.0", + "id": 11, + "result": { + "documents": [ + { + "uri": "file:///Users/alice/dev/acp/src/client.rs", + "languageId": "rust" + }, + { + "uri": "file:///Users/alice/dev/acp/docs/protocol/file-system.mdx", + "languageId": "markdown" + } + ] + } +} +``` + +### Method: `workspace/recent_documents` + +Returns recently opened files (absolute paths), optionally bounded by `limit`. + +#### Request + +```json +{ + "jsonrpc": "2.0", + "id": 12, + "method": "workspace/recent_documents", + "params": { + "sessionId": "sess_abc123def456", + "limit": 50 + } +} +``` + +#### Response + +```json +{ + "jsonrpc": "2.0", + "id": 12, + "result": { + "documents": [ + { + "uri": "file:///Users/alice/dev/acp/src/rpc.rs", + "languageId": "rust" + }, + { + "uri": "file:///Users/alice/dev/acp/docs/protocol/session-setup.mdx", + "languageId": "markdown" + } + ] + } +} +``` + +### Method: `workspace/active_document` + +Returns the currently focused text editor file, or `null` when no file-backed text editor is focused. + +#### Request + +```json +{ + "jsonrpc": "2.0", + "id": 13, + "method": "workspace/active_document", + "params": { + "sessionId": "sess_abc123def456" + } +} +``` + +#### Response + +```json +{ + "jsonrpc": "2.0", + "id": 13, + "result": { + "document": { + "uri": "file:///Users/alice/dev/acp/src/client.rs", + "languageId": "rust", + "visibleRange": { + "start": { "line": 0, "character": 0 }, + "end": { "line": 45, "character": 0 } + } + } + } +} +``` + +## Shiny future + +Once this exists: + +1. Agents can implement their own logic for context gathering. + +## Frequently asked questions + +## Revision history + +- 2026-03-17: Initial draft. From c7dff28b00bd0b34ceb21a63755675594aebfe5e Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Fri, 20 Mar 2026 12:54:49 +0100 Subject: [PATCH 2/4] add workspace methods rfd --- docs/rfds/client-editor-state-methods.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/rfds/client-editor-state-methods.mdx b/docs/rfds/client-editor-state-methods.mdx index 8c4fe97e..2eb98fce 100644 --- a/docs/rfds/client-editor-state-methods.mdx +++ b/docs/rfds/client-editor-state-methods.mdx @@ -158,11 +158,7 @@ Returns the currently focused text editor file, or `null` when no file-backed te "result": { "document": { "uri": "file:///Users/alice/dev/acp/src/client.rs", - "languageId": "rust", - "visibleRange": { - "start": { "line": 0, "character": 0 }, - "end": { "line": 45, "character": 0 } - } + "languageId": "rust" } } } @@ -173,6 +169,7 @@ Returns the currently focused text editor file, or `null` when no file-backed te Once this exists: 1. Agents can implement their own logic for context gathering. +2. `workspace/active_document` can be extended with additional fields such as `visibleRange` and cursor `position` to provide richer editor context. ## Frequently asked questions From bad2e6059706968d1ac8fe1b063521b663130735 Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Mon, 23 Mar 2026 08:28:05 +0100 Subject: [PATCH 3/4] add workspace methods rfd --- docs/rfds/client-editor-state-methods.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/rfds/client-editor-state-methods.mdx b/docs/rfds/client-editor-state-methods.mdx index 2eb98fce..59e01166 100644 --- a/docs/rfds/client-editor-state-methods.mdx +++ b/docs/rfds/client-editor-state-methods.mdx @@ -173,6 +173,10 @@ Once this exists: ## Frequently asked questions +1. Why `workspace`? + +Was looking for something general enough that would work not only for IDEs. + ## Revision history - 2026-03-17: Initial draft. From 78870b3d8085a8517af4c6d7beef2b7516ffd96f Mon Sep 17 00:00:00 2001 From: "Anna.Zhdan" Date: Tue, 24 Mar 2026 09:17:56 +0100 Subject: [PATCH 4/4] add workspace methods rfd --- docs/rfds/client-editor-state-methods.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfds/client-editor-state-methods.mdx b/docs/rfds/client-editor-state-methods.mdx index 59e01166..ae0022b1 100644 --- a/docs/rfds/client-editor-state-methods.mdx +++ b/docs/rfds/client-editor-state-methods.mdx @@ -164,7 +164,7 @@ Returns the currently focused text editor file, or `null` when no file-backed te } ``` -## Shiny future +## Further development Once this exists: