Answer a prompt the handler does not: cancel grace period and maximum duration

Two limits on a session/prompt, configurable on the agent builders
(AcpAgent.async/sync and AcpAgentSupport) and as PromptTimeouts on the
AcpAgentSession constructor:

- cancelGracePeriod, default 60 s: if the handler has not answered that
  long after session/cancel, the session cancels the handler's
  subscription and answers stopReason cancelled itself, which ACP v1
  requires of a cancelled prompt and which ends the turn.
- maxPromptDuration, off by default: when a prompt runs that long, the
  session cancels the handler and answers JSON-RPC error -32800 (request
  cancelled, which ACP v1 Cancellation asks of an internally cancelled
  request such as an internal timeout), or cancelled when the prompt was
  already being cancelled.

Duration.ZERO turns either off; negative or null is rejected. The
forced answer takes the normal path: the turn is released just before
it is published, and it is queued behind every update the handler had
sent. The timers run on the shared timeout timer and deliver on its
delivery threads; no new threads.

PromptAnswer decides who answers in one atomic step, so the handler's
answer racing a timer gives exactly one response. PromptAnswerLincheckTest
model checks the handler, a cancel, the grace timer and the max timer
(at most one answer, turn released once answered) and a cancel racing
the deadlines' set-up (the grace period still starts, once); both fail
when the guard or the re-check is removed. The behaviour tests run on a
virtual clock and failed with the deadlines switched off; an end-to-end
test shows the forced answer arriving after the handler's update.

Author: Mark Pollack

CHANGELOG.md

@@ -13,6 +13,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   CVE-2026-91776, CVE-2026-91777 (both lines) and CVE-2026-19032, CVE-2026-68497, CVE-2026-83557 (Jackson 3).
   0.18.0 shipped with the affected versions; applications can override the versions now.
 
+### Added
+
+- **Prompt timeouts on the agent builders** (`AcpAgent.async(...)`, `AcpAgent.sync(...)` and
+  `AcpAgentSupport.builder()`), also as `PromptTimeouts` on the `AcpAgentSession` constructor:
+  - `cancelGracePeriod(Duration)`: how long a prompt handler has to answer after `session/cancel`
+    before the agent answers `cancelled` itself. Default 60 seconds (see Changed).
+  - `maxPromptDuration(Duration)`: how long a prompt may run at all. When it passes, the agent
+    cancels the handler and answers with JSON-RPC error `-32800` (request cancelled), message
+    `Prompt exceeded maxPromptDuration of <duration>` and data `{"maxPromptDuration": "<ISO-8601>"}`
+    (ACP v1, Cancellation: an internally cancelled request, an internal timeout included, answers
+    `-32800`); a prompt already being cancelled is answered `cancelled` instead. Default: none, as
+    a prompt turn can legitimately run for a long time.
+
+  `Duration.ZERO` turns either off; a negative or null duration is rejected. Either way the forced
+  answer leaves through the normal path: the turn ends just before it is published, it follows
+  every update the handler had already sent, and exactly one answer is sent when the handler
+  answers just as a timer fires (model checked with Lincheck, `PromptAnswerLincheckTest`). The
+  timers run on the SDK's shared timeout timer, with no new threads. A handler that keeps running
+  after its subscription is cancelled (a blocking sync handler is not interrupted) and sends more
+  updates sends them after the answer. `AcpErrorCodes.REQUEST_CANCELLED` (`-32800`) is new.
+
 ### Changed
 
 - **Behaviour change: `session/cancel` no longer ends the prompt turn; the cancelled prompt's
@@ -24,11 +45,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `session/prompt`". A prompt sent between the cancel and that answer is now rejected with
   `-32000` (`CONCURRENT_PROMPT`), like any prompt during an active turn. The turn ends when the
   answer is published (before it reaches the client, as for every prompt), when the handler fails
