Document what the SDK's logs can carry; guard Quarkus 16 MiB limits

The READMEs now say that a stdio agent's standard error is logged at
INFO, unfiltered, on the agent-stderr logger and how to silence it, and
that DEBUG and TRACE on com.agentclientprotocol.sdk log message
payloads, session updates included.

HttpTransportTest sends a 12 MB prompt over Streamable HTTP and
WebSocket on Quarkus, above Quarkus's 10 MB default body size: a
regression guard for the limits AcpHttpConfigBuilder raises.

Author: Mark Pollack

CHANGELOG.md

@@ -62,6 +62,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a failed `terminal/release` of a cancelled `execute`. Each now logs the error code and the SDK's
   name for it (`-32603 Internal error`); the peer's message and data are logged at DEBUG.
 
+- **Documented: what the SDK's logs can carry.** A stdio agent's standard error is logged at INFO,
+  unfiltered, on `com.agentclientprotocol.sdk.client.transport.agent-stderr`; silence it with that
+  logger's level or `setStdErrorHandler`. DEBUG and TRACE on `com.agentclientprotocol.sdk` log
+  message payloads, session updates included, and should not be enabled where logs are shipped.
+
 - **A handler's unexpected exception no longer sends its message to the peer.** A request handler
   that failed with an exception other than `AcpProtocolException` was answered `-32603` with the
   exception's message, which can carry paths, SQL, URLs with credentials or tokens. It is now

README.md

@@ -499,6 +499,20 @@ that authenticates in front. Browser requests whose `Origin` is not a loopback o
 | Streamable HTTP and WebSocket in your own Servlet 6 container | `StreamableHttpAcpClientTransport`, `WebSocketAcpClientTransport` | `StreamableHttpAcpServlet` (WebSocket where the container has Jakarta WebSocket 2.1) | acp-core / acp-http-servlet |
 | Streamable HTTP and WebSocket in a Spring WebFlux application | `StreamableHttpAcpClientTransport`, `WebSocketAcpClientTransport` | `AcpWebFluxHost` (a `RouterFunction`) | acp-core / acp-http-webflux |
 
+#### Logging and sensitive data
+
+Two of the SDK's loggers can carry message content or other sensitive data:
+
+- **The agent's standard error.** `StdioAcpClientTransport` logs every line the agent process
+  writes to standard error at INFO on the logger `com.agentclientprotocol.sdk.client.transport.agent-stderr`,
+  unfiltered. An agent's diagnostics can carry sensitive data (paths, prompts, account details).
+  Silence it by setting that logger's level to `WARN` or `OFF`, or route the lines yourself with
+  `setStdErrorHandler`.
+- **DEBUG and TRACE.** At DEBUG and TRACE, loggers under `com.agentclientprotocol.sdk` log message
+  payloads in full: the stdio client's sent and received lines, the sessions' messages, and the
+  session updates the framework integrations log by default. Do not enable them where logs are
+  shipped or retained.
+
 ---
 
 ## Building

acp-integration/README.md

