diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fc3a86e2..a1196526 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,12 +16,13 @@ concurrency: jobs: build: runs-on: ubuntu-latest + timeout-minutes: 30 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 - name: Set up JDK 17 - uses: actions/setup-java@v4 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4 with: java-version: '17' distribution: 'temurin' @@ -32,7 +33,7 @@ jobs: - name: Upload test results if: always() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 with: name: test-results path: '**/target/surefire-reports/' diff --git a/.github/workflows/publish-snapshot.yml b/.github/workflows/publish-snapshot.yml index 2b293be4..7213fe5e 100644 --- a/.github/workflows/publish-snapshot.yml +++ b/.github/workflows/publish-snapshot.yml @@ -21,12 +21,13 @@ concurrency: jobs: publish: runs-on: ubuntu-latest + timeout-minutes: 30 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 - name: Set up JDK 17 - uses: actions/setup-java@v4 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4 with: java-version: '17' distribution: 'temurin' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 337870b3..e1980596 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,14 +23,15 @@ permissions: jobs: release: runs-on: ubuntu-latest + timeout-minutes: 30 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: token: ${{ secrets.GITHUB_TOKEN }} - name: Set up JDK 17 - uses: actions/setup-java@v4 + uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4 with: java-version: '17' distribution: 'temurin' @@ -75,7 +76,7 @@ jobs: git push origin v${{ inputs.version }} - name: Create GitHub Release - uses: softprops/action-gh-release@v2 + uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2 with: tag_name: v${{ inputs.version }} name: Release ${{ inputs.version }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d063a6b..6f46698a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.15.0] - 2026-08-21 + +Correctness and supply-chain hygiene. No protocol or public API changes: the ACP surface is +identical to 0.14.0, so this is a drop-in upgrade. + +### Fixed + +- **Notification ordering.** Incoming notifications were dispatched as independent + fire-and-forget subscriptions, so a handler doing any async work could observe them out of + order — visible with agents that stream many rapid `session/update` chunks. They are now + serialized through a sink drained by `concatMap`, preserving arrival order. Reported and + fixed by @ljiro (#13, closes #11). +- **Notifications lost on graceful close.** Following from the above, `closeGracefully()` + completed the notification sink and disposed the drain subscription in the same synchronous + block, discarding anything still queued. Because `AcpClient.SyncSpec` wraps every sync + `sessionUpdateConsumer` with `subscribeOn(SYNC_HANDLER_SCHEDULER)`, sync clients always have + async handlers, so a rapid burst could be lost entirely on close. `closeGracefully()` now + waits for the drain to terminate before tearing the session down, bounded by the session's + `requestTimeout` so a handler that never completes cannot hang shutdown. `close()` still + interrupts immediately — the two methods now differ, as their names imply. +- Notifications arriving after shutdown has begun are still dropped — a graceful shutdown stops + accepting new work while draining what is queued, and JSON-RPC notifications carry no delivery + guarantee — but the log severity now distinguishes that expected case (DEBUG) from overflow, + zero-subscriber and non-serialized emission, which lose traffic on a live session (ERROR). + +### Security + +- Jackson 2.21.2 → **2.21.5** and Jetty 12.0.14 → **12.0.37**, clearing 17 known advisories + (5 high severity) reported against the published dependency closure. Both reach consumers as + compile-scope transitives of `acp-core` and `acp-websocket-jetty`. + +### Changed + +- **`LICENSE` is now the verbatim Apache License 2.0.** The previous file was a paraphrase: it + omitted section 6 (Trademarks) entirely, renumbered the sections that follow, rewrote the + section 2 copyright grant, and narrowed the `Licensor` and `Work` definitions. Automated + license detection classified the repository as `NOASSERTION` while every published POM + declared Apache-2.0. +- `LICENSE` and a new `NOTICE` are now packaged under `META-INF` in every module artifact. +- Removed a redundant `` declaration from the published parent POM; consumers no + longer inherit a repository definition with snapshots enabled. + +### Build + +- Integration tests now execute. Three `*IT` classes existed, but Surefire's default includes do + not match `*IT` and no Failsafe plugin was configured, so `mvn verify` silently skipped them. +- All GitHub Actions are pinned to commit SHAs. +- `HandlerExceptionTest` no longer races the async dispatch with a fixed sleep. + ## [0.14.0] - 2026-06-11 Protocol currency: catching up to ACP spec v0.13.6 (June 2026). Supersedes the never-published @@ -126,3 +175,4 @@ Protocol currency: catching up to ACP spec v0.13.6 (June 2026). Supersedes the n - SLF4J 2.0.16 [0.9.0]: https://github.com/agentclientprotocol/java-sdk/releases/tag/v0.9.0 +[0.15.0]: https://github.com/agentclientprotocol/java-sdk/releases/tag/v0.15.0 diff --git a/LICENSE b/LICENSE index 025ae288..d6456956 100644 --- a/LICENSE +++ b/LICENSE @@ -1,185 +1,202 @@ -Apache License -Version 2.0, January 2004 -http://www.apache.org/licenses/ - -TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - -1. Definitions. - -"License" shall mean the terms and conditions for use, reproduction, -and distribution as defined by Sections 1 through 9 of this document. - -"Licensor" shall mean the copyright owner or entity granting the License. - -"Legal Entity" shall mean the union of the acting entity and all -other entities that control, are controlled by, or are under common -control with that entity. For the purposes of this definition, -"control" means (i) the power, direct or indirect, to cause the -direction or management of such entity, whether by contract or -otherwise, or (ii) ownership of fifty percent (50%) or more of the -outstanding shares, or (iii) beneficial ownership of such entity. - -"You" (or "Your") shall mean an individual or Legal Entity -exercising permissions granted by this License. - -"Source" form shall mean the preferred form for making modifications, -including but not limited to software source code, documentation -source, and configuration files. - -"Object" form shall mean any form resulting from mechanical -transformation or translation of a Source form, including but -not limited to compiled object code, generated documentation, -and conversions to other media types. - -"Work" shall mean the work of authorship, whether in Source or -Object form, made available under the License, as indicated by a -copyright notice that is included in or attached to the work -(which shall not include notices that do not pertain to any part of -the Work). - -"Derivative Works" shall mean any work, whether in Source or Object -form, that is based upon (or derived from) the Work and for which the -editorial revisions, annotations, elaborations, or other modifications -represent, as a whole, an original work of authorship. For the purposes -of this License, Derivative Works shall not include works that remain -separable from, or merely link (or bind by name) to the interfaces of, -the Work and derivative works thereof. - -"Contribution" shall mean any work of authorship, including -the original version of the Work and any modifications or additions -to that Work or Derivative Works thereof, that is intentionally -submitted to Licensor for inclusion in the Work by the copyright owner -or by an individual or Legal Entity authorized to submit on behalf of -the copyright owner. For the purposes of this definition, "submitted" -means any form of electronic, verbal, or written communication sent -to the Licensor or its representatives, including but not limited to -communication on electronic mailing lists, source code control -systems, and issue tracking systems that are managed by, or on behalf -of, the Licensor for the purpose of discussing and improving the Work, -but excluding communication that is conspicuously marked or otherwise -designated in writing by the copyright owner as "Not a Contribution." - -"Contributor" shall mean Licensor and any individual or Legal Entity -on behalf of whom a Contribution has been received by Licensor and -subsequently incorporated within the Work. - -2. Grant of Copyright License. Subject to the terms and conditions of -this License, each Contributor hereby grants to You a perpetual, -worldwide, non-exclusive, no-charge, royalty-free, irrevocable -copyright license to use, reproduce, modify, distribute, and perform -the Work and prepare Derivative Works based upon the Work, and to -sublicense the foregoing rights to third parties, subject to the -conditions stated in this Section 2. - -3. Grant of Patent License. Subject to the terms and conditions of -this License, each Contributor hereby grants to You a perpetual, -worldwide, non-exclusive, no-charge, royalty-free, irrevocable -(except as stated in this section) patent license to make, have made, -use, offer to sell, sell, import, and otherwise transfer the Work, -where such license applies only to those patent claims licensable -by such Contributor that are necessarily infringed by their -Contribution(s) alone or by combination of their Contribution(s) -with the Work to which such Contribution(s) was submitted. If You -institute patent litigation against any entity (including a -cross-claim or counterclaim in a lawsuit) alleging that the Work -or a Contribution incorporated within the Work constitutes direct -or contributory patent infringement, then any patent licenses -granted to You under this License for that Work shall terminate -as of the date such litigation is filed. - -4. Redistribution. You may reproduce and distribute copies of the -Work or Derivative Works thereof in any medium, with or without -modifications, and in Source or Object form, provided that You -meet the following conditions: - -(a) You must give any other recipients of the Work or -Derivative Works a copy of this License; and - -(b) You must cause any modified files to carry prominent notices -stating that You changed the files; and - -(c) You must retain, in the Source form of any Derivative Works -that You distribute, all copyright, trademark, patent, and -attribution notices from the Source form of the Work, -excluding those notices that do not pertain to any part of -the Derivative Works; and - -(d) If the Work includes a "NOTICE" text file as part of its -distribution, then any Derivative Works that You distribute must -include a readable copy of the attribution notices contained -within such NOTICE file, excluding those notices that do not -pertain to any part of the Derivative Works, in at least one -of the following places: within a NOTICE text file distributed -as part of the Derivative Works; within the Source form or -documentation, if provided along with the Derivative Works; or, -within a display generated by the Derivative Works, if and -wherever such third-party notices normally appear. The contents -of the NOTICE file are for informational purposes only and -do not modify the License. You may add Your own attribution -notices within Derivative Works that You distribute, alongside -or as an addendum to the NOTICE text from the Work, provided -that such additional attribution notices cannot be construed -as modifying the License. - -You may add Your own copyright notice to Your modifications and -may provide additional or different license terms and conditions -for use, reproduction, or distribution of Your modifications, or -for any such Derivative Works as a whole, provided Your use, -reproduction, and distribution of the Work otherwise complies with -the conditions stated in this License. - -5. Submission of Contributions. Unless You explicitly state otherwise, -any Contribution intentionally submitted for inclusion in the Work -by You to the Licensor shall be under the terms and conditions of -this License, without any additional terms or conditions. -Notwithstanding the above, nothing herein shall supersede or modify -the terms of any separate license agreement you may have executed -with Licensor regarding such Contributions. - -6. Disclaimer of Warranty. Unless required by applicable law or -agreed to in writing, Licensor provides the Work (and each -Contributor provides its Contributions) on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -implied, including, without limitation, any warranties or conditions -of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A -PARTICULAR PURPOSE. You are solely responsible for determining the -appropriateness of using or redistributing the Work and assume any -risks associated with Your exercise of permissions under this License. - -7. Limitation of Liability. In no event and under no legal theory, -whether in tort (including negligence), contract, or otherwise, -unless required by applicable law (such as deliberate and grossly -negligent acts) or agreed to in writing, shall any Contributor be -liable to You for damages, including any direct, indirect, special, -incidental, or consequential damages of any character arising as a -result of this License or out of the use or inability to use the -Work (including but not limited to damages for loss of goodwill, -work stoppage, computer failure or malfunction, or any and all -other commercial damages or losses), even if such Contributor -has been advised of the possibility of such damages. - -8. Accepting Warranty or Support. When redistributing the Work or -Derivative Works thereof, You may choose to offer, and charge a fee -for, warranty, support, indemnity, or other liability obligations -and/or rights consistent with this License. However, in accepting -such obligations, You may act only on Your own behalf and on Your -sole responsibility, not on behalf of any other Contributor, and only -if You agree to indemnify, defend, and hold each Contributor harmless -for any liability incurred by, or claims asserted against, such -Contributor by reason of your accepting any such warranty or support. - -END OF TERMS AND CONDITIONS - -Copyright 2024 Spring AI Community - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. \ No newline at end of file + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/NOTICE b/NOTICE new file mode 100644 index 00000000..fa72a808 --- /dev/null +++ b/NOTICE @@ -0,0 +1,8 @@ +ACP Java SDK +Copyright 2025-2026 the original author or authors. + +This product is licensed under the Apache License, Version 2.0. +A copy of the license is included in the LICENSE file distributed +with this software, and is also available at: + + https://www.apache.org/licenses/LICENSE-2.0 diff --git a/README.md b/README.md index a64378e9..3b4d0846 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # ACP Java SDK -> **Documentation**: https://springaicommunity.mintlify.app/acp-java-sdk | [API Reference](https://springaicommunity.mintlify.app/acp-java-sdk/reference/java) | [Tutorial](https://springaicommunity.mintlify.app/acp-java-sdk/tutorial) +> **Documentation**: https://lab.pollack.ai/docs/acp-java-sdk | [API Reference](https://lab.pollack.ai/docs/acp-java-sdk/reference/java) | [Tutorial](https://lab.pollack.ai/docs/acp-java-sdk/tutorial) Pure Java implementation of the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) specification for building both clients and agents. diff --git a/acp-agent-support/pom.xml b/acp-agent-support/pom.xml index 70ad1acf..13ad243d 100644 --- a/acp-agent-support/pom.xml +++ b/acp-agent-support/pom.xml @@ -7,7 +7,7 @@ com.agentclientprotocol acp-java-sdk - 0.13.0 + 0.15.0-SNAPSHOT acp-agent-support diff --git a/acp-annotations/README.md b/acp-annotations/README.md index 971e61ec..015ceeda 100644 --- a/acp-annotations/README.md +++ b/acp-annotations/README.md @@ -28,5 +28,5 @@ Zero-dependency annotation library for declarative ACP agent development. Use wi ## Documentation -- [Annotation-based Agent API](https://springaicommunity.mintlify.app/acp-java-sdk/reference/java#annotation-based-api) -- [Tutorial](https://springaicommunity.mintlify.app/acp-java-sdk/tutorial) +- [Annotation-based Agent API](https://lab.pollack.ai/docs/acp-java-sdk/reference/java#annotation-based-api) +- [Tutorial](https://lab.pollack.ai/docs/acp-java-sdk/tutorial) diff --git a/acp-annotations/pom.xml b/acp-annotations/pom.xml index 6e90d49f..ab731c5d 100644 --- a/acp-annotations/pom.xml +++ b/acp-annotations/pom.xml @@ -7,7 +7,7 @@ com.agentclientprotocol acp-java-sdk - 0.13.0 + 0.15.0-SNAPSHOT acp-annotations diff --git a/acp-core/README.md b/acp-core/README.md index 4a592293..d0ff0705 100644 --- a/acp-core/README.md +++ b/acp-core/README.md @@ -24,5 +24,5 @@ Core implementation of the Agent Client Protocol for Java. Provides client and a ## Documentation -- [API Reference](https://springaicommunity.mintlify.app/acp-java-sdk/reference/java) -- [Tutorial](https://springaicommunity.mintlify.app/acp-java-sdk/tutorial) +- [API Reference](https://lab.pollack.ai/docs/acp-java-sdk/reference/java) +- [Tutorial](https://lab.pollack.ai/docs/acp-java-sdk/tutorial) diff --git a/acp-core/pom.xml b/acp-core/pom.xml index 0b83f44f..297dc182 100644 --- a/acp-core/pom.xml +++ b/acp-core/pom.xml @@ -7,7 +7,7 @@ com.agentclientprotocol acp-java-sdk - 0.13.0 + 0.15.0-SNAPSHOT acp-core diff --git a/acp-core/src/main/java/com/agentclientprotocol/sdk/spec/AcpClientSession.java b/acp-core/src/main/java/com/agentclientprotocol/sdk/spec/AcpClientSession.java index 2b368313..9c68e2c2 100644 --- a/acp-core/src/main/java/com/agentclientprotocol/sdk/spec/AcpClientSession.java +++ b/acp-core/src/main/java/com/agentclientprotocol/sdk/spec/AcpClientSession.java @@ -11,8 +11,10 @@ import org.reactivestreams.Publisher; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import reactor.core.Disposable; import reactor.core.publisher.Mono; import reactor.core.publisher.MonoSink; +import reactor.core.publisher.Sinks; import java.time.Duration; import java.util.Map; @@ -78,6 +80,15 @@ public class AcpClientSession implements AcpSession { /** Atomic counter for generating unique request IDs */ private final AtomicLong requestCounter = new AtomicLong(0); + /** Sink for serializing notification delivery in arrival order */ + private final Sinks.Many notificationSink; + + /** Subscription draining the notification sink via concatMap */ + private final Disposable notificationSubscription; + + /** Completes when the notification drain terminates; awaited by {@link #closeGracefully()} */ + private final Sinks.Empty notificationDrainTerminated = Sinks.empty(); + /** * Functional interface for handling incoming JSON-RPC requests. Implementations * should process the request parameters and return a response. @@ -148,6 +159,18 @@ public AcpClientSession(Duration requestTimeout, AcpClientTransport transport, return t; }), "acp-timeout-" + sessionPrefix); + // Serialize notification delivery: concatMap ensures each notification's Mono + // completes before the next one starts, preserving arrival order even when + // handlers do async work. + this.notificationSink = Sinks.many().unicast().onBackpressureBuffer(); + this.notificationSubscription = this.notificationSink.asFlux() + .concatMap(notification -> handleIncomingNotification(notification).onErrorComplete(t -> { + logger.error("Error handling notification: {}", t.getMessage()); + return true; + })) + .doFinally(signal -> this.notificationDrainTerminated.tryEmitEmpty()) + .subscribe(); + this.transport.connect(mono -> mono.doOnNext(this::handle).then(Mono.empty())).transform(connectHook).subscribe(); } @@ -203,10 +226,23 @@ else if (message instanceof AcpSchema.JSONRPCRequest request) { else if (message instanceof AcpSchema.JSONRPCNotification notification) { logger.debug("Received notification: {}", notification); logger.trace("Incoming notification method='{}' params={}", notification.method(), notification.params()); - handleIncomingNotification(notification).onErrorComplete(t -> { - logger.error("Error handling notification: {}", t.getMessage()); - return true; - }).subscribe(); + Sinks.EmitResult result = notificationSink.tryEmitNext(notification); + if (result.isFailure()) { + if (result == Sinks.EmitResult.FAIL_TERMINATED || result == Sinks.EmitResult.FAIL_CANCELLED) { + // The session is shutting down. Refusing newly arriving notifications + // is the intended behaviour: a graceful shutdown stops accepting new + // work and drains what is already queued, and JSON-RPC notifications + // carry no delivery guarantee by design. + logger.debug("Session is closing; dropping notification method='{}' ({})", notification.method(), + result); + } + else { + // Overflow, no subscriber, or concurrent (non-serialized) emission: + // protocol traffic lost on a live session, which is never expected. + logger.error("Dropped notification method='{}': sink emission failed with {}", + notification.method(), result); + } + } } else { logger.warn("Received unknown message type: {}", message); @@ -350,10 +386,19 @@ public Mono sendNotification(String method, Object params) { */ @Override public Mono closeGracefully() { - return Mono.fromRunnable(() -> { + return Mono.fromRunnable(() -> { dismissPendingResponses(); - timeoutScheduler.dispose(); - }); + notificationSink.tryEmitComplete(); + }) + // Wait for queued notifications to drain before tearing the session down; + // disposing immediately would discard them. Bounded so a handler that never + // completes cannot hang graceful close. + .then(this.notificationDrainTerminated.asMono() + .timeout(this.requestTimeout, Mono.empty(), this.timeoutScheduler)) + .doFinally(signal -> { + notificationSubscription.dispose(); + timeoutScheduler.dispose(); + }); } /** @@ -362,6 +407,8 @@ public Mono closeGracefully() { @Override public void close() { dismissPendingResponses(); + notificationSink.tryEmitComplete(); + notificationSubscription.dispose(); timeoutScheduler.dispose(); } diff --git a/acp-core/src/test/java/com/agentclientprotocol/sdk/client/HandlerExceptionTest.java b/acp-core/src/test/java/com/agentclientprotocol/sdk/client/HandlerExceptionTest.java index d81652d5..4e84c348 100644 --- a/acp-core/src/test/java/com/agentclientprotocol/sdk/client/HandlerExceptionTest.java +++ b/acp-core/src/test/java/com/agentclientprotocol/sdk/client/HandlerExceptionTest.java @@ -3,6 +3,7 @@ */ package com.agentclientprotocol.sdk.client; +import java.time.Duration; import java.util.Map; import java.util.function.Function; @@ -23,7 +24,7 @@ class HandlerExceptionTest { * to a proper JSON-RPC error response with code -32603 (Internal Error). */ @Test - void handlerExceptionConvertedToJsonRpcError() throws InterruptedException { + void handlerExceptionConvertedToJsonRpcError() { MockAcpClientTransport transport = new MockAcpClientTransport(); String errorMessage = "File not found: /nonexistent.txt"; @@ -45,8 +46,7 @@ void handlerExceptionConvertedToJsonRpcError() throws InterruptedException { ); transport.simulateIncomingMessage(request); - // Wait for async processing - Thread.sleep(500); + awaitSentMessages(transport, 1); // Verify it's a JSON-RPC error response assertThat(transport.getSentMessages()).hasSize(1); @@ -66,7 +66,7 @@ void handlerExceptionConvertedToJsonRpcError() throws InterruptedException { * Verifies that IOException from file operations is also converted to JSON-RPC error. */ @Test - void ioExceptionConvertedToJsonRpcError() throws InterruptedException { + void ioExceptionConvertedToJsonRpcError() { MockAcpClientTransport transport = new MockAcpClientTransport(); // Create a handler that throws IOException (wrapped in RuntimeException per Java patterns) @@ -86,8 +86,7 @@ void ioExceptionConvertedToJsonRpcError() throws InterruptedException { ); transport.simulateIncomingMessage(request); - // Wait for async processing - Thread.sleep(500); + awaitSentMessages(transport, 1); assertThat(transport.getSentMessages()).hasSize(1); AcpSchema.JSONRPCResponse response = (AcpSchema.JSONRPCResponse) transport.getSentMessages().get(0); @@ -97,4 +96,22 @@ void ioExceptionConvertedToJsonRpcError() throws InterruptedException { client.close(); } + + /** + * Waits for the transport to have sent at least {@code expected} messages. The + * handler runs asynchronously, so a fixed sleep races the dispatch and fails + * intermittently on a loaded machine; poll to a generous deadline instead. + */ + private static void awaitSentMessages(MockAcpClientTransport transport, int expected) { + long deadline = System.nanoTime() + Duration.ofSeconds(10).toNanos(); + while (transport.getSentMessages().size() < expected && System.nanoTime() < deadline) { + try { + Thread.sleep(10); + } + catch (InterruptedException ex) { + Thread.currentThread().interrupt(); + return; + } + } + } } diff --git a/acp-core/src/test/java/com/agentclientprotocol/sdk/spec/AcpClientSessionTest.java b/acp-core/src/test/java/com/agentclientprotocol/sdk/spec/AcpClientSessionTest.java index 58a37997..57110dcd 100644 --- a/acp-core/src/test/java/com/agentclientprotocol/sdk/spec/AcpClientSessionTest.java +++ b/acp-core/src/test/java/com/agentclientprotocol/sdk/spec/AcpClientSessionTest.java @@ -5,7 +5,11 @@ package com.agentclientprotocol.sdk.spec; import java.time.Duration; +import java.util.List; import java.util.Map; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; import java.util.function.Function; import com.agentclientprotocol.sdk.MockAcpClientTransport; @@ -298,6 +302,62 @@ void testGracefulShutdown() { StepVerifier.create(session.closeGracefully()).verifyComplete(); } + @Test + void testNotificationOrderPreservedWithAsyncHandler() throws InterruptedException { + // Notification i gets a delay of (5 - i) * 30ms so that without serialization + // later notifications would complete first, reversing the observed order. + int count = 5; + List processedOrder = new CopyOnWriteArrayList<>(); + CountDownLatch latch = new CountDownLatch(count); + + var transport = new MockAcpClientTransport(); + var session = new AcpClientSession(TIMEOUT, transport, Map.of(), + Map.of(TEST_NOTIFICATION, params -> { + int index = (int) ((Map) params).get("index"); + long delayMs = (count - index) * 30L; + return Mono.delay(Duration.ofMillis(delayMs)).then(Mono.fromRunnable(() -> { + processedOrder.add(index); + latch.countDown(); + })); + }), + Function.identity()); + + for (int i = 0; i < count; i++) { + transport.simulateIncomingMessage(new AcpSchema.JSONRPCNotification( + AcpSchema.JSONRPC_VERSION, TEST_NOTIFICATION, Map.of("index", i))); + } + + assertThat(latch.await(5, TimeUnit.SECONDS)).isTrue(); + assertThat(processedOrder).containsExactly(0, 1, 2, 3, 4); + + session.close(); + } + + @Test + void testGracefulCloseDrainsQueuedNotifications() { + // Notifications queued behind an async handler must be delivered by a graceful + // close, not discarded when the drain subscription is disposed. + int count = 10; + List processedOrder = new CopyOnWriteArrayList<>(); + + var transport = new MockAcpClientTransport(); + var session = new AcpClientSession(TIMEOUT, transport, Map.of(), + Map.of(TEST_NOTIFICATION, params -> { + int index = (int) ((Map) params).get("index"); + return Mono.delay(Duration.ofMillis(20)).doOnNext(t -> processedOrder.add(index)).then(); + }), + Function.identity()); + + for (int i = 0; i < count; i++) { + transport.simulateIncomingMessage(new AcpSchema.JSONRPCNotification( + AcpSchema.JSONRPC_VERSION, TEST_NOTIFICATION, Map.of("index", i))); + } + + session.closeGracefully().block(); + + assertThat(processedOrder).containsExactly(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); + } + @Test void testConcurrentRequests() { var transport = new MockAcpClientTransport(); diff --git a/acp-test/README.md b/acp-test/README.md index a91ceb0b..6f254562 100644 --- a/acp-test/README.md +++ b/acp-test/README.md @@ -38,4 +38,4 @@ AcpSyncAgent agent = AcpAgent.sync(pair.agentTransport()) ## Documentation -- [Module 16: In-Memory Testing](https://springaicommunity.mintlify.app/acp-java-sdk/tutorial/16-in-memory-testing) +- [Module 16: In-Memory Testing](https://lab.pollack.ai/docs/acp-java-sdk/tutorial/16-in-memory-testing) diff --git a/acp-test/pom.xml b/acp-test/pom.xml index d31e7952..c35c1a53 100644 --- a/acp-test/pom.xml +++ b/acp-test/pom.xml @@ -7,7 +7,7 @@ com.agentclientprotocol acp-java-sdk - 0.13.0 + 0.15.0-SNAPSHOT acp-test diff --git a/acp-websocket-jetty/README.md b/acp-websocket-jetty/README.md index 61bbc80d..e9da9877 100644 --- a/acp-websocket-jetty/README.md +++ b/acp-websocket-jetty/README.md @@ -24,4 +24,4 @@ Use WebSocket transport when the agent runs as a long-lived server process that ## Documentation -- [API Reference — Transports](https://springaicommunity.mintlify.app/acp-java-sdk/reference/java#transports) +- [API Reference — Transports](https://lab.pollack.ai/docs/acp-java-sdk/reference/java#transports) diff --git a/acp-websocket-jetty/pom.xml b/acp-websocket-jetty/pom.xml index 66afb56f..e9e6ca2f 100644 --- a/acp-websocket-jetty/pom.xml +++ b/acp-websocket-jetty/pom.xml @@ -7,7 +7,7 @@ com.agentclientprotocol acp-java-sdk - 0.13.0 + 0.15.0-SNAPSHOT acp-websocket-jetty diff --git a/pom.xml b/pom.xml index 1f1188a6..c9ef2c90 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.agentclientprotocol acp-java-sdk - 0.13.0 + 0.15.0-SNAPSHOT pom ACP Java SDK @@ -62,10 +62,10 @@ 2023.0.12 - 2.21.2 + 2.21.5 2.0.16 - 12.0.14 + 12.0.37 5.11.0 @@ -76,6 +76,7 @@ 3.13.0 3.1.2 + 3.1.2 3.3.0 3.6.0 3.2.7 @@ -159,6 +160,22 @@ + + + + src/main/resources + + + + ${maven.multiModuleProjectDirectory} + META-INF + + LICENSE + NOTICE + + + + @@ -178,6 +195,22 @@ ${maven-surefire-plugin.version} + + + org.apache.maven.plugins + maven-failsafe-plugin + ${maven-failsafe-plugin.version} + + + + integration-test + verify + + + + + org.apache.maven.plugins @@ -310,16 +343,4 @@ - - - maven-central - https://repo.maven.apache.org/maven2/ - - true - - - true - - -