-  (a timeout the handler applies included), when the request is cancelled, or when the session
-  closes. The session sets no timeout of its own on an inbound prompt, so a handler that never
-  answers after a cancel keeps its session busy. Migration: clients send the next prompt after the
-  cancelled one has answered (the SDK client sends nothing on its own after `cancel`); agent
-  prompt handlers must answer a cancelled prompt.
+  (a timeout the handler applies included), when the request is cancelled, when the session
+  closes, or when the cancel grace period passes (below). Migration: clients send the next prompt
+  after the cancelled one has answered (the SDK client sends nothing on its own after `cancel`);
+  agent prompt handlers must answer a cancelled prompt.
+- **New default: a cancelled prompt is answered within 60 seconds.** If the prompt handler has not
+  answered 60 seconds after `session/cancel`, the agent cancels the handler's subscription and
+  answers the prompt with stop reason `cancelled` itself (the answer ACP v1 requires of a
+  cancelled prompt), which ends the turn. Before, a handler that never answered a cancelled prompt
+  kept its session busy for good. `cancelGracePeriod(Duration.ZERO)` restores that. The public
+  four-argument `AcpAgentSession` constructor uses the same default.
 - **Breaking (unstable providers API): the provider identifier is `providerId`, on the wire and in
   Java.** `ProviderInfo`, `SetProviderRequest` and `DisableProviderRequest` wrote and read `"id"`,
   but the unstable schema names the property `providerId`, so no spec-conforming peer could exchange

acp-agent-support/README.md

@@ -62,7 +62,7 @@ This module transitively includes `acp-annotations` and `acp-core`.
 | `@LoadSession` | `session/load` | Loads an existing session by ID. |
 | `@Prompt` | `session/prompt` | Handles user prompts within a session. |
 | `@SetSessionMode` | `session/set_mode` | Changes the operational mode of a session. |
-| `@Cancel` | `session/cancel` | Handles cancellation notifications (fire-and-forget). The cancel does not end the prompt turn: the cancelled `@Prompt` method still returns, with stop reason `cancelled`, and the session rejects a new prompt until it has. |
+| `@Cancel` | `session/cancel` | Handles cancellation notifications (fire-and-forget). The cancel does not end the prompt turn: the cancelled `@Prompt` method still returns, with stop reason `cancelled`, and the session rejects a new prompt until it has, or until the cancel grace period (default 60 s, `cancelGracePeriod`) passes and the agent answers `cancelled` itself. |
 
 ### Parameter Annotations
 

acp-agent-support/src/main/java/com/agentclientprotocol/sdk/agent/support/AcpAgentSupport.java

@@ -74,6 +74,7 @@
 import com.agentclientprotocol.sdk.spec.AcpSchema;
 import com.agentclientprotocol.sdk.spec.AcpSchema.InitializeResponse;
 import com.agentclientprotocol.sdk.spec.AcpSchema.NewSessionResponse;
+import com.agentclientprotocol.sdk.spec.PromptTimeouts;
 
 import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