@@ -110,7 +110,8 @@ AcpAgentDiscovery.requireSingle(candidates, "my.acp.agent.enabled").ifPresent(ag
 ## The client
 
 `AcpClients.async(transport, settings, customizers)` builds the one async client: capabilities,
-request and prompt timeouts, a session-update handler that logs at DEBUG, then the
+request and prompt timeouts, a session-update handler that logs each update at DEBUG, its content
+included, then the
 `AcpClientCustomizer`s in order. Building the client connects the transport (for stdio, it starts
 the agent process); a stdio command that cannot be started, or a transport already connected,
 fails the build. The ACP handshake waits for the application's `initialize()`.
@@ -119,6 +120,12 @@ fails the build. The ACP handshake waits for the application's `initialize()`.
 its timeout (`settings.closeTimeout()`); the framework must not close the client or its transport
 again through an inferred destroy method.
 
+Logging: DEBUG and TRACE on `com.agentclientprotocol.sdk` log message payloads in full, session
+updates included; do not enable them where logs are shipped. A stdio agent's standard error is
+logged at INFO, unfiltered, on `com.agentclientprotocol.sdk.client.transport.agent-stderr`, and can
+carry sensitive data: set that logger to `WARN` or `OFF`, or register a handler of your own with
+`StdioAcpClientTransport.setStdErrorHandler`.
+
 ## Not here
 
 The Mutiny `Uni` and `Multi` return types stay in `acp-quarkus`; the `CompletionStage` and

acp-micronaut/README.md

@@ -132,6 +132,12 @@ class Updates implements AcpClientCustomizer {
 }
 ```
 
+Without a session-update handler of your own, session updates are logged at DEBUG, content
+included. DEBUG and TRACE on `com.agentclientprotocol.sdk` log message payloads in full; do not
+enable them where logs are shipped. A stdio agent's standard error is logged at INFO, unfiltered,
+on `com.agentclientprotocol.sdk.client.transport.agent-stderr`, and can carry sensitive data: set
+that logger to `WARN` in `logback.xml` to silence it.
+
 | Property | Default | |
 |---|---|---|
 | `acp.client.request-timeout` | `60s` | |

acp-quarkus-deployment/src/test/java/com/agentclientprotocol/sdk/quarkus/deployment/HttpTransportTest.java

@@ -83,6 +83,17 @@ void oneMegabytePromptOverBothTransports() {
 		roundTrip(new WebSocketAcpClientTransport(webSocketUri(), AcpJsonMapper.createDefault()), true, big);
 	}
 
+	/**
+	 * The extension raises the Quarkus limits to the SDK's 16 MiB: a 12 MB prompt, above
+	 * Quarkus's 10 MB default body size, is accepted as a POST body and as a WebSocket message.
+	 */
+	@Test
+	void twelveMegabytePromptOverBothTransports() {
+		String big = "x".repeat(12 * 1024 * 1024);
+		roundTrip(new StreamableHttpAcpClientTransport(endpoint, AcpJsonMapper.createDefault()), true, big);
+		roundTrip(new WebSocketAcpClientTransport(webSocketUri(), AcpJsonMapper.createDefault()), true, big);
+	}
+
 	@Test
 	void connectionsLeftOpenAreCountedAndClosedAtShutdown() {
 		roundTrip(new StreamableHttpAcpClientTransport(endpoint, AcpJsonMapper.createDefault()), false);

acp-quarkus/README.md

@@ -136,6 +136,13 @@ type in every framework integration. The client beans are created when first inj
 your own of the same type replaces each. Client callbacks run on SDK threads, not on a Vert.x
 context: from a `Uni` built over a client call, hop back with `emitOn` when you need the context.
 
+Without a session-update handler of your own, session updates are logged at DEBUG, content
+included. DEBUG and TRACE on `com.agentclientprotocol.sdk` log message payloads in full; do not
+enable them where logs are shipped. A stdio agent's standard error is logged at INFO, unfiltered,
+on `com.agentclientprotocol.sdk.client.transport.agent-stderr`, and can carry sensitive data:
+`quarkus.log.category."com.agentclientprotocol.sdk.client.transport.agent-stderr".level=WARN`
+silences it.
+
 ## Configuration
 
 Build time (fixed when the application is built):

acp-spring-boot-autoconfigure/README.md

@@ -136,7 +136,11 @@ class Ask implements CommandLineRunner {
   type in the Micronaut and Quarkus integrations) are applied to the client's builder in bean order.
   Register the session-update handler, the permission handler, and the file system, terminal and
   elicitation handlers there. Without a session-update handler of your own, session updates are
-  logged at DEBUG.
+  logged at DEBUG, content included.
+- **Logging.** DEBUG and TRACE on `com.agentclientprotocol.sdk` log message payloads in full; do not
+  enable them where logs are shipped. A stdio agent's standard error is logged at INFO, unfiltered,
+  on `com.agentclientprotocol.sdk.client.transport.agent-stderr`, and can carry sensitive data:
+  set `logging.level.com.agentclientprotocol.sdk.client.transport.agent-stderr=WARN` to silence it.
 - **Capabilities.** The client advertises none by default. Turn one on with its
   `spring.acp.client.capabilities.*` property and register its handler in a customizer. A
   capability turned on without its handler fails the startup, naming the property.