Add elicitation/create and elicitation/complete (unstable)

Implement ACP elicitation methods — agent-to-client structured user
input via forms (JSON Schema) or URLs (out-of-band OAuth-style).

Schema types (all @UnstableAcpApi): CreateElicitationRequest/Response,
CompleteElicitationNotification, ElicitationSchema with 5 property
variants (string, number, integer, boolean, multi-select),
EnumOption, ElicitationCapabilities on ClientCapabilities.

Agent side: createElicitation() and completeElicitation() on
AcpAsyncAgent, PromptContext, and SyncPromptContext with capability
check. Client side: createElicitationHandler() on both AsyncSpec
and SyncSpec builders.

Adds acp-annotations as dependency of acp-core (zero-dep module)
so @UnstableAcpApi can be used on protocol types directly.

Tests: 6 serialization tests (schema round-trip, property type
polymorphism, request/response variants, capabilities) and 1
end-to-end integration test (agent sends form elicitation to
client, client accepts with structured response).

Author: Mark Pollack

acp-core/pom.xml

@@ -17,6 +17,13 @@
     <description>Core ACP implementation with stdio transport - zero external dependencies beyond Reactor</description>
 
     <dependencies>
+        <!-- ACP annotations (@UnstableAcpApi, etc.) - zero-dependency module -->
+        <dependency>
+            <groupId>com.agentclientprotocol</groupId>
+            <artifactId>acp-annotations</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
         <!-- Reactor for async operations -->
         <dependency>
             <groupId>io.projectreactor</groupId>

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/AcpAsyncAgent.java

