Null-mark the acp-test package

MockAcpAgent and MockAcpClient no longer construct themselves with a
null delegate and write the final field by reflection afterwards: each
constructor builds its delegate, whose handlers record into the mock's
already-initialized fields. MockAcpClient's session id is @nullable
until newSession, and its blocking calls go through one helper.

Author: Mark Pollack

acp-test/src/main/java/com/agentclientprotocol/sdk/test/MockAcpAgent.java

@@ -64,8 +64,31 @@ public class MockAcpAgent {
 
 	private final AtomicReference<CountDownLatch> promptLatch = new AtomicReference<>(new CountDownLatch(0));
 
-	private MockAcpAgent(AcpAsyncAgent delegate) {
-		this.delegate = delegate;
+	private MockAcpAgent(Builder builder) {
+		AcpSchema.InitializeResponse initializeResponse = builder.initializeResponse;
+		AcpSchema.NewSessionResponse newSessionResponse = builder.newSessionResponse;
+		Function<AcpSchema.PromptRequest, AcpSchema.PromptResponse> promptResponseProvider = builder.promptResponseProvider;
+		// The handlers record into this mock's fields, which are initialized before this body runs
+		this.delegate = AcpAgent.async(builder.transport)
+			.requestTimeout(builder.requestTimeout)
+			.initializeHandler(request -> {
+				receivedInitRequests.add(request);
+				return Mono.just(initializeResponse);
+			})
+			.newSessionHandler(request -> {
+				receivedNewSessionRequests.add(request);
+				return Mono.just(newSessionResponse);
+			})
+			.promptHandler((request, updater) -> {
+				receivedPrompts.add(request);
+				promptLatch.get().countDown();
+				return Mono.just(promptResponseProvider.apply(request));
+			})
+			.cancelHandler(notification -> {
+				receivedCancellations.add(notification);
+				return Mono.empty();
+			})
+			.build();
 	}
 
 	/**
@@ -242,40 +265,7 @@ public Builder requestTimeout(Duration timeout) {
 		 * @return The configured mock agent
 		 */
 		public MockAcpAgent build() {
-			MockAcpAgent mockAgent = new MockAcpAgent(null);
-
-			AcpAsyncAgent delegate = AcpAgent.async(transport)
-				.requestTimeout(requestTimeout)
-				.initializeHandler(request -> {
-					mockAgent.receivedInitRequests.add(request);
-					return Mono.just(initializeResponse);
-				})
-				.newSessionHandler(request -> {
-					mockAgent.receivedNewSessionRequests.add(request);
-					return Mono.just(newSessionResponse);
-				})
-				.promptHandler((request, updater) -> {
-					mockAgent.receivedPrompts.add(request);
-					mockAgent.promptLatch.get().countDown();
-					return Mono.just(promptResponseProvider.apply(request));
-				})
-				.cancelHandler(notification -> {
-					mockAgent.receivedCancellations.add(notification);
-					return Mono.empty();
-				})
-				.build();
-
-			// Replace the delegate using reflection (a bit ugly but avoids circular reference issues)
-			try {
-				var field = MockAcpAgent.class.getDeclaredField("delegate");
-				field.setAccessible(true);
-				field.set(mockAgent, delegate);
-			}
-			catch (Exception e) {
-				throw new RuntimeException("Failed to set delegate", e);
-			}
-
-			return mockAgent;
+			return new MockAcpAgent(this);
 		}
 
 	}

acp-test/src/main/java/com/agentclientprotocol/sdk/test/MockAcpClient.java

@@ -15,6 +15,7 @@
 import com.agentclientprotocol.sdk.client.AcpClient;
 import com.agentclientprotocol.sdk.spec.AcpClientTransport;
 import com.agentclientprotocol.sdk.spec.AcpSchema;
+import org.jspecify.annotations.Nullable;
 import reactor.core.publisher.Mono;
 
 /**
@@ -69,12 +70,36 @@ public class MockAcpClient {
 
 	private volatile CountDownLatch updateLatch = new CountDownLatch(0);
 
-	private volatile String currentSessionId;
-
-	private MockAcpClient(AcpAsyncClient delegate, AcpClientTransport transport, Duration timeout) {
-		this.delegate = delegate;
-		this.transport = transport;
-		this.timeout = timeout;
+	private volatile @Nullable String currentSessionId;
+
+	private MockAcpClient(Builder builder) {
+		this.transport = builder.transport;
+		this.timeout = builder.requestTimeout;
+		Function<AcpSchema.RequestPermissionRequest, AcpSchema.RequestPermissionResponse> permissionHandler = builder.permissionHandler;
+		Function<AcpSchema.ReadTextFileRequest, AcpSchema.ReadTextFileResponse> readFileHandler = builder.readFileHandler;
+		Function<AcpSchema.WriteTextFileRequest, AcpSchema.WriteTextFileResponse> writeFileHandler = builder.writeFileHandler;
+		// The handlers record into this mock's fields, which are initialized before this body runs
+		this.delegate = AcpClient.async(builder.transport)
+			.requestTimeout(builder.requestTimeout)
+			.sessionUpdateConsumer(notification -> {
+				receivedUpdates.add(notification);
+				updateLatch.countDown();
+				return Mono.empty();
+			})
+			// Using typed handlers (no manual unmarshalling needed)
+			.requestPermissionHandler((AcpSchema.RequestPermissionRequest request) -> {
+				receivedPermissionRequests.add(request);
+				return Mono.just(permissionHandler.apply(request));
+			})
+			.readTextFileHandler((AcpSchema.ReadTextFileRequest request) -> {
+				receivedFileReadRequests.add(request);
+				return Mono.just(readFileHandler.apply(request));
+			})
+			.writeTextFileHandler((AcpSchema.WriteTextFileRequest request) -> {
+				receivedFileWriteRequests.add(request);
+				return Mono.just(writeFileHandler.apply(request));
+			})
+			.build();
 	}
 
 	/**
@@ -104,7 +129,7 @@ public AcpSchema.InitializeResponse initialize() {
 		// Mock client advertises all capabilities by default
 		AcpSchema.FileSystemCapability fs = new AcpSchema.FileSystemCapability(true, true);
 		AcpSchema.ClientCapabilities caps = new AcpSchema.ClientCapabilities(fs, true);
-		return delegate.initialize(new AcpSchema.InitializeRequest(1, caps)).block(timeout);
+		return await(delegate.initialize(new AcpSchema.InitializeRequest(1, caps)));
 	}
 
 	/**
@@ -113,11 +138,9 @@ public AcpSchema.InitializeResponse initialize() {
 	 * @return The new session response
 	 */
 	public AcpSchema.NewSessionResponse newSession(String cwd) {
-		AcpSchema.NewSessionResponse response = delegate.newSession(new AcpSchema.NewSessionRequest(cwd, List.of()))
-			.block(timeout);
-		if (response != null) {
-			this.currentSessionId = response.sessionId();
-		}
+		AcpSchema.NewSessionResponse response = await(
+				delegate.newSession(new AcpSchema.NewSessionRequest(cwd, List.of())));
+		this.currentSessionId = response.sessionId();
 		return response;
 	}
 
@@ -127,12 +150,7 @@ public AcpSchema.NewSessionResponse newSession(String cwd) {
 	 * @return The prompt response
 	 */
 	public AcpSchema.PromptResponse prompt(String text) {
-		if (currentSessionId == null) {
-			throw new IllegalStateException("No session created. Call newSession() first.");
-		}
-		return delegate
-			.prompt(new AcpSchema.PromptRequest(currentSessionId, List.of(new AcpSchema.TextContent(text))))
-			.block(timeout);
+		return prompt(requireSessionId(), text);
 	}
 
 	/**
@@ -142,18 +160,31 @@ public AcpSchema.PromptResponse prompt(String text) {
 	 * @return The prompt response
 	 */
 	public AcpSchema.PromptResponse prompt(String sessionId, String text) {
-		return delegate.prompt(new AcpSchema.PromptRequest(sessionId, List.of(new AcpSchema.TextContent(text))))
-			.block(timeout);
+		return await(delegate.prompt(new AcpSchema.PromptRequest(sessionId, List.of(new AcpSchema.TextContent(text)))));
 	}
 
 	/**
 	 * Cancels operations for the current session.
 	 */
 	public void cancel() {
-		if (currentSessionId == null) {
+		delegate.cancel(new AcpSchema.CancelNotification(requireSessionId())).block(timeout);
+	}
+
+	private String requireSessionId() {
+		String sessionId = this.currentSessionId;
+		if (sessionId == null) {
 			throw new IllegalStateException("No session created. Call newSession() first.");
 		}
-		delegate.cancel(new AcpSchema.CancelNotification(currentSessionId)).block(timeout);
+		return sessionId;
+	}
+
+	/** Blocks for a response; a request's Mono emits its response or fails, never completes empty. */
+	private <T> T await(Mono<T> response) {
+		T value = response.block(timeout);
+		if (value == null) {
+			throw new IllegalStateException("ACP request completed without a response");
+		}
+		return value;
 	}
 
 	/**
@@ -210,7 +241,7 @@ public List<AcpSchema.WriteTextFileRequest> getReceivedFileWriteRequests() {
 	 * Gets the current session ID.
 	 * @return The session ID, or null if no session created
 	 */
-	public String getCurrentSessionId() {
+	public @Nullable String getCurrentSessionId() {
 		return currentSessionId;
 	}
 
@@ -325,42 +356,7 @@ public Builder requestTimeout(Duration timeout) {
 		 * @return The configured mock client
 		 */
 		public MockAcpClient build() {
-			// We need to create the mock first to capture updates
-			MockAcpClient mockClient = new MockAcpClient(null, transport, requestTimeout);
-
-			AcpAsyncClient delegate = AcpClient.async(transport)
-				.requestTimeout(requestTimeout)
-				.sessionUpdateConsumer(notification -> {
-					mockClient.receivedUpdates.add(notification);
-					mockClient.updateLatch.countDown();
-					return Mono.empty();
-				})
-				// Using typed handlers (no manual unmarshalling needed)
-				.requestPermissionHandler((AcpSchema.RequestPermissionRequest request) -> {
-					mockClient.receivedPermissionRequests.add(request);
-					return Mono.just(permissionHandler.apply(request));
-				})
-				.readTextFileHandler((AcpSchema.ReadTextFileRequest request) -> {
-					mockClient.receivedFileReadRequests.add(request);
-					return Mono.just(readFileHandler.apply(request));
-				})
-				.writeTextFileHandler((AcpSchema.WriteTextFileRequest request) -> {
-					mockClient.receivedFileWriteRequests.add(request);
-					return Mono.just(writeFileHandler.apply(request));
-				})
-				.build();
-
-			// Replace the delegate using reflection
-			try {
-				var field = MockAcpClient.class.getDeclaredField("delegate");
-				field.setAccessible(true);
-				field.set(mockClient, delegate);
-			}
-			catch (Exception e) {
-				throw new RuntimeException("Failed to set delegate", e);
-			}
-
-			return mockClient;
+			return new MockAcpClient(this);
 		}
 
 	}

acp-test/src/main/java/com/agentclientprotocol/sdk/test/package-info.java

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2025-2026 the original author or authors.
+ */
+
+/**
+ * Test support for ACP applications: an in-memory transport pair and mock agent and client.
+ *
+ * <p>
+ * The package is null-marked: every type is non-null unless annotated
+ * {@link org.jspecify.annotations.Nullable @Nullable}.
+ * </p>
+ */
+@NullMarked
+package com.agentclientprotocol.sdk.test;
+
+import org.jspecify.annotations.NullMarked;