@@ -135,7 +136,9 @@ private AcpAgentSupport(Builder builder, AcpAgentTransport transport) {
 
 		// Build the underlying sync agent
 		var agentBuilder = AcpAgent.sync(transport)
-				.requestTimeout(builder.requestTimeout);
+				.requestTimeout(builder.requestTimeout)
+				.cancelGracePeriod(builder.cancelGracePeriod)
+				.maxPromptDuration(builder.maxPromptDuration);
 
 		// Wire discovered handlers to the agent builder
 		wireHandlers(agentBuilder);
@@ -392,6 +395,10 @@ public static class Builder {
 
 		private Duration requestTimeout = Duration.ofSeconds(30);
 
+		private Duration cancelGracePeriod = PromptTimeouts.DEFAULT_CANCEL_GRACE_PERIOD;
+
+		private Duration maxPromptDuration = Duration.ZERO;
+
 		/**
 		 * Register an agent instance.
 		 * @param agentInstance the annotated agent instance
@@ -454,6 +461,31 @@ public Builder requestTimeout(Duration timeout) {
 			return this;
 		}
 
+		/**
+		 * Set how long a {@code @Prompt} method has to return after {@code session/cancel}
+		 * before the agent answers the prompt with stop reason {@code cancelled} itself. The
+		 * method's thread is not interrupted. Default 60 seconds; {@link Duration#ZERO} for
+		 * none. See {@code AcpAgent.SyncAgentBuilder#cancelGracePeriod}.
+		 * @param gracePeriod the grace period; zero for none, not negative
+		 * @return this builder
+		 */
+		public Builder cancelGracePeriod(Duration gracePeriod) {
+			this.cancelGracePeriod = gracePeriod;
+			return this;
+		}
+
+		/**
+		 * Set how long a prompt may run before the agent answers it with error
+		 * {@code -32800} (request cancelled). Default none ({@link Duration#ZERO}). See
+		 * {@code AcpAgent.SyncAgentBuilder#maxPromptDuration}.
+		 * @param maxDuration the maximum prompt duration; zero for none, not negative
+		 * @return this builder
+		 */
+		public Builder maxPromptDuration(Duration maxDuration) {
+			this.maxPromptDuration = maxDuration;
+			return this;
+		}
+
 		/**
 		 * Add an interceptor.
 		 * @param interceptor the interceptor

acp-annotations/src/main/java/com/agentclientprotocol/sdk/annotation/Cancel.java

@@ -21,7 +21,10 @@
  *
  * <p>The cancel does not end the prompt turn: the cancelled prompt handler should stop,
  * send any last updates, and return stop reason {@code cancelled}. Until it has returned
- * (or failed), the session rejects a new prompt (ACP v1, prompt turn, Cancellation).
+ * (or failed), the session rejects a new prompt (ACP v1, prompt turn, Cancellation). If it
+ * has not returned within the cancel grace period (60 seconds unless configured on the
+ * agent builder), the agent answers the prompt {@code cancelled} itself; the method's
+ * thread is not interrupted.
  *
  * <p>The method can have the following parameters (all optional):
  * <ul>

acp-core/pom.xml

@@ -221,6 +221,7 @@
                                 <param>com.agentclientprotocol.sdk.spec.OutboundMessages*</param>
                                 <param>com.agentclientprotocol.sdk.spec.PendingResponses*</param>
                                 <param>com.agentclientprotocol.sdk.spec.ActivePrompts*</param>
+                                <param>com.agentclientprotocol.sdk.spec.Prompt*</param>
                                 <param>com.agentclientprotocol.sdk.spec.InboundMessages*</param>
                                 <param>com.agentclientprotocol.sdk.spec.ResponseResults*</param>
                                 <param>com.agentclientprotocol.sdk.spec.AcpError*</param>

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

@@ -13,6 +13,7 @@
 import com.agentclientprotocol.sdk.json.TypeRef;
 import com.agentclientprotocol.sdk.spec.AcpAgentTransport;
 import com.agentclientprotocol.sdk.spec.AcpSchema;
+import com.agentclientprotocol.sdk.spec.PromptTimeouts;
 import com.agentclientprotocol.sdk.util.Assert;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -321,7 +322,9 @@ interface DisableProviderHandler {
 	 * A cancel does not end the prompt turn: stop the prompt's work, send any last
 	 * updates, and answer the prompt with stop reason {@code cancelled}. The session stays
 	 * busy, rejecting a new prompt, until that answer (or an error) is sent (ACP v1, prompt
-	 * turn, Cancellation).
+	 * turn, Cancellation). If the prompt handler has not answered within the cancel grace
+	 * period (60 seconds unless set with {@code cancelGracePeriod}), the agent cancels it
+	 * and answers {@code cancelled} itself.
 	 * </p>
 	 */
 	@FunctionalInterface
@@ -554,6 +557,8 @@ class AsyncAgentBuilder {
 
 		private Duration requestTimeout = DEFAULT_REQUEST_TIMEOUT;
 
+		private PromptTimeouts promptTimeouts = PromptTimeouts.DEFAULTS;
+
 		private final AgentHandlers handlers = new AgentHandlers();
 
 		AsyncAgentBuilder(AcpAgentTransport transport) {
@@ -572,6 +577,37 @@ public AsyncAgentBuilder requestTimeout(Duration timeout) {
 			return this;
 		}
 
+		/**
+		 * Sets how long a prompt handler has to answer after {@code session/cancel}. When it
+		 * passes, the agent cancels the handler and answers the prompt itself with stop
+		 * reason {@code cancelled}, as ACP requires of a cancelled prompt, which ends the
+		 * turn so the session accepts a new prompt. Updates the handler sent before that
+		 * answer reach the client first. Default: 60 seconds
+		 * ({@link PromptTimeouts#DEFAULT_CANCEL_GRACE_PERIOD}); {@link Duration#ZERO} turns
+		 * it off, and a handler that never answers then keeps its session busy.
+		 * @param gracePeriod the grace period; zero for none, not negative
+		 * @return This builder for chaining
+		 */
+		public AsyncAgentBuilder cancelGracePeriod(Duration gracePeriod) {
+			this.promptTimeouts = this.promptTimeouts.withCancelGracePeriod(gracePeriod);
+			return this;
+		}
+
+		/**
+		 * Sets how long a prompt may run. When it passes, the agent cancels the handler and
+		 * answers the prompt with JSON-RPC error {@code -32800} (request cancelled; ACP
+		 * answers an internally cancelled request, an internal timeout included, with this
+		 * code), or with stop reason {@code cancelled} if the client had cancelled the
+		 * prompt, and the turn ends. Default: none ({@link Duration#ZERO}), since a prompt
+		 * turn can legitimately run for a long time.
+		 * @param maxDuration the maximum prompt duration; zero for none, not negative
+		 * @return This builder for chaining
+		 */
+		public AsyncAgentBuilder maxPromptDuration(Duration maxDuration) {
+			this.promptTimeouts = this.promptTimeouts.withMaxPromptDuration(maxDuration);
+			return this;
+		}
+
 		/**
 		 * Sets the handler for initialize requests.
 		 * @param handler The initialize handler
@@ -757,7 +793,7 @@ private <T> AsyncAgentBuilder request(String method, TypeRef<T> requestType,
 		 * @return A new AcpAsyncAgent instance
 		 */
 		public AcpAsyncAgent build() {
-			return new DefaultAcpAsyncAgent(transport, requestTimeout, handlers);
+			return new DefaultAcpAsyncAgent(transport, requestTimeout, promptTimeouts, handlers);
 		}
 
 	}
@@ -801,6 +837,37 @@ public SyncAgentBuilder requestTimeout(Duration timeout) {
 			return this;
 		}
 
+		/**
+		 * Sets how long a prompt handler has to answer after {@code session/cancel}. When it
+		 * passes, the agent cancels the handler (a sync handler blocked on its thread is not interrupted; what it sends afterwards is its own) and answers the prompt itself with stop
+		 * reason {@code cancelled}, as ACP requires of a cancelled prompt, which ends the
+		 * turn so the session accepts a new prompt. Updates the handler sent before that
+		 * answer reach the client first. Default: 60 seconds
+		 * ({@link PromptTimeouts#DEFAULT_CANCEL_GRACE_PERIOD}); {@link Duration#ZERO} turns
+		 * it off, and a handler that never answers then keeps its session busy.
+		 * @param gracePeriod the grace period; zero for none, not negative
+		 * @return This builder for chaining
+		 */
+		public SyncAgentBuilder cancelGracePeriod(Duration gracePeriod) {
+			asyncBuilder.cancelGracePeriod(gracePeriod);
+			return this;
+		}
+
+		/**
+		 * Sets how long a prompt may run. When it passes, the agent cancels the handler and
+		 * answers the prompt with JSON-RPC error {@code -32800} (request cancelled; ACP
+		 * answers an internally cancelled request, an internal timeout included, with this
+		 * code), or with stop reason {@code cancelled} if the client had cancelled the
+		 * prompt, and the turn ends. Default: none ({@link Duration#ZERO}), since a prompt
+		 * turn can legitimately run for a long time.
+		 * @param maxDuration the maximum prompt duration; zero for none, not negative
+		 * @return This builder for chaining
+		 */
+		public SyncAgentBuilder maxPromptDuration(Duration maxDuration) {
+			asyncBuilder.maxPromptDuration(maxDuration);
+			return this;
+		}
+
 		/**
 		 * Sets the synchronous handler for initialize requests.
 		 * @param handler The sync initialize handler (returns plain value)

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

@@ -16,6 +16,7 @@
 import com.agentclientprotocol.sdk.spec.AcpAgentSession;
 import com.agentclientprotocol.sdk.spec.AcpAgentTransport;
 import com.agentclientprotocol.sdk.spec.AcpSchema;
+import com.agentclientprotocol.sdk.spec.PromptTimeouts;
 import com.agentclientprotocol.sdk.json.TypeRef;
 import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
@@ -42,6 +43,8 @@ class DefaultAcpAsyncAgent implements AcpAsyncAgent {
 
 	private final Duration requestTimeout;
 
+	private final PromptTimeouts promptTimeouts;
+
 	private final List<AgentHandlers.Request<?>> requestHandlers;
 
 	private final List<AgentHandlers.Notification<?>> notificationHandlers;
@@ -57,9 +60,11 @@ class DefaultAcpAsyncAgent implements AcpAsyncAgent {
 	 */
 	private final AtomicReference<@Nullable NegotiatedCapabilities> clientCapabilities = new AtomicReference<>();
 
-	DefaultAcpAsyncAgent(AcpAgentTransport transport, Duration requestTimeout, AgentHandlers handlers) {
+	DefaultAcpAsyncAgent(AcpAgentTransport transport, Duration requestTimeout, PromptTimeouts promptTimeouts,
+			AgentHandlers handlers) {
 		this.transport = transport;
 		this.requestTimeout = requestTimeout;
+		this.promptTimeouts = promptTimeouts;
 		this.requestHandlers = handlers.requests();
 		this.notificationHandlers = handlers.notifications();
 	}
@@ -76,7 +81,7 @@ public Mono<Void> start() {
 			for (AgentHandlers.Notification<?> registration : notificationHandlers) {
 				notifications.put(registration.method(), sessionHandler(registration));
 			}
-			this.session = new AcpAgentSession(requestTimeout, transport, requests, notifications);
+			this.session = new AcpAgentSession(requestTimeout, transport, requests, notifications, promptTimeouts);
 			logger.info("ACP async agent started");
 		});
 	}

acp-core/src/main/java/com/agentclientprotocol/sdk/error/AcpErrorCodes.java

@@ -56,6 +56,13 @@ private AcpErrorCodes() {
 	 */
 	public static final int INTERNAL_ERROR = -32603;
 
+	/**
+	 * Request cancelled: execution of the method was aborted, because the caller cancelled
+	 * the request or because of resource constraints or shutdown. ACP answers an internally
+	 * cancelled request (an internal timeout, for one) with this code too.
+	 */
+	public static final int REQUEST_CANCELLED = -32800;
+
 	// --------------------------
 	// ACP-Specific Errors
 	// --------------------------
@@ -94,6 +101,7 @@ private AcpErrorCodes() {
 	private static final Map<Integer, String> DESCRIPTIONS = Map.ofEntries(Map.entry(PARSE_ERROR, "Parse error"),
 			Map.entry(INVALID_REQUEST, "Invalid request"), Map.entry(METHOD_NOT_FOUND, "Method not found"),
 			Map.entry(INVALID_PARAMS, "Invalid params"), Map.entry(INTERNAL_ERROR, "Internal error"),
+			Map.entry(REQUEST_CANCELLED, "Request cancelled"),
 			Map.entry(CONCURRENT_PROMPT, "Concurrent prompt"),
 			Map.entry(CAPABILITY_NOT_SUPPORTED, "Capability not supported"),
 			Map.entry(SESSION_NOT_FOUND, "Session not found"), Map.entry(NOT_INITIALIZED, "Not initialized"),