@@ -125,6 +125,20 @@ public interface AcpAsyncAgent {
 	 */
 	Mono<AcpSchema.KillTerminalCommandResponse> killTerminal(AcpSchema.KillTerminalCommandRequest request);
 
+	/**
+	 * Requests structured user input from the client via a form or URL.
+	 * @param request The elicitation request
+	 * @return A Mono containing the user's response
+	 */
+	Mono<AcpSchema.CreateElicitationResponse> createElicitation(AcpSchema.CreateElicitationRequest request);
+
+	/**
+	 * Notifies the client that a URL-mode elicitation has completed.
+	 * @param notification The completion notification
+	 * @return A Mono that completes when the notification is sent
+	 */
+	Mono<Void> completeElicitation(AcpSchema.CompleteElicitationNotification notification);
+
 	/**
 	 * Closes the agent gracefully, allowing pending operations to complete.
 	 * @return A Mono that completes when the agent is closed

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultAcpAsyncAgent.java

@@ -339,6 +339,29 @@ public Mono<AcpSchema.KillTerminalCommandResponse> killTerminal(AcpSchema.KillTe
 				});
 	}
 
+	@Override
+	public Mono<AcpSchema.CreateElicitationResponse> createElicitation(
+			AcpSchema.CreateElicitationRequest request) {
+		if (session == null) {
+			return Mono.error(new IllegalStateException("Agent not started"));
+		}
+		NegotiatedCapabilities caps = clientCapabilities.get();
+		if (caps != null && !caps.supportsElicitation()) {
+			return Mono.error(new AcpCapabilityException("elicitation"));
+		}
+		return session.sendRequest(AcpSchema.METHOD_ELICITATION_CREATE, request,
+				new TypeRef<AcpSchema.CreateElicitationResponse>() {
+				});
+	}
+
+	@Override
+	public Mono<Void> completeElicitation(AcpSchema.CompleteElicitationNotification notification) {
+		if (session == null) {
+			return Mono.error(new IllegalStateException("Agent not started"));
+		}
+		return session.sendNotification(AcpSchema.METHOD_ELICITATION_COMPLETE, notification);
+	}
+
 	@Override
 	public Mono<Void> closeGracefully() {
 		return Mono.defer(() -> {

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultPromptContext.java

@@ -106,6 +106,17 @@ public Mono<AcpSchema.KillTerminalCommandResponse> killTerminal(AcpSchema.KillTe
 		return agent.killTerminal(request);
 	}
 
+	@Override
+	public Mono<AcpSchema.CreateElicitationResponse> createElicitation(
+			AcpSchema.CreateElicitationRequest request) {
+		return agent.createElicitation(request);
+	}
+
+	@Override
+	public Mono<Void> completeElicitation(AcpSchema.CompleteElicitationNotification notification) {
+		return agent.completeElicitation(notification);
+	}
+
 	@Override
 	public NegotiatedCapabilities getClientCapabilities() {
 		return agent.getClientCapabilities();

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/DefaultSyncPromptContext.java

@@ -80,6 +80,17 @@ public AcpSchema.KillTerminalCommandResponse killTerminal(AcpSchema.KillTerminal
 		return asyncContext.killTerminal(request).block();
 	}
 
+	@Override
+	public AcpSchema.CreateElicitationResponse createElicitation(
+			AcpSchema.CreateElicitationRequest request) {
+		return asyncContext.createElicitation(request).block();
+	}
+
+	@Override
+	public void completeElicitation(AcpSchema.CompleteElicitationNotification notification) {
+		asyncContext.completeElicitation(notification).block();
+	}
+
 	@Override
 	public NegotiatedCapabilities getClientCapabilities() {
 		return asyncContext.getClientCapabilities();

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/PromptContext.java

@@ -136,6 +136,24 @@ public interface PromptContext {
 	 */
 	Mono<AcpSchema.KillTerminalCommandResponse> killTerminal(AcpSchema.KillTerminalCommandRequest request);
 
+	// ========================================================================
+	// Elicitation
+	// ========================================================================
+
+	/**
+	 * Requests structured user input from the client via a form or URL.
+	 * @param request The elicitation request
+	 * @return A Mono containing the user's response
+	 */
+	Mono<AcpSchema.CreateElicitationResponse> createElicitation(AcpSchema.CreateElicitationRequest request);
+
+	/**
+	 * Notifies the client that a URL-mode elicitation has completed.
+	 * @param notification The completion notification
+	 * @return A Mono that completes when the notification is sent
+	 */
+	Mono<Void> completeElicitation(AcpSchema.CompleteElicitationNotification notification);
+
 	// ========================================================================
 	// Client Capabilities
 	// ========================================================================

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/SyncPromptContext.java

@@ -133,6 +133,24 @@ public interface SyncPromptContext {
 	 */
 	AcpSchema.KillTerminalCommandResponse killTerminal(AcpSchema.KillTerminalCommandRequest request);
 
+	// ========================================================================
+	// Elicitation
+	// ========================================================================
+
+	/**
+	 * Requests structured user input from the client via a form or URL.
+	 * Blocks until the user responds.
+	 * @param request The elicitation request
+	 * @return The user's response
+	 */
+	AcpSchema.CreateElicitationResponse createElicitation(AcpSchema.CreateElicitationRequest request);
+
+	/**
+	 * Notifies the client that a URL-mode elicitation has completed.
+	 * @param notification The completion notification
+	 */
+	void completeElicitation(AcpSchema.CompleteElicitationNotification notification);
+
 	// ========================================================================
 	// Client Capabilities
 	// ========================================================================

acp-core/src/main/java/com/agentclientprotocol/sdk/capabilities/NegotiatedCapabilities.java

@@ -10,6 +10,7 @@
 import com.agentclientprotocol.sdk.spec.AcpSchema.FileSystemCapability;
 import com.agentclientprotocol.sdk.spec.AcpSchema.McpCapabilities;
 import com.agentclientprotocol.sdk.spec.AcpSchema.PromptCapabilities;
+import com.agentclientprotocol.sdk.spec.AcpSchema.ElicitationCapabilities;
 import com.agentclientprotocol.sdk.spec.AcpSchema.SessionCapabilities;
 
 /**
@@ -60,6 +61,13 @@ public final class NegotiatedCapabilities {
 
 	private final boolean terminal;
 
+	// Client elicitation capabilities
+	private final boolean elicitation;
+
+	private final boolean elicitationForm;
+
+	private final boolean elicitationUrl;
+
 	// Agent capabilities (what agent offers to client)
 	private final boolean loadSession;
 
@@ -83,6 +91,9 @@ private NegotiatedCapabilities(Builder builder) {
 		this.readTextFile = builder.readTextFile;
 		this.writeTextFile = builder.writeTextFile;
 		this.terminal = builder.terminal;
+		this.elicitation = builder.elicitation;
+		this.elicitationForm = builder.elicitationForm;
+		this.elicitationUrl = builder.elicitationUrl;
 		this.loadSession = builder.loadSession;
 		this.listSessions = builder.listSessions;
 		this.closeSession = builder.closeSession;
@@ -114,6 +125,13 @@ public static NegotiatedCapabilities fromClient(ClientCapabilities caps) {
 
 		builder.terminal(Boolean.TRUE.equals(caps.terminal()));
 
+		ElicitationCapabilities elicit = caps.elicitation();
+		if (elicit != null) {
+			builder.elicitation(true);
+			builder.elicitationForm(elicit.form() != null);
+			builder.elicitationUrl(elicit.url() != null);
+		}
+
 		return builder.build();
 	}
 
@@ -211,6 +229,40 @@ public void requireTerminal() {
 		}
 	}
 
+	/**
+	 * Returns true if the client supports elicitation (any mode).
+	 * @return true if elicitation capability was advertised
+	 */
+	public boolean supportsElicitation() {
+		return elicitation;
+	}
+
+	/**
+	 * Returns true if the client supports form-based elicitation.
+	 * @return true if elicitation.form capability was advertised
+	 */
+	public boolean supportsElicitationForm() {
+		return elicitationForm;
+	}
+
+	/**
+	 * Returns true if the client supports URL-based elicitation.
+	 * @return true if elicitation.url capability was advertised
+	 */
+	public boolean supportsElicitationUrl() {
+		return elicitationUrl;
+	}
+
+	/**
+	 * Requires elicitation capability, throwing if not supported.
+	 * @throws AcpCapabilityException if the client doesn't support elicitation
+	 */
+	public void requireElicitation() {
+		if (!elicitation) {
+			throw new AcpCapabilityException("elicitation");
+		}
+	}
+
 	// --------------------------
 	// Agent Capability Checks (for clients)
 	// --------------------------
@@ -350,7 +402,9 @@ public void requireAudioContent() {
 	@Override
 	public String toString() {
 		return "NegotiatedCapabilities{" + "readTextFile=" + readTextFile + ", writeTextFile=" + writeTextFile
-				+ ", terminal=" + terminal + ", loadSession=" + loadSession + ", listSessions=" + listSessions
+				+ ", terminal=" + terminal + ", elicitation=" + elicitation + ", elicitationForm="
+				+ elicitationForm + ", elicitationUrl=" + elicitationUrl + ", loadSession=" + loadSession
+				+ ", listSessions=" + listSessions
 				+ ", closeSession=" + closeSession + ", resumeSession=" + resumeSession + ", imageContent="
 				+ imageContent + ", audioContent=" + audioContent + ", embeddedContext=" + embeddedContext
 				+ ", mcpHttp=" + mcpHttp + ", mcpSse=" + mcpSse + '}';
@@ -367,6 +421,12 @@ public static class Builder {
 
 		private boolean terminal = false;
 
+		private boolean elicitation = false;
+
+		private boolean elicitationForm = false;
+
+		private boolean elicitationUrl = false;
+
 		private boolean loadSession = false;
 
 		private boolean listSessions = false;
@@ -400,6 +460,21 @@ public Builder terminal(boolean value) {
 			return this;
 		}
 
+		public Builder elicitation(boolean value) {
+			this.elicitation = value;
+			return this;
+		}
+
+		public Builder elicitationForm(boolean value) {
+			this.elicitationForm = value;
+			return this;
+		}
+
+		public Builder elicitationUrl(boolean value) {
+			this.elicitationUrl = value;
+			return this;
+		}
+
 		public Builder loadSession(boolean value) {
 			this.loadSession = value;
 			return this;

acp-core/src/main/java/com/agentclientprotocol/sdk/client/AcpClient.java

@@ -452,6 +452,26 @@ public AsyncSpec killTerminalHandler(
 			return this;
 		}
 
+		/**
+		 * Adds a typed handler for elicitation requests from the agent.
+		 * The agent uses elicitation to request structured user input via forms.
+		 *
+		 * @param handler The typed handler function that processes elicitation requests
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if handler is null
+		 */
+		public AsyncSpec createElicitationHandler(
+				Function<AcpSchema.CreateElicitationRequest, Mono<AcpSchema.CreateElicitationResponse>> handler) {
+			Assert.notNull(handler, "Create elicitation handler must not be null");
+			AcpClientSession.RequestHandler<AcpSchema.CreateElicitationResponse> rawHandler = params -> {
+				AcpSchema.CreateElicitationRequest request = transport.unmarshalFrom(params,
+						new TypeRef<AcpSchema.CreateElicitationRequest>() {});
+				return handler.apply(request);
+			};
+			this.requestHandlers.put(AcpSchema.METHOD_ELICITATION_CREATE, rawHandler);
+			return this;
+		}
+
 		/**
 		 * Adds a consumer to be notified when session update notifications are received
 		 * from the agent. Session updates include agent thoughts, message chunks, and
@@ -833,6 +853,27 @@ public SyncSpec killTerminalHandler(
 			return this;
 		}
 
+		/**
+		 * Adds a typed handler for elicitation requests from the agent.
+		 * The agent uses elicitation to request structured user input via forms.
+		 *
+		 * @param handler The typed handler function that processes elicitation requests
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if handler is null
+		 */
+		public SyncSpec createElicitationHandler(
+				Function<AcpSchema.CreateElicitationRequest, AcpSchema.CreateElicitationResponse> handler) {
+			Assert.notNull(handler, "Create elicitation handler must not be null");
+			SyncRequestHandler<AcpSchema.CreateElicitationResponse> rawHandler = params -> {
+				logger.debug("createElicitation request params: {}", params);
+				AcpSchema.CreateElicitationRequest request = transport.unmarshalFrom(params,
+						new TypeRef<AcpSchema.CreateElicitationRequest>() {});
+				return handler.apply(request);
+			};
+			this.requestHandlers.put(AcpSchema.METHOD_ELICITATION_CREATE, fromSync(rawHandler));
+			return this;
+		}
+
 		/**
 		 * Adds a synchronous consumer to be notified when session update notifications
 		 * are received from the agent. This is the preferred method for sync clients.