Null-mark the spec package

AcpSchema's record components follow the ACP schema (v1, unstable
superset): 217 optional or nullable components are @nullable, required
ones stay non-null, and the convenience constructors that forward to
optional components take @nullable arguments. The JSON-RPC envelope's
id, params, result, error and data are @nullable.

Marking the sessions surfaced four wire bugs, each with a test:
- a request or notification that omits params (legal JSON-RPC) reached
  its handler as null; it now reads as an empty object;
- a request handler that completed empty sent no response at all; it is
  now answered with INTERNAL_ERROR;
- an exception without a message produced a JSON-RPC error without the
  required message; the exception's type name is used instead;
- a success response without a result failed with an opaque
  NullPointerException; it now fails saying so.

A terminal command killed by a signal has no exit code, and execute()
unboxed it into a NullPointerException. CommandResult now carries a
nullable exit code and the signal (with a test).

Author: Mark Pollack

acp-agent-support/README.md

@@ -171,7 +171,7 @@ PromptResponse handle(PromptRequest req, SyncPromptContext ctx) {
 
     // Execute terminal commands (requires client capabilities)
     CommandResult result = ctx.execute("ls", "-la");
-    if (result.exitCode() == 0) {
+    if (result.success()) {
         ctx.sendMessage("Output: " + result.output());
     }
 

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

@@ -4,6 +4,8 @@
 
 package com.agentclientprotocol.sdk.agent;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Result of executing a terminal command via the convenience API.
  *
@@ -16,15 +18,17 @@
  * Example usage:
  * <pre>{@code
  * CommandResult result = context.execute("make", "build");
- * if (result.exitCode() == 0) {
+ * if (result.success()) {
  *     context.sendMessage("Build succeeded!");
  * } else {
  *     context.sendMessage("Build failed: " + result.output());
  * }
  * }</pre>
  *
  * @param output The combined stdout/stderr output from the command
- * @param exitCode The exit code (0 typically means success)
+ * @param exitCode The exit code (0 typically means success), or null if the process was
+ * terminated by a signal
+ * @param signal The signal that terminated the process, or null if it exited normally
  * @param timedOut Whether the command was terminated due to timeout
  * @author Mark Pollack
  * @since 0.9.2
@@ -33,7 +37,8 @@
  */
 public record CommandResult(
 		String output,
-		int exitCode,
+		@Nullable Integer exitCode,
+		@Nullable String signal,
 		boolean timedOut
 ) {
 
@@ -44,15 +49,25 @@ public record CommandResult(
 	 * @param exitCode The exit code
 	 */
 	public CommandResult(String output, int exitCode) {
-		this(output, exitCode, false);
+		this(output, exitCode, null, false);
+	}
+
+	/**
+	 * Creates a CommandResult for a process that exited with the given code.
+	 * @param output The command output
+	 * @param exitCode The exit code
+	 * @param timedOut Whether the command was terminated due to timeout
+	 */
+	public CommandResult(String output, int exitCode, boolean timedOut) {
+		this(output, exitCode, null, timedOut);
 	}
 
 	/**
 	 * Returns true if the command completed successfully (exit code 0).
-	 * @return true if exit code is 0 and command did not time out
+	 * @return true if the process exited with code 0 and did not time out
 	 */
 	public boolean success() {
-		return exitCode == 0 && !timedOut;
+		return exitCode != null && exitCode == 0 && !timedOut;
 	}
 
 }

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

@@ -223,7 +223,8 @@ public Mono<CommandResult> execute(Command command) {
 
 				return waitForTerminalExit(new WaitForTerminalExitRequest(sessionId, terminalId))
 						.flatMap(exitResp -> getTerminalOutput(new TerminalOutputRequest(sessionId, terminalId))
-								.map(outputResp -> new CommandResult(outputResp.output(), exitResp.exitCode(), false)))
+								.map(outputResp -> new CommandResult(outputResp.output(), exitResp.exitCode(),
+										exitResp.signal(), false)))
 						// Release terminal after getting result, then return result
 						.flatMap(result -> releaseTerminal(releaseReq).thenReturn(result))
 						// On error, still release terminal before propagating error

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

@@ -702,9 +702,13 @@ private Mono<Void> processNewSessionResponse(AcpSchema.JSONRPCResponse response)
 			return emitInbound(response);
 		}
 
+		Object result = response.result();
+		if (result == null) {
+			return emitInbound(errorResponse(response.id(), "session/new response carried no result", null));
+		}
 		String sessionId;
 		try {
-			AcpSchema.NewSessionResponse sessionResponse = jsonMapper.convertValue(response.result(),
+			AcpSchema.NewSessionResponse sessionResponse = jsonMapper.convertValue(result,
 					new TypeRef<AcpSchema.NewSessionResponse>() {
 					});
 			sessionId = sessionResponse.sessionId();
@@ -721,7 +725,7 @@ private Mono<Void> processNewSessionResponse(AcpSchema.JSONRPCResponse response)
 					"Failed to open session SSE stream for session " + sessionId, error)));
 	}
 
-	private AcpSchema.JSONRPCResponse errorResponse(Object id, String message, @Nullable Throwable error) {
+	private AcpSchema.JSONRPCResponse errorResponse(@Nullable Object id, String message, @Nullable Throwable error) {
 		Object data = error == null ? null : error.getMessage();
 		return new AcpSchema.JSONRPCResponse(AcpSchema.JSONRPC_VERSION, id, null,
 				new AcpSchema.JSONRPCError(AcpErrorCodes.INTERNAL_ERROR, message, data));

acp-core/src/main/java/com/agentclientprotocol/sdk/spec/AcpAgentSession.java

@@ -19,6 +19,7 @@
 import com.agentclientprotocol.sdk.util.AcpSchedulers;
 import com.agentclientprotocol.sdk.util.Assert;
 import com.agentclientprotocol.sdk.json.TypeRef;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Mono;
@@ -94,12 +95,12 @@ public class AcpAgentSession implements AcpSession {
 	 * Set when the transport's {@code start()} fails (already started, port in use, ...).
 	 * Requests to the client are then failed immediately with the cause.
 	 */
-	private volatile Throwable startFailure;
+	private volatile @Nullable Throwable startFailure;
 
 	/**
 	 * Represents an active prompt session for single-turn enforcement.
 	 */
-	private record ActivePrompt(String sessionId, Object requestId) {
+	private record ActivePrompt(String sessionId, @Nullable Object requestId) {
 	}
 
 	/**
@@ -113,8 +114,9 @@ public interface RequestHandler<T> {
 
 		/**
 		 * Handles an incoming request with the given parameters.
-		 * @param params The request parameters
-		 * @return A Mono containing the response object
+		 * @param params The request parameters; an omitted params arrives as an empty
+		 * object
+		 * @return A Mono containing the response object; it must not complete empty
 		 */
 		Mono<T> handle(Object params);
 
@@ -129,7 +131,8 @@ public interface NotificationHandler {
 
 		/**
 		 * Handles an incoming notification with the given parameters.
-		 * @param params The notification parameters
+		 * @param params The notification parameters; an omitted params arrives as an empty
+		 * object
 		 * @return A Mono that completes when the notification is processed
 		 */
 		Mono<Void> handle(Object params);
@@ -185,7 +188,7 @@ private void dismissPendingResponses() {
 		dismissPendingResponses(null);
 	}
 
-	private void dismissPendingResponses(Throwable cause) {
+	private void dismissPendingResponses(@Nullable Throwable cause) {
 		this.pendingResponses.forEach((id, sink) -> {
 			logger.warn("Abruptly terminating exchange for request {}", id);
 			sink.error(new RuntimeException("ACP session with client terminated", cause));
@@ -231,7 +234,7 @@ else if (message instanceof AcpSchema.JSONRPCRequest request) {
 					errorCode = AcpErrorCodes.INTERNAL_ERROR;
 				}
 				var errorResponse = new AcpSchema.JSONRPCResponse(AcpSchema.JSONRPC_VERSION, request.id(), null,
-						new AcpSchema.JSONRPCError(errorCode, error.getMessage(), errorData));
+						new AcpSchema.JSONRPCError(errorCode, errorMessage(error), errorData));
 				return Mono.just(errorResponse);
 			}).map(response -> (AcpSchema.JSONRPCMessage) response);
 		}
@@ -285,14 +288,14 @@ private Mono<AcpSchema.JSONRPCResponse> handleIncomingRequest(AcpSchema.JSONRPCR
 				// ordered before publication on every path; doFinally covers cancellation.
 				// Mono.defer keeps a handler that throws synchronously from holding the lock
 				// forever: the throw becomes an error signal that passes through the release.
-				return Mono.defer(() -> handler.handle(request.params()))
+				return requireResult(Mono.defer(() -> handler.handle(paramsOrEmpty(request.params()))), request.method())
 					.map(result -> new AcpSchema.JSONRPCResponse(AcpSchema.JSONRPC_VERSION, request.id(), result, null))
 					.doOnNext(response -> releasePrompt(sessionId, newPrompt, "response"))
 					.doOnError(error -> releasePrompt(sessionId, newPrompt, "error"))
 					.doFinally(signal -> releasePrompt(sessionId, newPrompt, signal.toString()));
 			}
 
-			return Mono.defer(() -> handler.handle(request.params()))
+			return requireResult(Mono.defer(() -> handler.handle(paramsOrEmpty(request.params()))), request.method())
 				.map(result -> new AcpSchema.JSONRPCResponse(AcpSchema.JSONRPC_VERSION, request.id(), result, null));
 		});
 	}
@@ -313,7 +316,7 @@ private void releasePrompt(String sessionId, ActivePrompt prompt, String reason)
 	 * Extracts the sessionId from request parameters, which arrive as a {@code Map} from
 	 * the JSON transports and as the typed record from in-process transports.
 	 */
-	private String extractSessionId(Object params) {
+	private String extractSessionId(@Nullable Object params) {
 		if (params instanceof AcpSchema.PromptRequest promptRequest) {
 			return promptRequest.sessionId() != null ? promptRequest.sessionId() : "unknown";
 		}
@@ -327,7 +330,7 @@ private String extractSessionId(Object params) {
 		return "unknown";
 	}
 
-	record MethodNotFoundError(String method, String message, Object data) {
+	record MethodNotFoundError(String method, String message, @Nullable Object data) {
 	}
 
 	private MethodNotFoundError getMethodNotFoundError(String method) {
@@ -356,7 +359,7 @@ private Mono<Void> handleIncomingNotification(AcpSchema.JSONRPCNotification noti
 				logger.warn("No handler registered for notification method: {}", notification.method());
 				return Mono.empty();
 			}
-			return handler.handle(notification.params());
+			return handler.handle(paramsOrEmpty(notification.params()));
 		});
 	}
 
@@ -415,7 +418,14 @@ public <T> Mono<T> sendRequest(String method, Object requestParams, TypeRef<T> t
 					deliveredResponseSink.complete();
 				}
 				else {
-					deliveredResponseSink.next(this.transport.unmarshalFrom(jsonRpcResponse.result(), typeRef));
+					Object result = jsonRpcResponse.result();
+					if (result == null) {
+						deliveredResponseSink.error(new AcpProtocolException(AcpErrorCodes.INTERNAL_ERROR,
+								"The response to " + method + " carried no result"));
+					}
+					else {
+						deliveredResponseSink.next(this.transport.unmarshalFrom(result, typeRef));
+					}
 				}
 			}
 		});
@@ -429,7 +439,7 @@ public <T> Mono<T> sendRequest(String method, Object requestParams, TypeRef<T> t
 	 * @return a Mono that completes when the notification is sent
 	 */
 	@Override
-	public Mono<Void> sendNotification(String method, Object params) {
+	public Mono<Void> sendNotification(String method, @Nullable Object params) {
 		return Mono.defer(() -> {
 			Throwable failure = this.startFailure;
 			if (failure != null) {
@@ -469,7 +479,7 @@ public boolean hasActivePrompt(String sessionId) {
 	 * </p>
 	 * @return one active session ID or null if no prompt is active
 	 */
-	public String getActivePromptSessionId() {
+	public @Nullable String getActivePromptSessionId() {
 		return activePrompts.keySet().stream().findFirst().orElse(null);
 	}
 
@@ -503,6 +513,27 @@ public void close() {
 		transport.close();
 	}
 
+	/**
+	 * The params a handler receives. JSON-RPC lets a request or notification omit them;
+	 * an omitted params reads as an empty object, which is what a peer sending {@code {}}
+	 * would deliver, so handlers never see null.
+	 */
+	private static Object paramsOrEmpty(@Nullable Object params) {
+		return (params != null) ? params : Map.of();
+	}
+
+	/** JSON-RPC requires an error message; an exception without one is named by its type. */
+	private static String errorMessage(Throwable error) {
+		String message = error.getMessage();
+		return (message != null) ? message : error.getClass().getName();
+	}
+
+	/** A request always gets a response: a handler that completes empty is answered with an error. */
+	private static <T> Mono<T> requireResult(Mono<T> result, String method) {
+		return result.switchIfEmpty(Mono.error(() -> new AcpProtocolException(AcpErrorCodes.INTERNAL_ERROR,
+				"The " + method + " handler produced no response")));
+	}
+
 	/**
 	 * ACP-specific error wrapper for JSON-RPC errors.
 	 * Provides detailed error information including code, message, and data.
@@ -549,7 +580,7 @@ public int getCode() {
 			return error.code();
 		}
 
-		public Object getData() {
+		public @Nullable Object getData() {
 			return error.data();
 		}