feat(acp): prefix extension methods with _nanocoder/ and advertise them (#1909)

* feat(acp): prefix extension methods with _nanocoder/ and advertise them

ACP reserves the _ prefix for custom methods. Answer renameSession, timeline/list, timeline/revert and retryTurn as _nanocoder/<name>, keep the bare names as deprecated aliases that log a one-time notice, and list the exact method and notification names under agentCapabilities._meta.nanocoder. An unrecognised custom request now fails with Method not found (-32601). The VS Code extension uses the advertised names and falls back to the bare ones. Closes #1893

* fix(acp): share the notification name and prefix, and harden the new tests

Export the session title notification name and use it both where it is sent and in the advertised list, copy the advertised notification list like the method list, and have the VS Code client build the names it looks up from the shared prefix and method list instead of repeating the literals.

Tests: run the logger-patching deprecation test serially so the bare-name calls in other tests cannot land in its window, reuse makeHandshakenClient in the VS Code spec, and cover an agent that advertises only some of the extension methods.

Author: addyCooks

.changeset/acp-ext-method-names.md

@@ -0,0 +1,5 @@
+---
+"@nanocollective/nanocoder": minor
+---
+
+ACP extension requests now use the `_` prefix ACP reserves for custom methods: `_nanocoder/renameSession`, `_nanocoder/timeline/list`, `_nanocoder/timeline/revert` and `_nanocoder/retryTurn`. The bare names still work as deprecated aliases and log a one-time notice, and will be removed in a later release. `initialize` now lists the exact method and notification names under `agentCapabilities._meta.nanocoder`, so a client can detect support instead of guessing from the version. A custom request the agent doesn't recognise now fails with the standard "Method not found" (`-32601`) instead of a plain error. The VS Code extension uses the advertised names and falls back to the bare ones for an older agent.

docs/features/acp.md

@@ -35,9 +35,34 @@ With ACP the **client is the UI**: the agent runs headless and everything (strea
 - **`ask_user`** — when the agent asks a clarifying question, the options appear as selectable buttons in the editor. (Selection only; a free-form typed answer is not available over ACP.)
 - **`@`-mentioned files** — files you reference in the editor are read and included in the prompt, using the editor's live buffer (including unsaved edits) when available.
 - **Session persistence** - ACP sessions are saved to disk like TUI sessions (see [Session Management](session-management.md)). Loading or resuming a thread replays its history, even after the editor and agent restart. Loading or resuming a session ID that is neither in memory nor on disk fails with `Session not found on disk: <id>` instead of creating an empty session; only `session/new` creates one.
-- **Session management** - clients can list, resume, close and delete sessions. Nanocoder also answers a `renameSession` extension method (`sessionId`, `title`), and new sessions get a generated title from the first message.
+- **Session management** - clients can list, resume, close and delete sessions. Nanocoder also answers a `_nanocoder/renameSession` extension method (`sessionId`, `title`; see [Extension methods](#extension-methods)), and new sessions get a generated title from the first message.
 - **Images** - PNG, JPEG, GIF and WebP attachments are sent to the model as images.
 
+## Extension methods
+
+ACP reserves method names starting with `_` for custom methods. Nanocoder's are:
+
+| Method | Params | What it does |
+|--------|--------|--------------|
+| `_nanocoder/renameSession` | `sessionId`, `title` | Sets a session's title |
+| `_nanocoder/timeline/list` | `sessionId` | Lists the session's file-change checkpoints |
+| `_nanocoder/timeline/revert` | `sessionId`, `checkpointId` | Reverts the files and history to before a checkpoint |
+| `_nanocoder/retryTurn` | `sessionId`, optional `promptText` | Removes the last turn so the prompt can be sent again |
+
+The agent also sends the `_nanocoder/sessionTitleChanged` notification when it titles a session in the background.
+
+**Capability detection.** `initialize` lists the exact names under `agentCapabilities._meta.nanocoder`:
+
+```json
+{"nanocoder": {"extMethods": ["_nanocoder/renameSession", "..."], "extNotifications": ["_nanocoder/sessionTitleChanged"]}}
+```
+
+Take the names from that list as they are rather than building them from a prefix. An agent that doesn't list a method doesn't support it under that name.
+
+**Deprecated aliases.** The same methods are still answered under their old bare names (`renameSession`, `timeline/list`, `timeline/revert`, `retryTurn`) for clients that predate the prefix. The first use of each logs a deprecation notice. The aliases will be removed in a later release, announced in the changelog.
+
+**Unknown methods.** A custom request the agent doesn't recognise fails with the standard JSON-RPC "Method not found" error (`-32601`), so "not supported" can be told apart from "failed".
+
 ## Setup in Zed
 
 [Zed](https://zed.dev) is the reference ACP client. Register Nanocoder as a custom agent in Zed's `settings.json` (`Cmd+,`, or **zed: open settings** from the command palette):

plugins/vscode/src/acp-client.spec.ts

@@ -97,6 +97,7 @@ test('NanocoderAcpClient - newChat clears pending permissions', async (t) => {
 async function makeHandshakenClient(
 	agentCapabilities: unknown,
 	closeSession: (params: {sessionId: string}) => Promise<unknown>,
+	extMethod?: (method: string, params: unknown) => Promise<unknown>,
 ) {
 	const lines: string[] = [];
 	const client = new NanocoderAcpClient(
@@ -106,6 +107,7 @@ async function makeHandshakenClient(
 	client.setConnection({
 		initialize: async () => ({agentInfo: {version: '1.32.0'}, agentCapabilities}),
 		closeSession,
+		extMethod,
 	} as any);
 	await client.initializeHandshake();
 	(client as any)._sessionId = 'session-old';
@@ -453,3 +455,66 @@ test('NanocoderAcpClient - a creation still in flight does not overwrite a resum
 	t.is(await pending, 'session-resumed');
 	t.is((client as any)._sessionId, 'session-resumed');
 });
+
+function recordExtCalls() {
+	const calls: Array<{method: string; params: unknown}> = [];
+	const extMethod = async (method: string, params: unknown) => {
+		calls.push({method, params});
+		return {};
+	};
+	return {calls, extMethod};
+}
+
+async function renameAndRetry(agentCapabilities: unknown) {
+	const {calls, extMethod} = recordExtCalls();
+	const {client} = await makeHandshakenClient(
+		agentCapabilities,
+		async () => ({}),
+		extMethod,
+	);
+	await client.renameSession('session-old', 'New title');
+	await client.retryTurn('again');
+	return {client, calls};
+}
+
+test('NanocoderAcpClient - rename and retry use the extension names the agent advertises', async (t) => {
+	const {calls} = await renameAndRetry({
+		_meta: {
+			nanocoder: {
+				extMethods: ['_nanocoder/renameSession', '_nanocoder/retryTurn'],
+			},
+		},
+	});
+
+	t.deepEqual(
+		calls.map((call) => call.method),
+		['_nanocoder/renameSession', '_nanocoder/retryTurn'],
+	);
+	t.deepEqual(calls[0].params, {sessionId: 'session-old', title: 'New title'});
+});
+
+test('NanocoderAcpClient - rename and retry fall back to the bare names for an agent that advertises none', async (t) => {
+	for (const agentCapabilities of [
+		{},
+		{_meta: {nanocoder: {}}},
+		{_meta: {nanocoder: {extMethods: 'x'}}},
+	]) {
+		const {calls} = await renameAndRetry(agentCapabilities);
+
+		t.deepEqual(
+			calls.map((call) => call.method),
+			['renameSession', 'retryTurn'],
+		);
+	}
+});
+
+test('NanocoderAcpClient - each extension method resolves on its own against what the agent advertises', async (t) => {
+	const {calls} = await renameAndRetry({
+		_meta: {nanocoder: {extMethods: ['_nanocoder/renameSession']}},
+	});
+
+	t.deepEqual(
+		calls.map((call) => call.method),
+		['_nanocoder/renameSession', 'retryTurn'],
+	);
+});

plugins/vscode/src/acp-client.ts

@@ -1,5 +1,6 @@
 import * as vscode from 'vscode';
 import {ClientSideConnection} from '@agentclientprotocol/sdk';
+import {ACP_EXT_PREFIX, type ACP_EXT_METHODS} from '../../../source/acp/acp-capabilities';
 import {AcpStateManager, ACPStatus} from './acp-state';
 import {PromptAttempt} from './prompt-attempt';
 import { resolveExtensionCwd } from './workspace-utils';
@@ -55,6 +56,8 @@ export class NanocoderAcpClient {
 	private _handshakeComplete = false;
 	/** Whether the agent advertised `sessionCapabilities.close` at initialize. */
 	private _supportsSessionClose = false;
+	/** Extension request names the agent advertised at initialize. */
+	private _extMethods: readonly string[] = [];
 
 	get isHandshakeComplete(): boolean {
 		return this._handshakeComplete && this.connection != null;
@@ -119,6 +122,7 @@ export class NanocoderAcpClient {
 		this._clearPendingPermissions();
 		this._handshakeComplete = false;
 		this._supportsSessionClose = false;
+		this._extMethods = [];
 	}
 
 	/** Drop any in-flight session creation; see {@link _sessionGeneration}. */
@@ -208,6 +212,10 @@ export class NanocoderAcpClient {
 
 			this._supportsSessionClose =
 				initResult.agentCapabilities?.sessionCapabilities?.close != null;
+			const advertised = (initResult.agentCapabilities?._meta?.nanocoder as
+				| { extMethods?: unknown }
+				| undefined)?.extMethods;
+			this._extMethods = Array.isArray(advertised) ? advertised : [];
 
 			// Complete handshake
 			this._handshakeComplete = true;
@@ -507,10 +515,22 @@ export class NanocoderAcpClient {
 		}
 	}
 
+	/**
+	 * The advertised name when the agent lists it, else the bare name an agent
+	 * from before the `_nanocoder/` prefix understands.
+	 */
+	private extMethodName(method: (typeof ACP_EXT_METHODS)[number]): string {
+		const advertised = `${ACP_EXT_PREFIX}${method}`;
+		return this._extMethods.includes(advertised) ? advertised : method;
+	}
+
 	async renameSession(sessionId: string, title: string): Promise<void> {
 		if (!this.connection) return;
 		try {
-			await this.connection.extMethod('renameSession', {sessionId, title});
+			await this.connection.extMethod(
+				this.extMethodName('renameSession'),
+				{sessionId, title},
+			);
 		} catch (error) {
 			this.outputChannel.appendLine(`renameSession failed: ${error}`);
 			vscode.window.showErrorMessage(`Failed to rename session: ${error}`);
@@ -559,10 +579,13 @@ export class NanocoderAcpClient {
 			return;
 		}
 		try {
-			await this.connection.extMethod('retryTurn', {
-				sessionId: this._sessionId,
-				promptText,
-			});
+			await this.connection.extMethod(
+				this.extMethodName('retryTurn'),
+				{
+					sessionId: this._sessionId,
+					promptText,
+				},
+			);
 		} catch (error) {
 			this.outputChannel.appendLine(`retryTurn warning: ${error}`);
 		}

source/acp/acp-agent.spec.ts

@@ -19,6 +19,7 @@ import {
 } from '@/message-handler';
 import {convertToModelMessages} from '@/ai-sdk-client/converters/message-converter';
 import {sessionManager} from '@/session/session-manager';
+import {getLogger} from '@/utils/logging';
 import {SemanticMemoryManager} from '@/memory/semantic-memory-manager';
 import {readFileTool} from '@/tools/read-file';
 import type {Message} from '@/types/core';
@@ -1207,11 +1208,86 @@ test.serial(
 	},
 );
 
-test('AcpAgent.extMethod - throws for an unknown method', async t => {
+test('AcpAgent.extMethod - an unknown method is "Method not found"', async t => {
 	const {agent} = createAgent();
-	await t.throwsAsync(agent.extMethod('bogus', {}), {
-		message: 'Unknown extension method: bogus',
-	});
+	for (const method of ['bogus', '_nanocoder/bogus', '_other/renameSession']) {
+		const error = await t.throwsAsync(agent.extMethod(method, {}));
+		t.is((error as {code?: number}).code, -32601, method);
+		t.regex(error?.message ?? '', /Method not found/);
+	}
+});
+
+test('AcpAgent.extMethod - answers on the prefixed name and on the bare alias', async t => {
+	const {agent} = createAgent();
+	const session = await agent.newSession({cwd: '/tmp'});
+	try {
+		await agent.prompt({
+			sessionId: session.sessionId,
+			prompt: [{type: 'text', text: 'hello'}],
+		});
+		for (const name of ['timeline/list', 'retryTurn', 'renameSession']) {
+			const params =
+				name === 'renameSession'
+					? {sessionId: session.sessionId, title: 'Same title'}
+					: {sessionId: session.sessionId};
+			const prefixed = await agent.extMethod(`_nanocoder/${name}`, params);
+			const bare = await agent.extMethod(name, params);
+			t.deepEqual(prefixed, bare, name);
+		}
+		// The same input errors identically under both names.
+		await t.throwsAsync(
+			agent.extMethod('_nanocoder/timeline/revert', {sessionId: 1}),
+			{message: 'timeline/revert requires string sessionId and checkpointId'},
+		);
+		await t.throwsAsync(
+			agent.extMethod('timeline/revert', {sessionId: 1}),
+			{message: 'timeline/revert requires string sessionId and checkpointId'},
+		);
+	} finally {
+		await agent.deleteSession({sessionId: session.sessionId});
+	}
+});
+
+// Serial: it patches the process-wide logger, and every bare-name call in the
+// other tests would land in the patch window as a stray notice.
+test.serial('AcpAgent.extMethod - a bare name logs one deprecation notice, a prefixed name none', async t => {
+	const {agent} = createAgent();
+	const logger = getLogger();
+	const original = logger.warn;
+	const warnings: string[] = [];
+	logger.warn = ((message: string) => {
+		warnings.push(message);
+	}) as typeof logger.warn;
+	try {
+		const params = {sessionId: 'nope'};
+		await t.throwsAsync(agent.extMethod('_nanocoder/timeline/list', params));
+		t.deepEqual(warnings, []);
+
+		await t.throwsAsync(agent.extMethod('timeline/list', params));
+		await t.throwsAsync(agent.extMethod('timeline/list', params));
+		await t.throwsAsync(agent.extMethod('retryTurn', params));
+		t.is(warnings.length, 2);
+		t.regex(warnings[0], /"timeline\/list" is deprecated; use "_nanocoder\/timeline\/list"/);
+		t.regex(warnings[1], /"retryTurn" is deprecated/);
+	} finally {
+		logger.warn = original;
+	}
+});
+
+test('AcpAgent.initialize - advertises the extension methods, and each one is handled', async t => {
+	const {agent} = createAgent();
+	const {agentCapabilities} = await agent.initialize({protocolVersion: 1});
+	const advertised = agentCapabilities?._meta?.nanocoder as {
+		extMethods: string[];
+		extNotifications: string[];
+	};
+	t.deepEqual(advertised.extNotifications, ['_nanocoder/sessionTitleChanged']);
+	t.true(advertised.extMethods.length > 0);
+	for (const method of advertised.extMethods) {
+		// Bad params fail inside the handler; an unsupported name would be -32601.
+		const error = await t.throwsAsync(agent.extMethod(method, {}));
+		t.not((error as {code?: number}).code, -32601, method);
+	}
 });
 
 test('AcpAgent.extMethod - renameSession throws on non-string sessionId/title', async t => {

source/acp/acp-agent.ts

@@ -31,7 +31,11 @@ import type {
 	SetSessionModeRequest,
 	SetSessionModeResponse,
 } from '@agentclientprotocol/sdk';
+import {RequestError} from '@agentclientprotocol/sdk';
 import {
+	ACP_EXT_METHODS,
+	ACP_EXT_PREFIX,
+	ACP_SESSION_TITLE_NOTIFICATION,
 	acpModeToDevelopmentMode,
 	developmentModeToAcpMode,
 	getAgentCapabilities,
@@ -102,6 +106,8 @@ export class AcpAgent implements Agent {
 	private conn: AgentSideConnection;
 	private appVersion: string;
 	private clientCapabilities?: ClientCapabilities;
+	/** Bare extension method names already reported as deprecated. */
+	private warnedExtAliases = new Set<string>();
 
 	constructor(
 		initContext: AcpInitContext,
@@ -489,7 +495,7 @@ export class AcpAgent implements Agent {
 						// Lands after the turn went idle, so the client may already be
 						// gone; an unhandled rejection here would kill the agent.
 						void this.conn
-							.notify('_nanocoder/sessionTitleChanged', {
+							.notify(ACP_SESSION_TITLE_NOTIFICATION, {
 								sessionId: session.sessionId,
 								title,
 							})
@@ -710,11 +716,28 @@ export class AcpAgent implements Agent {
 	 * ACP's core methods don't include a way for the client to rename a
 	 * session (title is otherwise agent-driven, from the latest message).
 	 * `extMethod` is the protocol's sanctioned escape hatch for exactly this.
+	 *
+	 * Methods are named `_nanocoder/<name>`. The bare `<name>` still works as a
+	 * deprecated alias; anything else is "Method not found" so a client can
+	 * tell an unsupported method from a failed one.
 	 */
 	async extMethod(
-		method: string,
+		requested: string,
 		params: Record<string, unknown>,
 	): Promise<Record<string, unknown>> {
+		const method = requested.startsWith(ACP_EXT_PREFIX)
+			? requested.slice(ACP_EXT_PREFIX.length)
+			: requested;
+		if (!(ACP_EXT_METHODS as readonly string[]).includes(method)) {
+			throw RequestError.methodNotFound(requested);
+		}
+		if (method === requested && !this.warnedExtAliases.has(method)) {
+			this.warnedExtAliases.add(method);
+			logger.warn(
+				`ACP extMethod "${method}" is deprecated; use "${ACP_EXT_PREFIX}${method}"`,
+			);
+		}
+
 		if (method === 'renameSession') {
 			const sessionId = params.sessionId;
 			const title = params.title;
@@ -828,7 +851,7 @@ export class AcpAgent implements Agent {
 			return {ok: true, messagesCount: session.messages.length};
 		}
 
-		throw new Error(`Unknown extension method: ${method}`);
+		throw RequestError.methodNotFound(requested);
 	}
 
 	async unstable_listProviders(

source/acp/acp-capabilities.spec.ts

@@ -23,6 +23,17 @@ test('getAgentCapabilities - returns session capabilities with close', t => {
 			list: {},
 			resume: {},
 		},
+		_meta: {
+			nanocoder: {
+				extMethods: [
+					'_nanocoder/renameSession',
+					'_nanocoder/timeline/list',
+					'_nanocoder/timeline/revert',
+					'_nanocoder/retryTurn',
+				],
+				extNotifications: ['_nanocoder/sessionTitleChanged'],
+			},
+		},
 	});
 });