diff --git a/.github/workflows/release-sdk-java.yml b/.github/workflows/release-sdk-java.yml new file mode 100644 index 00000000000..e387aaaa163 --- /dev/null +++ b/.github/workflows/release-sdk-java.yml @@ -0,0 +1,212 @@ +name: 'Release Java SDK' + +on: + workflow_dispatch: + inputs: + dry_run: + description: 'Verify the release without publishing, tagging, or creating a GitHub Release.' + required: true + type: 'boolean' + default: true + +concurrency: + group: 'release-sdk-java-0.1.0-alpha' + cancel-in-progress: false + +jobs: + release: + if: "${{ github.repository == 'QwenLM/qwen-code' }}" + runs-on: 'ubuntu-latest' + environment: + name: "${{ inputs.dry_run && 'sdk-java-dry-run' || 'production-release' }}" + url: '${{ github.server_url }}/${{ github.repository }}/releases' + permissions: + contents: 'write' + env: + SDK_DIRECTORY: 'packages/sdk-java/qwencode' + SDK_VERSION: '0.1.0-alpha' + RELEASE_TAG: 'sdk-java-v0.1.0-alpha' + steps: + - name: 'Require protected main' + env: + WORKFLOW_REF: '${{ github.ref }}' + run: |- + if [[ "${WORKFLOW_REF}" != "refs/heads/main" ]]; then + echo 'The Java SDK release workflow must run from main.' >&2 + exit 1 + fi + + - name: 'Checkout main' + uses: 'actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10' # v6.0.3 + with: + ref: 'main' + fetch-depth: 0 + persist-credentials: false + + - name: 'Set up Java' + uses: 'actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654' # v5.2.0 + with: + distribution: 'temurin' + java-version: '11' + cache: 'maven' + cache-dependency-path: 'packages/sdk-java/qwencode/pom.xml' + + - name: 'Set up Node.js' + uses: 'actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e' # v6.4.0 + with: + node-version: '22' + cache: 'npm' + + - name: 'Validate release version and tag' + id: 'preflight' + env: + CURRENT_SHA: '${{ github.sha }}' + DRY_RUN: '${{ inputs.dry_run }}' + run: |- + set -euo pipefail + checked_out_sha=$(git rev-parse HEAD) + if [[ "${checked_out_sha}" != "${CURRENT_SHA}" ]]; then + echo "Checked-out main ${checked_out_sha} does not match workflow SHA ${CURRENT_SHA}." >&2 + exit 1 + fi + + tag_state='new' + direct_tag=$(git ls-remote --refs --tags origin "refs/tags/${RELEASE_TAG}" | cut -f1) + peeled_tag=$(git ls-remote --tags origin "refs/tags/${RELEASE_TAG}^{}" | cut -f1) + if [[ -n "${direct_tag}" ]]; then + if [[ -z "${peeled_tag}" ]]; then + echo "${RELEASE_TAG} is not an annotated release tag." >&2 + exit 1 + fi + tag_commit=${peeled_tag} + if ! git merge-base --is-ancestor "${tag_commit}" "${checked_out_sha}"; then + echo "${RELEASE_TAG} does not point to a commit in protected main history." >&2 + exit 1 + fi + git checkout --detach "${tag_commit}" + tag_state='resume' + fi + + actual_version=$(mvn --batch-mode --no-transfer-progress -f "${SDK_DIRECTORY}/pom.xml" help:evaluate -Dexpression=project.version -q -DforceStdout) + if [[ "${actual_version}" != "${SDK_VERSION}" ]]; then + echo "Expected ${SDK_VERSION}, found ${actual_version}." >&2 + exit 1 + fi + artifact_url="https://repo1.maven.org/maven2/com/alibaba/qwencode-sdk/${SDK_VERSION}/qwencode-sdk-${SDK_VERSION}.pom" + probe_artifact() { + local status='' + for attempt in 1 2 3; do + if status=$(curl --silent --show-error --location --connect-timeout 10 --max-time 30 --output /dev/null --write-out '%{http_code}' "${artifact_url}"); then + if [[ "${status}" == '200' ]]; then + echo 'published' + return 0 + fi + if [[ "${status}" == '404' ]]; then + echo 'missing' + return 0 + fi + fi + if [[ "${attempt}" -lt 3 ]]; then + sleep 5 + fi + done + echo "Maven Central probe was inconclusive (last HTTP status: ${status:-transport_error})." >&2 + return 1 + } + artifact_state=$(probe_artifact) + if [[ "${tag_state}" == 'new' && "${artifact_state}" == 'published' ]]; then + echo "${SDK_VERSION} is already published without ${RELEASE_TAG}; manual recovery is required." >&2 + exit 1 + fi + if [[ "${DRY_RUN}" == 'false' && "${tag_state}" == 'resume' && "${artifact_state}" == 'missing' ]]; then + echo 'Matching tag already exists; Maven publication will resume from that immutable source commit.' + elif [[ "${DRY_RUN}" == 'false' && "${tag_state}" == 'resume' ]]; then + echo 'Matching tag and artifact already exist; GitHub Release creation will resume.' + fi + echo "tag_state=${tag_state}" >> "${GITHUB_OUTPUT}" + echo "artifact_state=${artifact_state}" >> "${GITHUB_OUTPUT}" + + - name: 'Verify release build' + working-directory: '${{ env.SDK_DIRECTORY }}' + run: 'mvn --batch-mode --no-transfer-progress clean verify -Dgpg.skip=true' + + - name: 'Install Node.js dependencies' + run: 'npm ci --prefer-offline --no-audit --progress=false' + + - name: 'Build Qwen Code' + run: 'npm run build' + + - name: 'Bundle Qwen Code' + run: 'npm run bundle' + + - name: 'Run Java daemon E2E' + run: 'npx tsx scripts/run-java-daemon-sdk-e2e.ts' + + - name: 'Require an unchanged source tree' + run: |- + if [[ -n "$(git status --porcelain)" ]]; then + git status --short + echo 'Release verification changed or created source files.' >&2 + exit 1 + fi + + - name: 'Create and push release tag' + if: "${{ !inputs.dry_run && steps.preflight.outputs.tag_state == 'new' }}" + env: + GH_TOKEN: '${{ github.token }}' + run: |- + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + git tag -a "${RELEASE_TAG}" -m "Java SDK ${SDK_VERSION}" + gh auth setup-git + git push origin "refs/tags/${RELEASE_TAG}" + + - name: 'Configure Maven Central publishing' + if: "${{ !inputs.dry_run && steps.preflight.outputs.artifact_state == 'missing' }}" + uses: 'actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654' # v5.2.0 + with: + distribution: 'temurin' + java-version: '11' + cache: 'maven' + cache-dependency-path: 'packages/sdk-java/qwencode/pom.xml' + server-id: 'central' + server-username: 'MAVEN_USERNAME' + server-password: 'MAVEN_PASSWORD' + gpg-private-key: '${{ secrets.MAVEN_GPG_PRIVATE_KEY }}' + gpg-passphrase: 'MAVEN_GPG_PASSPHRASE' + + - name: 'Publish signed artifacts to Maven Central' + if: "${{ !inputs.dry_run && steps.preflight.outputs.artifact_state == 'missing' }}" + working-directory: '${{ env.SDK_DIRECTORY }}' + env: + MAVEN_GPG_PASSPHRASE: '${{ secrets.MAVEN_GPG_PASSPHRASE }}' + MAVEN_USERNAME: '${{ secrets.CENTRAL_USERNAME }}' + MAVEN_PASSWORD: '${{ secrets.CENTRAL_PASSWORD }}' + run: 'mvn --batch-mode --no-transfer-progress -DskipTests deploy' + + - name: 'Verify Maven Central availability' + if: '${{ !inputs.dry_run }}' + run: |- + artifact_url="https://repo1.maven.org/maven2/com/alibaba/qwencode-sdk/${SDK_VERSION}/qwencode-sdk-${SDK_VERSION}.pom" + for attempt in {1..30}; do + if curl --fail --silent --show-error --location --output /dev/null "${artifact_url}"; then + exit 0 + fi + if [[ "${attempt}" -lt 30 ]]; then + sleep 10 + fi + done + echo "Published artifact is not available at ${artifact_url}." >&2 + exit 1 + + - name: 'Create GitHub Release' + if: '${{ !inputs.dry_run }}' + env: + GH_TOKEN: '${{ github.token }}' + run: |- + git fetch origin "refs/tags/${RELEASE_TAG}:refs/tags/${RELEASE_TAG}" --force + if gh release view "${RELEASE_TAG}" >/dev/null 2>&1; then + echo "GitHub Release ${RELEASE_TAG} already exists." + exit 0 + fi + gh release create "${RELEASE_TAG}" --verify-tag --title "Java SDK ${SDK_VERSION}" --generate-notes diff --git a/.github/workflows/sdk-java.yml b/.github/workflows/sdk-java.yml new file mode 100644 index 00000000000..ba99ba31134 --- /dev/null +++ b/.github/workflows/sdk-java.yml @@ -0,0 +1,119 @@ +name: 'SDK Java' + +on: + pull_request: + branches: + - 'main' + - 'release/**' + paths: + - 'packages/sdk-java/**' + - 'packages/cli/src/commands/serve.ts' + - 'packages/cli/src/serve/**' + - 'packages/cli/src/acp-integration/**' + - 'packages/acp-bridge/**' + - 'integration-tests/fake-openai-server.ts' + - 'package.json' + - 'package-lock.json' + - 'docs/developers/sdk-java.md' + - 'docs/design/java-daemon-sdk-alpha.md' + - 'scripts/run-java-daemon-sdk-e2e.ts' + - '.github/workflows/sdk-java.yml' + - '.github/workflows/release-sdk-java.yml' + push: + branches: + - 'main' + - 'release/**' + paths: + - 'packages/sdk-java/**' + - 'packages/cli/src/commands/serve.ts' + - 'packages/cli/src/serve/**' + - 'packages/cli/src/acp-integration/**' + - 'packages/acp-bridge/**' + - 'integration-tests/fake-openai-server.ts' + - 'package.json' + - 'package-lock.json' + - 'docs/developers/sdk-java.md' + - 'docs/design/java-daemon-sdk-alpha.md' + - 'scripts/run-java-daemon-sdk-e2e.ts' + - '.github/workflows/sdk-java.yml' + - '.github/workflows/release-sdk-java.yml' + +permissions: + contents: 'read' + +jobs: + test: + name: '${{ matrix.os }} / Java ${{ matrix.java }}' + runs-on: '${{ matrix.os }}' + strategy: + fail-fast: false + matrix: + include: + - os: 'ubuntu-latest' + java: '11' + - os: 'ubuntu-latest' + java: '17' + - os: 'ubuntu-latest' + java: '21' + - os: 'macos-latest' + java: '21' + - os: 'windows-latest' + java: '21' + steps: + - name: 'Checkout' + uses: 'actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10' # v6.0.3 + + - name: 'Set up Java' + uses: 'actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654' # v5.2.0 + with: + distribution: 'temurin' + java-version: '${{ matrix.java }}' + cache: 'maven' + cache-dependency-path: 'packages/sdk-java/qwencode/pom.xml' + + - name: 'Run Java SDK tests' + working-directory: 'packages/sdk-java/qwencode' + run: 'mvn --batch-mode --no-transfer-progress clean test' + + - name: 'Run Java SDK Checkstyle' + if: "${{ matrix.os == 'ubuntu-latest' && matrix.java == '11' }}" + working-directory: 'packages/sdk-java/qwencode' + run: 'mvn --batch-mode --no-transfer-progress checkstyle:check' + + - name: 'Build release artifacts' + if: "${{ matrix.os == 'ubuntu-latest' && matrix.java == '11' }}" + working-directory: 'packages/sdk-java/qwencode' + run: 'mvn --batch-mode --no-transfer-progress -DskipTests -Dgpg.skip=true package' + + daemon-e2e: + name: 'Real daemon E2E / Java 11' + runs-on: 'ubuntu-latest' + steps: + - name: 'Checkout' + uses: 'actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10' # v6.0.3 + + - name: 'Set up Node.js' + uses: 'actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e' # v6.4.0 + with: + node-version: '22' + cache: 'npm' + + - name: 'Set up Java' + uses: 'actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654' # v5.2.0 + with: + distribution: 'temurin' + java-version: '11' + cache: 'maven' + cache-dependency-path: 'packages/sdk-java/qwencode/pom.xml' + + - name: 'Install Node.js dependencies' + run: 'npm ci --prefer-offline --no-audit --progress=false' + + - name: 'Build Qwen Code' + run: 'npm run build' + + - name: 'Bundle Qwen Code' + run: 'npm run bundle' + + - name: 'Run Java daemon E2E' + run: 'npx tsx scripts/run-java-daemon-sdk-e2e.ts' diff --git a/docs/design/java-daemon-sdk-alpha.md b/docs/design/java-daemon-sdk-alpha.md new file mode 100644 index 00000000000..e7370ca25d3 --- /dev/null +++ b/docs/design/java-daemon-sdk-alpha.md @@ -0,0 +1,213 @@ +# Java daemon SDK 0.1.0-alpha + +## Status + +This document defines the first daemon transport in the existing +`com.alibaba:qwencode-sdk` artifact. It is intentionally independent from the +legacy stdio implementation under `com.alibaba.qwen.code.cli`. + +## Goals + +- Add a Java 11 API for `qwen serve` without creating another Maven artifact. +- Deliver streamed text, thought, tool, usage, permission, and raw events in + daemon order. +- Return prompt text only after a matching reliable terminal event. +- Resume a prompt stream from the admission watermark without replay gaps or + duplicate observer delivery. +- Make ambiguous mutation outcomes and incomplete prompt outcomes explicit. +- Keep client-owned threads, streams, sessions, and detach attempts bounded. + +## Public surface + +`DaemonClient` owns HTTP and worker resources, reads capabilities, and creates +sessions. Session creation defaults to `sessionScope=thread`. Blocking prompt +observation uses a configurable bounded worker pool rather than a global or +unbounded executor. +The shared timer only dispatches watchdog actions. Potentially blocking SSE +stream closure runs on a separate bounded pool sized to the prompt concurrency +limit, so one stalled close cannot delay another session's deadline or idle +watchdog. Each admitted prompt reserves bounded stream-cleanup capacity until +its final close task finishes. A stalled close can therefore cause a later +`startPrompt` call to fail with `DaemonClientCapacityException`, but it cannot +silently discard a deadline-triggered close or grow cleanup work without bound. + +`DaemonSessionClient` owns one daemon session and admits at most one local +prompt at a time. `startPrompt` returns a `PromptCall` immediately. Its +admission and terminal futures are independent, so a caller can distinguish +"the daemon accepted this prompt" from "the turn ended reliably". +Admission and terminal future continuations are dispatched through a separate, +client-owned executor so user continuations cannot delay SSE observation, its +local timeout, or prompt transport capacity. Exceptional completion follows +the same path. Publication capacity is bounded relative to +`maximumConcurrentPrompts`; continuations that remain blocked can therefore +cause a later `startPrompt` call to fail with `DaemonClientCapacityException` +instead of creating unbounded threads or queued work. + +An indeterminate completion is not a session-reuse boundary. After admission +becomes unknown or an admitted prompt ends indeterminately, the session client +permanently rejects further prompts even if local stream cleanup succeeds. +A local observation timeout is published without waiting indefinitely for +stream closure; cleanup continues asynchronously and retains bounded client +capacity until it finishes. Callers close or destroy the affected session. + +`PromptObserver` receives typed callbacks and the raw event. Callbacks execute +serially on a client-owned daemon thread. An event cursor advances only after +all applicable callbacks return successfully. Callbacks must therefore return +promptly, must not wait on the same `PromptCall`, and must not close or destroy +the same session from a callback. Responding to a permission from its callback +is supported; the response method returns `false` when the daemon reports that +the request was already resolved or is no longer pending. + +`promptText` is a convenience over `startPrompt`. It collects only assistant +text, enforces a UTF-8 byte limit, and returns a `PromptTextResult` only for a +matching `turn_complete`. A `turn_error` remains a reliable terminal but is +reported as `PromptTurnException`; any outcome without a reliable terminal is +reported as `PromptOutcomeIndeterminateException` with explicitly incomplete +partial text when available. + +Fastjson2 encoding and strict Jackson Core decoding are implementation details. +Decoding rejects non-standard JSON and duplicate object keys. Public raw JSON +values use Java `Map`, `List`, scalar, and null values. + +Creation-time model selection is intentionally not exposed in this alpha. +The daemon keeps a fresh session alive on the default model when +`modelServiceId` is rejected and reports the rejection only through an SSE +event emitted before the create response. The per-prompt subscription starts +from the later admission watermark, so it cannot prove that the requested +model was selected without adding a separate session-event lifecycle. + +Before session creation, the SDK requires the daemon to advertise REST and +`session_scope_override`; it refuses to mutate when an older daemon could +silently ignore the requested scope. While a session remains open, the SDK +sends a new heartbeat mutation once per configured interval (one minute by +default) only when the daemon advertises `client_heartbeat`, and stops on +detach or destroy. Each heartbeat has the normal finite-request deadline and +is not retried; setting the interval to zero disables automatic keepalive. +Likewise, a prompt carrying `deadlineMs` is rejected before admission unless +the daemon advertises `prompt_absolute_deadline`, so a requested server-side +deadline cannot be silently ignored. The local observation timeout remains +independent and is always enforced by the SDK. + +## Wire flow + +1. Send one non-retried `POST /session/:id/prompt`. +2. Require `202` and validate `{promptId,lastEventId}`. +3. Open `GET /session/:id/events` with `Last-Event-ID` set to the watermark. +4. Replay and observe only events correlated with that prompt, while treating + session-level failure frames as fatal. +5. Stop only on matching `turn_complete` or `turn_error`. + +This per-prompt subscription covers content and terminal events emitted before +the `202` response reaches the client. It does not require an unknown-prompt +cache or a long-lived session pump. + +## Transport contract + +The JDK `HttpClient` uses HTTP/1.1 and never follows redirects. Every request +sends JSON or event-stream `Accept` headers, bearer authentication when +configured, and the daemon-issued `X-Qwen-Client-Id` after session creation. +SSE additionally sends `Accept-Encoding: identity`, `Cache-Control: no-cache`, +and `Last-Event-ID`. + +Finite JSON and error bodies are consumed by a bounded subscriber and raced +against the request deadline through `sendAsync`; receiving response headers +does not end that deadline. Non-success SSE bodies are separately bounded by +the shorter of the request and prompt-observation budgets. + +The SSE parser accepts LF and CRLF framing, comments, and multiple `data:` +lines. UTF-8 decoding is strict. Frames, event names, envelope version, numeric +IDs, and SSE/envelope ID consistency are validated. A malformed frame, an ID +gap, `state_resync_required`, session death, observer failure, idle timeout, or +reconnect exhaustion fails closed. + +IDs at or below the committed cursor are duplicates and are not delivered. +The next numeric event must be exactly `cursor + 1`. Synthetic ID-less events +are accepted only for the daemon's documented control frames and do not move +the cursor; an ID-less content or terminal event fails closed. The +implementation reconnects only the SSE GET, using bounded exponential +full-jitter backoff, the SSE `retry` directive after a stream disconnect, and +`Retry-After` on retryable HTTP responses. Mutations are never retried +automatically. + +## Ambiguous and terminal outcomes + +If prompt transport fails after dispatch without a validated `202`, or returns +HTTP 408 or 5xx, the admission future fails with +`PromptAdmissionUnknownException`; the SDK never reposts the prompt. Session +creation applies the same conservative classification through +`SessionCreationOutcomeUnknownException`. Permission, cancel, heartbeat, +detach, and delete apply the same classification because an intermediary +response does not prove that the daemon rejected the mutation. Detach uses the +more specific `DetachOutcomeUnknownException`. Every mutation is attempted at +most once per method invocation. + +Only matching `turn_complete` and `turn_error` are terminal. Queue and +`prompt_cancelled` events are advisory. A local timeout stops observation but +does not automatically cancel the daemon turn. A cooperative daemon +cancellation completes as `turn_complete` with `stopReason=cancelled`, while an +agent or provider failure during cancellation can produce `turn_error`. +`promptText()` returns the complete result and surfaces the error terminal as +`PromptTurnException`; callers must wait for the terminal in both cases. +When cancellation, deadline, teardown, or agent settlement race, the daemon's +exactly-once latch publishes the first formal terminal and suppresses later +candidates. The SDK therefore treats the received terminal as authoritative +instead of deriving an outcome from the last control mutation it sent. + +`close()` is locally idempotent, stops local observation, and attempts detach +at most once. A lost detach response is not retried. `destroySession()` is the +only API that issues `DELETE /session/:id`; it may be called after detach. + +## Compatibility and non-goals + +The whole artifact now requires Java 11. Java 8 users must remain on +`0.0.3-alpha`. The stdio API remains source-compatible but now runs on Java 11 +and obtains logging through `slf4j-api`; applications choose their own SLF4J +provider because Logback is test-only. + +The compatible daemon is the qwen-code build released from the same source +revision as the SDK. It contains the per-client detach ledger from #7386, the +per-epoch terminal guarantee from #7400, and this release's acknowledged +admission cancellation plus FIFO cancel-drain fence. The #7400 commit alone can +still acknowledge cancel before agent dispatch without stopping the admitted +prompt, or let an unacknowledged session-scoped cancel reach a queued successor. +The bundled ACP child handles the daemon's internal cancellation request through +one acknowledged admission-aware handshake. A custom standards-compliant ACP +child that does not implement that extension receives one standard +`session/cancel` notification instead. The +daemon does not advertise a capability that distinguishes these implementations +with the same REST/SSE feature set, so the SDK cannot negotiate this minimum at +runtime and fails closed when a formal terminal is absent. + +The handshake intentionally waits for the targeted prompt call to settle before +the FIFO may dispatch its successor. Adding an acknowledgement-only timeout +would allow a late session-scoped cancel to reach that successor and would break +the ordering guarantee. Consequently, a provider, tool, or custom integration +that ignores its `AbortSignal` indefinitely can leave the cancel mutation +outcome unknown and the session unusable. Reclaiming a wedged shared ACP child +without terminating sibling sessions requires stronger runtime isolation and is +outside this alpha. + +The alpha does not promise exactly-once execution across daemon restarts, +automatic epoch recovery, snapshot/resync, persisted cursors, or true +prompt-ID-targeted cancellation. It also does not expose creation-time model +selection until the daemon can return a definitive result or the SDK owns a +session-event lifecycle from `Last-Event-ID: 0`. An ambiguous create can leave +a daemon session that the caller cannot identify or detach until daemon-side +reaping. Those cases require stronger daemon contracts. + +## Verification + +Unit tests use an in-process HTTP server to inject SSE fragmentation, slow +single-line delivery, replay, duplicates, gaps, conflicting prompt IDs, +opaque future event data, watermark replay, disconnects, compressed responses, +stalled finite bodies, resync, observer failures, terminal absence, and +ambiguous mutation responses. Lifecycle tests cover one-local-prompt admission, +admission/close serialization, deadline terminal followed by session reuse, +cancelled completion, teardown terminal ordering, bounded text, automatic +heartbeat, idempotent close, detach client identity, detach-once, and explicit +destroy. + +CI compiles and tests on Java 11, 17, and 21 on Linux, with Java 21 smoke +coverage on macOS and Windows. Linux CI and the protected release workflow run +an E2E against a real `qwen serve` process with a temporary workspace and +model stub. diff --git a/docs/developers/sdk-java.md b/docs/developers/sdk-java.md index 7c001977985..890817b4cb6 100644 --- a/docs/developers/sdk-java.md +++ b/docs/developers/sdk-java.md @@ -1,18 +1,18 @@ # Qwen Code Java SDK -The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications. +The Qwen Code Java SDK provides a recommended daemon transport for `qwen serve` and retains the experimental legacy stdio API for compatibility. Both APIs ship in the same `com.alibaba:qwencode-sdk` artifact. ## Requirements -- Java >= 1.8 -- Maven >= 3.6.0 (for building from source) -- qwen-code >= 0.5.0 +- Java >= 11 for `0.1.0-alpha` +- Maven >= 3.9.2 when building or publishing this SDK from source +- A compatible `qwen serve` for the daemon API, or qwen-code >= 0.5.0 for the legacy stdio API ### Dependencies -- **Logging**: ch.qos.logback:logback-classic +- **Logging API**: org.slf4j:slf4j-api (choose an SLF4J provider in your application) - **Utilities**: org.apache.commons:commons-lang3 -- **JSON Processing**: com.alibaba.fastjson2:fastjson2 +- **JSON Processing**: Fastjson2 for encoding and Jackson Core for strict decoding - **Testing**: JUnit 5 (org.junit.jupiter:junit-jupiter) ## Installation @@ -23,14 +23,14 @@ Add the following dependency to your Maven `pom.xml`: com.alibaba qwencode-sdk - {$version} + 0.1.0-alpha ``` Or if using Gradle, add to your `build.gradle`: ```gradle -implementation 'com.alibaba:qwencode-sdk:{$version}' +implementation 'com.alibaba:qwencode-sdk:0.1.0-alpha' ``` ## Building and Running @@ -51,9 +51,63 @@ mvn package mvn install ``` -## Quick Start +### Real daemon E2E from source -The simplest way to use the SDK is through the `QwenCodeCli.simpleQuery()` method: +Run the real-daemon Java integration tests from the repository root after building both the workspaces and the root CLI bundle: + +```bash +npm run build +npm run bundle +npx tsx scripts/run-java-daemon-sdk-e2e.ts +``` + +`npm run build` alone does not refresh `dist/cli.js`; the E2E harness launches that bundle and fails with an explicit prerequisite error when it is missing. + +## Recommended daemon API + +Start `qwen serve`, then create an independent thread-scoped session. `promptText` returns only after a matching `turn_complete`; incomplete streams fail with `PromptOutcomeIndeterminateException` rather than returning partial text as success. + +For the lifecycle guarantees assumed by `0.1.0-alpha`, use the qwen-code build released from the same source revision as the SDK. The daemon must contain the idempotent per-client detach ledger from [#7386](https://github.com/QwenLM/qwen-code/pull/7386), the per-epoch terminal guarantee from [#7400](https://github.com/QwenLM/qwen-code/pull/7400), and this release's acknowledged admission cancellation plus FIFO cancel-drain fence. The #7400 commit alone is not sufficient: a same-wire daemon can acknowledge cancel before agent dispatch without stopping the admitted prompt, or let an unacknowledged session-scoped cancel reach a queued successor. The bundled ACP child uses one acknowledged admission-aware cancellation handshake; a custom standards-compliant ACP child without that extension receives one standard `session/cancel` notification. Feature negotiation cannot distinguish older same-wire daemon builds, so the SDK fails closed rather than reporting partial output as success. + +The bundled cancellation handshake deliberately waits for the targeted prompt call to settle before the daemon dispatches its queued successor. It has no timeout that merely acknowledges cancellation: doing so could let a late session-scoped cancel reach the next prompt. If a provider, tool, or custom integration ignores its `AbortSignal` indefinitely, the cancel mutation can therefore remain outcome-unknown and that session must not be reused. Treat a formal prompt terminal received within the caller's observation boundary as authoritative; otherwise close or destroy the session after observation fails. Recovering a wedged shared ACP child without disturbing its sibling sessions requires stronger runtime isolation and is outside this alpha contract. + +```java +import com.alibaba.qwen.code.daemon.DaemonClient; +import com.alibaba.qwen.code.daemon.DaemonSessionClient; +import com.alibaba.qwen.code.daemon.PromptTextResult; +import java.net.URI; + +try (DaemonClient daemon = DaemonClient.builder() + .baseUri(URI.create("http://127.0.0.1:4170")) + .build(); + DaemonSessionClient session = daemon.createSession()) { + PromptTextResult result = session.promptText("Explain this repository"); + System.out.println(result.getText()); +} +``` + +If `qwen serve` requires authentication, add +`.bearerToken(System.getenv("QWEN_SERVER_TOKEN"))` to the `DaemonClient` +builder. The SDK sends the bearer on REST and SSE requests and never puts it in +the URL. + +Use `startPrompt` with a `PromptObserver` when you need ordered text, thought, tool, usage, permission, and raw event callbacks. Its `acceptanceFuture()` and `completionFuture()` views separately expose daemon admission and the reliable turn terminal. `respondToPermission()` returns `false` when the request was already resolved or no longer pending. Cancelling the future views does not cancel the daemon prompt; use `cancelActivePrompt()` for the session-level daemon cancel operation and still wait for the matching terminal. A cooperative cancellation completes with `turn_complete` and `stopReason=cancelled`; `promptText()` returns its `PromptTextResult`, so callers that distinguish cancellation must inspect `result.getTerminal().getStopReason()`. If the agent or provider fails while cancelling, the daemon can instead publish `turn_error`, which makes `promptText()` throw `PromptTurnException`. + +When cancellation, deadline, teardown, or agent settlement race, the daemon's exactly-once latch publishes the first formal terminal and suppresses later candidates. Always branch on the received terminal itself; the last control mutation sent by the client does not determine the terminal kind or error code. + +The SSE transport sends `Accept-Encoding: identity` and `Last-Event-ID`, validates framing and event IDs, deduplicates replay, and reconnects only the SSE GET. Prompt and other mutation requests are never retried automatically. HTTP 408 and 5xx responses to prompt admission, session creation, permission, cancel, heartbeat, detach, or delete are reported as outcome-unknown because they do not prove that the daemon rejected the mutation. Finite response bodies and SSE observation have independent deadlines. + +Creation-time model selection is intentionally not exposed by the Java daemon SDK API in this alpha. The daemon reports a rejected `modelServiceId` only as an SSE event emitted before the create response, while this SDK opens its stream from the later prompt-admission watermark. Until the daemon returns a definitive create result or the SDK owns a separate session-event subscription from `Last-Event-ID: 0`, use the daemon's configured default model. + +`PromptRequest.Builder.deadline(Duration)` requests a daemon-enforced prompt deadline and is accepted only when the daemon advertises `prompt_absolute_deadline`; otherwise the SDK fails before sending the prompt. The value must be between 1 and 2,147,483,647 milliseconds, matching the daemon's Node timer range. This is separate from `observationTimeout(Duration)`, which only bounds local SSE observation and never sends a cancel mutation. + +Before creating a session, the SDK requires the daemon to advertise the REST transport and `session_scope_override`; this prevents an older daemon from silently ignoring the requested `thread` scope and attaching the client to a shared session. When `client_heartbeat` is advertised, an open session sends a fresh heartbeat every minute so the daemon does not reap an otherwise idle client. Set `heartbeatInterval(Duration.ZERO)` on the `DaemonClient` builder to disable this behavior, or choose a different positive interval. A heartbeat is never retried; the next scheduled heartbeat is a separate keepalive. Prompt observation is bounded to 32 concurrent prompts per client by default and can be adjusted with `maximumConcurrentPrompts`. Admission and terminal future callbacks run away from transport workers; callbacks that remain blocked consume bounded publication capacity. SSE stream cleanup is also bounded, and a close that remains blocked retains its cleanup reservation. Either condition can cause a later `startPrompt` to fail with `DaemonClientCapacityException` rather than dropping a timeout close or growing threads and queued work without limit. + +An indeterminate completion is an outcome boundary, not a session-reuse boundary. After `PromptAdmissionUnknownException` or `PromptOutcomeIndeterminateException`, that `DaemonSessionClient` permanently rejects further prompts even if local stream cleanup later succeeds; close or destroy the session instead. An observation timeout is published without waiting forever for a blocked stream close, while cleanup continues asynchronously and retains bounded client capacity until it finishes. + +## Legacy stdio API + +The existing `com.alibaba.qwen.code.cli` API remains available: ```java public static void runSimpleExample() { @@ -126,17 +180,24 @@ public static void runStreamingExample() { other examples see src/test/java/com/alibaba/qwen/code/cli/example +## Java 11 migration and alpha limits + +`0.1.0-alpha` raises the minimum Java version for the whole artifact from 8 to 11. Java 8 applications must remain on `0.0.3-alpha`. Logback is no longer a runtime dependency; add the SLF4J provider your application uses. + +This alpha deliberately fails closed when it cannot prove a prompt terminal. It does not guarantee exactly-once execution across daemon restarts, automatic epoch recovery, snapshot/resync, persisted cursors, or true prompt-ID-targeted cancellation. `prompt_cancelled` and queue events are advisory; only matching `turn_complete` and `turn_error` are terminal. + +If session creation has an ambiguous transport outcome, the daemon may retain a session whose ID never reached the caller. The SDK does not retry creation and cannot detach that unknown session; daemon-side lifecycle reaping is the recovery boundary. + ## Architecture -The SDK follows a layered architecture: +The artifact contains two isolated implementations: + +- **Daemon API**: `DaemonClient` and `DaemonSessionClient` use REST mutations plus resumable SSE and own bounded HTTP, prompt, maintenance, and timer resources. +- **Legacy stdio API**: `QwenCodeCli`, `Session`, and `ProcessTransport` manage a child CLI process using the existing CLI protocol DTOs and utilities. -- **API Layer**: Provides the main entry points through `QwenCodeCli` class with simple static methods for basic usage -- **Session Layer**: Manages communication sessions with the Qwen Code CLI through the `Session` class -- **Transport Layer**: Handles the communication mechanism between the SDK and CLI process (currently using process transport via `ProcessTransport`) -- **Protocol Layer**: Defines data structures for communication based on the CLI protocol -- **Utils**: Common utilities for concurrent execution, timeout handling, and error management +The daemon implementation does not reuse the legacy process transport, session model, DTOs, or global executor. -## Key Features +## Legacy stdio features ### Permission Modes @@ -284,11 +345,12 @@ The SDK provides specific exception types for different error scenarios: ### Q: Do I need to install the Qwen CLI separately? -A: yes, requires Qwen CLI 0.5.5 or higher. +A: Yes. The daemon API requires a compatible `qwen serve`; the legacy stdio +API requires qwen-code 0.5.0 or higher. ### Q: What Java versions are supported? -A: The SDK requires Java 1.8 or higher. +A: `0.1.0-alpha` requires Java 11 or higher. Java 8 users must remain on `0.0.3-alpha`. ### Q: How do I handle long-running requests? diff --git a/packages/acp-bridge/src/bridge.test.ts b/packages/acp-bridge/src/bridge.test.ts index fb8fbbf896f..d71d59b5685 100644 --- a/packages/acp-bridge/src/bridge.test.ts +++ b/packages/acp-bridge/src/bridge.test.ts @@ -80,6 +80,7 @@ import { import { SessionArtifactAuthorizationError } from './sessionArtifacts.js'; import { MID_TURN_QUEUE_DRAIN_METHOD, + PROMPT_CANCEL_METHOD, TODO_STOP_GUARD_QUEUE_RELEASE_METHOD, } from './bridgeTypes.js'; @@ -6020,11 +6021,9 @@ describe('createAcpSessionBridge', () => { const evt = await peerCancel; expect(evt.type).toBe('prompt_cancelled'); expect((evt.data as { reason?: string }).reason).toBe('forward_failed'); - await vi.waitFor(() => { - expect(cancelSpy).toHaveBeenCalledWith({ - sessionId: session.sessionId, - }); - }); + // A rejected prompt request has already settled in the child. Sending a + // late session-scoped cancel here could hit the queued successor. + expect(cancelSpy).not.toHaveBeenCalled(); peerAbort.abort(); await bridge.shutdown(); }); @@ -7135,7 +7134,16 @@ describe('createAcpSessionBridge', () => { }); it('publishes a deadline turn_error, unlocks the FIFO, and clears active state when the agent wedges (DAEMON-003)', async () => { - const handle = wedgeChannel(); + const handle = makeChannel({ + promptImpl: async (request) => { + const text = (request.prompt[0] as { text?: string }).text; + if (text === 'wedge') { + return new Promise(() => {}); + } + return { stopReason: 'end_turn' }; + }, + cancelImpl: () => new Promise(() => {}), + }); const bridge = makeBridge({ channelFactory: async () => handle.channel }); const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); const events: BridgeEvent[] = []; @@ -7253,6 +7261,9 @@ describe('createAcpSessionBridge', () => { }); await new Promise((r) => setTimeout(r, 60)); expect(terminalsFor(events, 'prompt-queued-deadline')).toHaveLength(1); + expect( + bridge.getSessionSummary(session.sessionId).turnError, + ).toBeUndefined(); // A queued prompt never ran, so its deadline terminal must not // advertise a session-level turnError nor arm the retry path — those @@ -7657,6 +7668,286 @@ describe('createAcpSessionBridge', () => { }); describe('cancelSession', () => { + it('cancels an admitted prompt before agent dispatch', async () => { + const events: BridgeEvent[] = []; + const handle = makeChannel({ + cancelImpl: () => { + throw { + code: -32603, + message: 'Internal error', + data: { details: 'Not currently generating' }, + }; + }, + }); + const bridge = makeBridge({ channelFactory: async () => handle.channel }); + const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); + const sub = (async () => { + for await (const event of bridge.subscribeEvents(session.sessionId)) { + events.push(event); + } + })(); + sub.catch(() => {}); + + const prompt = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'cancel immediately' }], + }, + undefined, + { promptId: 'prompt-admitted' }, + ); + await bridge.cancelSession(session.sessionId); + + await expect(prompt).rejects.toMatchObject({ name: 'AbortError' }); + expect(handle.agent.promptCalls).toHaveLength(0); + expect(handle.agent.cancelCalls).toHaveLength(0); + await vi.waitFor(() => { + const terminals = events.filter( + (event) => + (event.type === 'turn_complete' || event.type === 'turn_error') && + event.promptId === 'prompt-admitted', + ); + expect(terminals).toHaveLength(1); + expect(terminals[0]).toMatchObject({ + type: 'turn_complete', + data: { stopReason: 'cancelled' }, + }); + }); + + await bridge.shutdown(); + }); + + it('keeps cancelling while the child admits the prompt', async () => { + const promptEntered = deferred(); + const cancelAccepted = deferred(); + let generating = false; + const handle = makeChannel({ + promptImpl: async () => { + promptEntered.resolve(undefined); + setTimeout(() => { + generating = true; + }, 10); + await cancelAccepted.promise; + return { stopReason: 'cancelled' }; + }, + cancelImpl: () => { + if (!generating) { + throw new Error(NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE); + } + cancelAccepted.resolve(undefined); + }, + }); + const bridge = makeBridge({ channelFactory: async () => handle.channel }); + const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); + const prompt = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'cancel during admission' }], + }, + undefined, + { promptId: 'prompt-child-admission' }, + ); + + await promptEntered.promise; + await bridge.cancelSession(session.sessionId); + + await expect(prompt).resolves.toMatchObject({ stopReason: 'cancelled' }); + expect(handle.agent.cancelCalls.length).toBeGreaterThan(1); + await bridge.shutdown(); + }); + + it('drains a late cancel retry before dispatching the queued successor', async () => { + const firstPromptEntered = deferred(); + const finishFirstPrompt = deferred(); + const retryEntered = deferred(); + const releaseRetry = deferred(); + let cancelCalls = 0; + const handle = makeChannel({ + promptImpl: async (request) => { + const text = (request.prompt[0] as { text?: string }).text; + if (text === 'first') { + firstPromptEntered.resolve(undefined); + return finishFirstPrompt.promise; + } + return { stopReason: 'end_turn' }; + }, + cancelImpl: async () => { + cancelCalls += 1; + if (cancelCalls === 1) { + throw new Error(NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE); + } + retryEntered.resolve(undefined); + await releaseRetry.promise; + }, + }); + const bridge = makeBridge({ channelFactory: async () => handle.channel }); + const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); + const first = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'first' }], + }, + undefined, + { promptId: 'prompt-first' }, + ); + await firstPromptEntered.promise; + const second = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'second' }], + }, + undefined, + { promptId: 'prompt-second' }, + ); + + const cancel = bridge.cancelSession(session.sessionId); + await retryEntered.promise; + finishFirstPrompt.resolve({ stopReason: 'cancelled' }); + await expect(first).resolves.toEqual({ stopReason: 'cancelled' }); + await new Promise((resolve) => setTimeout(resolve, 20)); + expect(handle.agent.promptCalls).toHaveLength(1); + + releaseRetry.resolve(undefined); + await cancel; + await expect(second).resolves.toEqual({ stopReason: 'end_turn' }); + expect(handle.agent.promptCalls).toHaveLength(2); + await bridge.shutdown(); + }); + + it('releases cancellation and queued work when the channel exits during the handshake', async () => { + const firstPromptEntered = deferred(); + const handle = makeChannel({ + promptImpl: async (request) => { + const text = (request.prompt[0] as { text?: string }).text; + if (text === 'first') { + firstPromptEntered.resolve(undefined); + return new Promise(() => {}); + } + return { stopReason: 'end_turn' }; + }, + cancelImpl: () => new Promise(() => {}), + }); + const bridge = makeBridge({ channelFactory: async () => handle.channel }); + const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); + const first = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'first' }], + }, + undefined, + { promptId: 'prompt-first' }, + ); + void first.catch(() => {}); + await firstPromptEntered.promise; + const second = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'second' }], + }, + undefined, + { promptId: 'prompt-second' }, + ); + void second.catch(() => {}); + + const cancel = bridge.cancelSession(session.sessionId); + await vi.waitFor(() => { + expect(handle.agent.extMethodCalls).toContainEqual({ + method: PROMPT_CANCEL_METHOD, + params: { sessionId: session.sessionId }, + }); + }); + handle.crash({ exitCode: 1, signalCode: null }); + + await expect(cancel).rejects.toBeInstanceOf(BridgeChannelClosedError); + await expect(first).rejects.toBeInstanceOf(BridgeChannelClosedError); + await expect(second).rejects.toBeDefined(); + expect(handle.agent.promptCalls).toHaveLength(1); + await bridge.shutdown(); + }); + + it('falls back once to standard ACP cancellation for custom agents', async () => { + const promptEntered = deferred(); + const cancelAccepted = deferred(); + const handle = makeChannel({ + promptCancelExtension: false, + promptImpl: async () => { + promptEntered.resolve(undefined); + await cancelAccepted.promise; + return { stopReason: 'cancelled' }; + }, + cancelImpl: () => cancelAccepted.resolve(undefined), + }); + const bridge = makeBridge({ channelFactory: async () => handle.channel }); + const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); + const prompt = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: 'standard ACP fallback' }], + }, + undefined, + { promptId: 'prompt-standard-cancel' }, + ); + + await promptEntered.promise; + await bridge.cancelSession(session.sessionId); + + await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' }); + expect(handle.agent.extMethodCalls).toEqual([ + { + method: PROMPT_CANCEL_METHOD, + params: { sessionId: session.sessionId }, + }, + ]); + expect(handle.agent.cancelCalls).toEqual([ + { sessionId: session.sessionId }, + ]); + await bridge.shutdown(); + }); + + it('broadcasts immediate cancellation once for each prompt', async () => { + const events: BridgeEvent[] = []; + const handle = makeChannel(); + const bridge = makeBridge({ channelFactory: async () => handle.channel }); + const session = await bridge.spawnOrAttach({ workspaceCwd: WS_A }); + const sub = (async () => { + for await (const event of bridge.subscribeEvents(session.sessionId)) { + events.push(event); + } + })(); + sub.catch(() => {}); + + for (const promptId of ['prompt-immediate-1', 'prompt-immediate-2']) { + const prompt = bridge.sendPrompt( + session.sessionId, + { + sessionId: session.sessionId, + prompt: [{ type: 'text', text: promptId }], + }, + undefined, + { promptId }, + ); + await bridge.cancelSession(session.sessionId); + await expect(prompt).rejects.toMatchObject({ name: 'AbortError' }); + } + + await vi.waitFor(() => { + expect( + events + .filter((event) => event.type === 'prompt_cancelled') + .map((event) => event.promptId), + ).toEqual(['prompt-immediate-1', 'prompt-immediate-2']); + }); + expect(handle.agent.promptCalls).toHaveLength(0); + await bridge.shutdown(); + }); + it('forwards a cancel notification with the routing id', async () => { const handles: ChannelHandle[] = []; const factory: ChannelFactory = async () => { diff --git a/packages/acp-bridge/src/bridge.ts b/packages/acp-bridge/src/bridge.ts index 0c25a6d946e..9f48bdd10c7 100644 --- a/packages/acp-bridge/src/bridge.ts +++ b/packages/acp-bridge/src/bridge.ts @@ -101,6 +101,7 @@ import { LOAD_REPLAY_MODE_META_KEY, LOAD_REPLAY_PAGE_SIZE_META_KEY, LOAD_REPLAY_VERSION, + PROMPT_CANCEL_METHOD, TODO_STOP_GUARD_QUEUE_RELEASE_METHOD, } from './bridgeTypes.js'; import { getChannelStartupProfileAttributes } from './channel-startup-profile.js'; @@ -590,16 +591,8 @@ interface SessionEntry { errorKind?: string; }; retryAllowed: boolean; - /** - * Per-prompt "already broadcast `prompt_cancelled`" latch. The explicit - * `cancelSession` route and the `sendPrompt` abort path (originator SSE - * drop) can both fire for the same active prompt — e.g. a client POSTs - * /cancel then immediately closes its socket. Without dedup, peers - * receive two `prompt_cancelled` frames for one turn. Reset to `false` - * when the **next prompt starts** (the latch is per-prompt); set `true` - * on the first broadcast. - */ - cancelBroadcast?: boolean; + /** Prompt id whose `prompt_cancelled` event has already been broadcast. */ + cancelBroadcastPromptId?: string; /** * Count of times `spawnOrAttach` has returned `attached: true` for * this entry — i.e. a second-or-subsequent client claimed this @@ -982,10 +975,9 @@ function broadcastPromptCancelled( /** * Dedup wrapper around {@link broadcastPromptCancelled}. Broadcasts at - * most once per active prompt by latching `entry.cancelBroadcast`, so the + * most once per active prompt by recording its id, so the * `cancelSession` route and the `sendPrompt` abort path can't both emit a * `prompt_cancelled` for a single turn (POST /cancel then socket close). - * The latch is reset when the next prompt starts. */ function broadcastPromptCancelledOnce( entry: SessionEntry, @@ -994,13 +986,15 @@ function broadcastPromptCancelledOnce( originatorClientId: string | undefined, reason?: 'forward_failed', ): void { - if (entry.cancelBroadcast) { + if (promptId !== undefined && entry.cancelBroadcastPromptId === promptId) { writeStderrLine( - `broadcastPromptCancelledOnce: suppressed duplicate cancel for session ${sessionId} (latch already set)`, + `broadcastPromptCancelledOnce: suppressed duplicate cancel for session ${sessionId} prompt=${promptId}`, ); return; } - entry.cancelBroadcast = true; + if (promptId !== undefined) { + entry.cancelBroadcastPromptId = promptId; + } broadcastPromptCancelled( entry, sessionId, @@ -1800,6 +1794,73 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { // daemon. Cleared in the `finally` of the creator. let inFlightChannelSpawn: Promise | undefined; const byId = new Map(); + const forwardRunningPromptCancel = async ( + entry: SessionEntry, + pending: PendingPromptEntry, + notification: CancelNotification, + ): Promise => { + if (pending.cancelForwardInitial) { + return pending.cancelForwardInitial; + } + const initial = (async () => { + try { + const extension = entry.connection + .extMethod(PROMPT_CANCEL_METHOD, notification) + .then((result) => ({ kind: 'result' as const, result })); + const outcome = await Promise.race([ + extension, + getTransportClosedReject(entry), + ...(pending.cancelForwardDeadline + ? [ + pending.cancelForwardDeadline.then(() => ({ + kind: 'deadline' as const, + })), + ] + : []), + ]); + if (outcome.kind === 'deadline') return; + const { result } = outcome; + if (typeof result['cancelled'] !== 'boolean') { + throw new Error( + `${PROMPT_CANCEL_METHOD} returned an invalid acknowledgement`, + ); + } + } catch (error) { + if ( + (typeof error === 'object' && + error !== null && + 'code' in error && + error.code === -32601) || + isNotCurrentlyGeneratingCancelError(error) + ) { + await Promise.race([ + entry.connection.cancel(notification), + getTransportClosedReject(entry), + ...(pending.cancelForwardDeadline + ? [pending.cancelForwardDeadline] + : []), + ]); + return; + } + throw error; + } + })().catch((error) => { + if (pending.cancelForwardInitial === initial) { + delete pending.cancelForwardInitial; + } + throw error; + }); + pending.cancelForwardInitial = initial; + // The same-revision extension resolves only after cancellation is handled + // (or the target prompt has already settled). ACP-compatible custom agents + // that do not implement it receive one standard session/cancel notification. + // The FIFO tail awaits this promise so no extension request remains in flight + // when prompt ownership advances, except when the prompt deadline invokes the + // documented DAEMON-003 overlap policy. + pending.cancelForwardDrain = initial; + void initial.catch(() => {}); + return initial; + }; const generationRequests = new Map< string, { @@ -5180,6 +5241,10 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { // The race consumer may not be attached yet (or ever, for a queued // prompt that never dispatches) — keep the rejection handled. deadlinePromise.catch(() => {}); + pendingEntry.cancelForwardDeadline = deadlinePromise.then( + () => undefined, + () => undefined, + ); const onDeadline = () => { if (pendingEntry.terminalPublished) return; const deadlineErr = new PromptDeadlineExceededError(deadlineMs); @@ -5373,7 +5438,6 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { // // Retry: skip echo — the original user_message_chunk is already // in the transcript from the first attempt. - entry.cancelBroadcast = false; // Continuations carry no user prompt to echo (empty `prompt`); // the original user_message_chunk is already in the transcript. if (!isRetry && !isContinue) { @@ -5388,6 +5452,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { settleActivePromptState(entry, pendingEntry.promptId); throw echoErr; } + pendingEntry.dispatched = true; const promptPromise = entry.connection .prompt(promptRequest) .finally(() => { @@ -5440,7 +5505,7 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { // onDeadline already published the terminal and // aborted the prompt — the abort listener (onAbort) // ran synchronously and handled the cancel broadcast - // + connection.cancel. Nothing to compensate. + // and cancellation handshake. Nothing to compensate. return; } if ( @@ -5464,11 +5529,6 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { 'forward_failed', ); cancelPendingForSession(sessionId); - entry.connection.cancel({ sessionId }).catch((err) => { - writeStderrLine( - `[pending-prompt] cancel forward failed after prompt abort session=${sessionId}: ${extractErrorMessage(err)}`, - ); - }); }, ) .catch(() => {}); @@ -5485,11 +5545,15 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { originatorClientId, ); cancelPendingForSession(sessionId); - entry.connection.cancel({ sessionId }).catch((err) => { - writeStderrLine( - `[pending-prompt] cancel forward failed after removePendingPrompt session=${sessionId}: ${extractErrorMessage(err)}`, - ); - }); + if (byId.get(sessionId) === entry) { + void forwardRunningPromptCancel(entry, pendingEntry, { + sessionId, + }).catch((err) => { + writeStderrLine( + `[pending-prompt] cancel forward failed after removePendingPrompt session=${sessionId}: ${extractErrorMessage(err)}`, + ); + }); + } }; if (abortSignal.aborted) { onAbort(); @@ -5539,9 +5603,17 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { ); // Tail swallows failures so subsequent prompts still run. The caller // still sees rejections on its own `result` reference. + const drainCancelForwarding = async (): Promise => { + try { + await pendingEntry.cancelForwardDrain; + } catch { + // The initiating mutation already reports or logs forwarding + // failures. The queue only needs to fence any in-flight write. + } + }; entry.promptQueue = result.then( - () => undefined, - () => undefined, + drainCancelForwarding, + drainCancelForwarding, ); result .finally(() => { @@ -5637,6 +5709,9 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { entry, context?.clientId, ); + const runningPrompt = entry.pendingPromptList.find( + (pending) => pending.state === 'running' && !pending.terminalPublished, + ); // Broadcast `prompt_cancelled` so other SSE-subscribed clients see // the cancel as a first-class event rather than inferring it from // the absence of further `agent_message_chunk` frames. Mirrors @@ -5656,14 +5731,13 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { // user-voted); this top-level `prompt_cancelled` carries the // cancelling client so peer UIs can attribute it. // - // `...Once` dedups against the `sendPrompt` abort path so a client - // that POSTs /cancel and then drops its socket doesn't emit two - // `prompt_cancelled` frames for the same turn. The latch resets at - // the next prompt start, so a later turn still broadcasts. + // `...Once` dedups against the `sendPrompt` abort path by prompt id, so + // a client that POSTs /cancel and then drops its socket doesn't emit two + // `prompt_cancelled` frames for the same turn. broadcastPromptCancelledOnce( entry, sessionId, - entry.activePromptId, + entry.activePromptId ?? runningPrompt?.promptId, cancelOriginatorClientId, ); // ACP spec: cancelling a prompt MUST resolve outstanding @@ -5696,6 +5770,21 @@ export function createAcpSessionBridge(opts: BridgeOptions): AcpSessionBridge { 'session.id': sessionId, }, async () => { + if (runningPrompt) { + const forwarding = + runningPrompt.dispatched === true && + entry.activePromptId === runningPrompt.promptId + ? forwardRunningPromptCancel(entry, runningPrompt, notif) + : Promise.resolve(); + runningPrompt.abortController.abort( + new DOMException( + 'Prompt cancelled before dispatch', + 'AbortError', + ), + ); + await forwarding; + return; + } try { await entry.connection.cancel(notif); } catch (err) { diff --git a/packages/acp-bridge/src/bridgeTypes.ts b/packages/acp-bridge/src/bridgeTypes.ts index 663ddc3d1d2..c42070f7d1b 100644 --- a/packages/acp-bridge/src/bridgeTypes.ts +++ b/packages/acp-bridge/src/bridgeTypes.ts @@ -545,6 +545,9 @@ export const MID_TURN_QUEUE_DRAIN_METHOD = 'craft/drainMidTurnQueue'; export const TODO_STOP_GUARD_QUEUE_RELEASE_METHOD = 'craft/todoStopGuardQueueReleased'; +/** Parent-to-agent request that acknowledges prompt cancellation handling. */ +export const PROMPT_CANCEL_METHOD = 'craft/cancelPendingPrompt'; + /** * Reverse tool channel marker (issue #5626, Phase 2). The parent serve process * stamps this boolean on a client-hosted (extension) MCP server's @@ -601,6 +604,14 @@ export interface PendingPromptEntry { * later publish attempts for the same prompt are suppressed. */ terminalPublished?: boolean; + /** Cancellation handshake; duplicate callers await rather than resend it. */ + cancelForwardInitial?: Promise; + /** Full cancellation handshake, used to fence the next FIFO dispatch. */ + cancelForwardDrain?: Promise; + /** Releases the cancellation fence when the prompt deadline expires. */ + cancelForwardDeadline?: Promise; + /** True after the prompt request has been handed to the ACP connection. */ + dispatched?: boolean; /** * Set when `removePendingPrompt` cancels a RUNNING prompt. The entry * stays on `pendingPromptList` (hidden from `getPendingPrompts`) until diff --git a/packages/acp-bridge/src/internal/testUtils.ts b/packages/acp-bridge/src/internal/testUtils.ts index 41a7627d773..66aad392223 100644 --- a/packages/acp-bridge/src/internal/testUtils.ts +++ b/packages/acp-bridge/src/internal/testUtils.ts @@ -39,6 +39,7 @@ import * as path from 'node:path'; import { AgentSideConnection, PROTOCOL_VERSION, + RequestError, ndJsonStream, } from '@agentclientprotocol/sdk'; import type { @@ -62,8 +63,9 @@ import type { SetSessionModeResponse, } from '@agentclientprotocol/sdk'; import { createAcpSessionBridge } from '../bridge.js'; +import { isNotCurrentlyGeneratingCancelError } from '../bridgeErrors.js'; import type { BridgeOptions } from '../bridgeOptions.js'; -import type { AcpSessionBridge } from '../bridgeTypes.js'; +import { PROMPT_CANCEL_METHOD, type AcpSessionBridge } from '../bridgeTypes.js'; import type { AcpChannel } from '../channel.js'; // Workspace fixtures must round-trip through `path.resolve` so the @@ -119,6 +121,8 @@ export interface FakeAgentOpts { self: FakeAgent, ) => Promise | PromptResponse; cancelImpl?: (p: CancelNotification, self: FakeAgent) => Promise | void; + /** Make the fake expose only standard ACP cancellation. */ + promptCancelExtension?: boolean; /** * Custom `newSession` handler. Default returns a synthesized id (see * `newSession` below). Used by tests that need to exercise the @@ -234,6 +238,29 @@ export class FakeAgent implements Agent { params: Record, ): Promise> { this.extMethodCalls.push({ method, params }); + if (method === PROMPT_CANCEL_METHOD) { + if (this.opts.promptCancelExtension === false) { + throw RequestError.methodNotFound(method); + } + const sessionId = params['sessionId']; + if (typeof sessionId !== 'string') { + throw new Error('Invalid or missing sessionId'); + } + let delayMs = 1; + while (true) { + try { + await this.cancel({ sessionId }); + return { cancelled: true }; + } catch (error) { + if (!isNotCurrentlyGeneratingCancelError(error)) throw error; + } + await new Promise((resolve) => { + const timer = setTimeout(resolve, delayMs); + timer.unref(); + }); + delayMs = Math.min(delayMs * 2, 100); + } + } if (this.opts.extMethodImpl) { return this.opts.extMethodImpl(method, params, this); } diff --git a/packages/cli/src/acp-integration/acpAgent.test.ts b/packages/cli/src/acp-integration/acpAgent.test.ts index c111f8ccabe..5a2e8618010 100644 --- a/packages/cli/src/acp-integration/acpAgent.test.ts +++ b/packages/cli/src/acp-integration/acpAgent.test.ts @@ -849,6 +849,7 @@ import { buildAuthMethods } from './authMethods.js'; import { CHANNEL_STARTUP_PROFILE_META_KEY, CHANNEL_STARTUP_PROFILE_VERSION, + PROMPT_CANCEL_METHOD, TODO_STOP_GUARD_QUEUE_RELEASE_METHOD, } from '@qwen-code/acp-bridge/bridgeTypes'; import { @@ -1478,8 +1479,9 @@ describe('QwenAgent MCP SSE/HTTP support', () => { rewindToTurn: ReturnType; getRewindableUserTurnCount: ReturnType; clearTodoStopGuardTrust: ReturnType; - releaseTodoStopGuardQueuedPromptWait: ReturnType; + cancelPendingPrompt: ReturnType; prompt: ReturnType; + releaseTodoStopGuardQueuedPromptWait: ReturnType; } | undefined; let processExitSpy: MockInstance; @@ -1681,6 +1683,7 @@ describe('QwenAgent MCP SSE/HTTP support', () => { _meta: { keep: true }, }, invocation, + expect.any(AbortSignal), ); mockConnectionState.resolve(); await agentPromise; @@ -1764,6 +1767,7 @@ describe('QwenAgent MCP SSE/HTTP support', () => { _meta: { keep: true }, }, undefined, + expect.any(AbortSignal), ); mockConnectionState.resolve(); await agentPromise; @@ -2745,6 +2749,58 @@ describe('QwenAgent MCP SSE/HTTP support', () => { await agentPromise; }); + it('acknowledges prompt cancellation after the tracked prompt settles', async () => { + const sessionId = '11111111-1111-1111-1111-111111111111'; + await setupSessionMocks(sessionId); + const { agent, agentPromise } = await bootAcpAgent(); + await agent.newSession({ cwd: '/tmp', mcpServers: [] }); + let finishPrompt: ((value: unknown) => void) | undefined; + lastSessionMock?.prompt.mockImplementation( + () => + new Promise((resolve) => { + finishPrompt = resolve; + }), + ); + const prompt = agent.prompt({ sessionId, prompt: [] }); + + await vi.waitFor(() => expect(lastSessionMock?.prompt).toHaveBeenCalled()); + const cancellationSignal = lastSessionMock?.prompt.mock.calls[0]?.[2] as + | AbortSignal + | undefined; + + let cancellationSettled = false; + const cancellation = agent + .extMethod(PROMPT_CANCEL_METHOD, { sessionId }) + .finally(() => { + cancellationSettled = true; + }); + await vi.waitFor(() => expect(cancellationSignal?.aborted).toBe(true)); + expect(cancellationSettled).toBe(false); + expect(lastSessionMock?.cancelPendingPrompt).not.toHaveBeenCalled(); + + finishPrompt?.({ stopReason: 'cancelled' }); + await expect(cancellation).resolves.toEqual({ cancelled: true }); + await prompt; + + mockConnectionState.resolve(); + await agentPromise; + }); + + it('acknowledges cancellation as a no-op when no prompt call is active', async () => { + const sessionId = '11111111-1111-1111-1111-111111111111'; + await setupSessionMocks(sessionId); + const { agent, agentPromise } = await bootAcpAgent(); + await agent.newSession({ cwd: '/tmp', mcpServers: [] }); + + await expect( + agent.extMethod(PROMPT_CANCEL_METHOD, { sessionId }), + ).resolves.toEqual({ cancelled: false }); + expect(lastSessionMock?.cancelPendingPrompt).not.toHaveBeenCalled(); + + mockConnectionState.resolve(); + await agentPromise; + }); + it('reconnects an MCP server in every live non-pooled runtime', async () => { const server = { command: 'node', args: ['server.js'] }; const workspaceDiscover = vi.fn().mockResolvedValue(undefined); diff --git a/packages/cli/src/acp-integration/acpAgent.ts b/packages/cli/src/acp-integration/acpAgent.ts index e7473ede0ef..043d7b00120 100644 --- a/packages/cli/src/acp-integration/acpAgent.ts +++ b/packages/cli/src/acp-integration/acpAgent.ts @@ -296,6 +296,7 @@ import { LOAD_REPLAY_MODE_META_KEY, LOAD_REPLAY_PAGE_SIZE_META_KEY, LOAD_REPLAY_VERSION, + PROMPT_CANCEL_METHOD, TODO_STOP_GUARD_QUEUE_RELEASE_METHOD, type ClientMcpOverWsRuntimeConfig, type BridgeLoadReplayEnvelope, @@ -3003,8 +3004,14 @@ interface PendingMcpAuthentication { }>; } +interface ActivePromptCall { + controller: AbortController; + settled: Promise; +} + class QwenAgent implements Agent { private sessions: Map = new Map(); + private activePromptCalls = new Map>(); private workspaceMcpDiscoveryConfig: Config | undefined; private workspaceMcpDiscoveryPromise: Promise | undefined; private workspaceMcpDiscoveryError: string | undefined; @@ -4443,7 +4450,32 @@ class QwenAgent implements Agent { 'Invalid trusted ACP invocation context', ); } - return session.prompt(sanitizedParams, invocationContext); + let settleCall = () => {}; + const call: ActivePromptCall = { + controller: new AbortController(), + settled: new Promise((resolve) => { + settleCall = resolve; + }), + }; + let calls = this.activePromptCalls.get(params.sessionId); + if (!calls) { + calls = new Set(); + this.activePromptCalls.set(params.sessionId, calls); + } + calls.add(call); + try { + return await session.prompt( + sanitizedParams, + invocationContext, + call.controller.signal, + ); + } finally { + calls.delete(call); + if (calls.size === 0) { + this.activePromptCalls.delete(params.sessionId); + } + settleCall(); + } } async cancel(params: CancelNotification): Promise { @@ -6685,6 +6717,31 @@ class QwenAgent implements Agent { const SESSION_ID_RE = /^[0-9a-fA-F-]{32,36}$/; switch (method) { + case PROMPT_CANCEL_METHOD: { + const sessionId = params['sessionId']; + if (typeof sessionId !== 'string' || sessionId.length === 0) { + throw RequestError.invalidParams( + undefined, + 'Invalid or missing sessionId', + ); + } + const session = this.sessions.get(sessionId); + if (!session) { + throw RequestError.invalidParams( + undefined, + `Session not found for id: ${sessionId}`, + ); + } + const targetedCalls = new Set( + this.activePromptCalls.get(sessionId) ?? [], + ); + if (targetedCalls.size === 0) { + return { cancelled: false }; + } + targetedCalls.forEach((call) => call.controller.abort()); + await Promise.all(Array.from(targetedCalls, (call) => call.settled)); + return { cancelled: true }; + } case TODO_STOP_GUARD_QUEUE_RELEASE_METHOD: { const sessionId = params['sessionId']; if (typeof sessionId !== 'string' || sessionId.length === 0) { diff --git a/packages/cli/src/acp-integration/session/Session.test.ts b/packages/cli/src/acp-integration/session/Session.test.ts index 329cd3ace36..a6e6f6843d7 100644 --- a/packages/cli/src/acp-integration/session/Session.test.ts +++ b/packages/cli/src/acp-integration/session/Session.test.ts @@ -774,6 +774,32 @@ describe('Session', () => { }); }); + it('cancels an admitted call without cancelling a background turn', async () => { + let releaseAdmission!: () => void; + const admission = new Promise((resolve) => { + releaseAdmission = resolve; + }); + mockConfig.assertCanStartTurn = vi.fn().mockReturnValue(admission); + const cancellation = new AbortController(); + + const prompt = session.prompt( + { + sessionId: 'test-session-id', + prompt: [{ type: 'text', text: 'hello' }], + }, + undefined, + cancellation.signal, + ); + await vi.waitFor(() => + expect(mockConfig.assertCanStartTurn).toHaveBeenCalledOnce(), + ); + cancellation.abort(); + releaseAdmission(); + + await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' }); + expect(mockChat.sendMessageStream).not.toHaveBeenCalled(); + }); + it('pins durable cron startup, prompt restart, and stop to the session runtime', async () => { const runtimeDir = path.resolve('runtime', 'cron-session'); const observedStarts: string[] = []; @@ -16418,6 +16444,54 @@ describe('Session', () => { }); } + it('cleans up an admitted retry cancelled during previous-turn drain', async () => { + rebuildSessionWithGuard(); + let releasePreviousTurn!: () => void; + const previousTurn = new Promise((resolve) => { + releasePreviousTurn = resolve; + }); + const cancellation = new AbortController(); + const internals = session as unknown as { + pendingPrompt: AbortController | null; + pendingPromptCompletion: Promise | null; + todoStopGuard: { + hasTrustedUnfinishedState: boolean; + isHardSuspended: boolean; + observeTodoWrite(resultDisplay: unknown, allowArm: boolean): boolean; + }; + }; + internals.todoStopGuard.observeTodoWrite( + { type: 'todo_list', todos: pendingTodos }, + true, + ); + expect(internals.todoStopGuard.hasTrustedUnfinishedState).toBe(true); + internals.pendingPromptCompletion = previousTurn; + + const prompt = session.prompt( + { + sessionId: 'test-session-id', + prompt: [{ type: 'text', text: 'retry after cancellation' }], + _meta: { 'qwen.daemon.retry': true }, + } as Parameters[0], + undefined, + cancellation.signal, + ); + await vi.waitFor(() => { + expect(internals.pendingPrompt).not.toBeNull(); + expect(internals.todoStopGuard.isHardSuspended).toBe(false); + }); + + cancellation.abort(); + releasePreviousTurn(); + + await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' }); + expect(internals.pendingPrompt).toBeNull(); + expect(internals.todoStopGuard.isHardSuspended).toBe(true); + await expect(session.cancelPendingPrompt()).rejects.toThrow( + 'Not currently generating', + ); + }); + function createDeferredAbortStream() { let markStarted!: () => void; const started = new Promise((resolve) => { diff --git a/packages/cli/src/acp-integration/session/Session.ts b/packages/cli/src/acp-integration/session/Session.ts index 82359236c74..e066576f384 100644 --- a/packages/cli/src/acp-integration/session/Session.ts +++ b/packages/cli/src/acp-integration/session/Session.ts @@ -1985,11 +1985,15 @@ export class Session implements SessionContext { async prompt( params: PromptRequest, invocationContext?: InvocationContextV1, + admissionCancellation?: AbortSignal, ): Promise { if (this.closing) { throw RequestError.invalidParams(undefined, 'Session is closing'); } await this.assertCanStartTurn(); + if (admissionCancellation?.aborted) { + return { stopReason: 'cancelled' }; + } const todoStopGuardPreparation = this.#prepareTodoStopGuardForPrompt(params); // After writer admission, install this prompt's AbortController before @@ -1997,7 +2001,20 @@ export class Session implements SessionContext { // targets us. A cancel during admission cannot target this pending prompt. this.pendingPrompt?.abort(); const pendingSend = new AbortController(); + const cancelPendingSend = () => pendingSend.abort(USER_CANCEL_ABORT_REASON); + if (admissionCancellation) { + admissionCancellation.addEventListener('abort', cancelPendingSend, { + once: true, + }); + if (admissionCancellation.aborted) cancelPendingSend(); + } this.pendingPrompt = pendingSend; + const releasePendingSend = () => { + admissionCancellation?.removeEventListener('abort', cancelPendingSend); + if (this.pendingPrompt === pendingSend) { + this.pendingPrompt = null; + } + }; // Abort the previous turn's in-flight follow-up suggestion // generation (if any). Mirrors `pendingPrompt?.abort()` above — @@ -2051,6 +2068,8 @@ export class Session implements SessionContext { // Cancelled while waiting for the previous prompt to finish. if (pendingSend.signal.aborted) { + releasePendingSend(); + this.todoStopGuard.suspend(); return { stopReason: 'cancelled' }; } @@ -2075,7 +2094,7 @@ export class Session implements SessionContext { pendingSend, invocationContext, ); - this.pendingPrompt = null; + releasePendingSend(); // Drain any cron prompts that queued while the prompt was active void this.#drainCronQueue(); void this.#drainNotificationQueue(); @@ -2089,7 +2108,7 @@ export class Session implements SessionContext { } throw error; } finally { - this.pendingPrompt = null; + releasePendingSend(); const shouldDrainAutomaticQueues = todoStopGuardPreparation.drainSupersededAutomaticQueues || this.todoStopGuardDrainAutomaticQueuesWhenIdle || diff --git a/packages/sdk-java/qwencode/QWEN.md b/packages/sdk-java/qwencode/QWEN.md index 0486fecaf03..701cf51db8a 100644 --- a/packages/sdk-java/qwencode/QWEN.md +++ b/packages/sdk-java/qwencode/QWEN.md @@ -1,377 +1,25 @@ # Qwen Code Java SDK -## Project Overview +This package publishes `com.alibaba:qwencode-sdk:0.1.0-alpha` and requires +Java 11 or newer. Java 8 users must remain on `0.0.3-alpha`. -The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications. +The recommended API is the Java 11 daemon transport in +`com.alibaba.qwen.code.daemon`. It talks to `qwen serve` through REST and SSE, +creates thread-scoped sessions by default, fails closed without a reliable +prompt terminal, and uses periodic heartbeats when the daemon advertises them. -**Context Information:** +The experimental stdio API remains in `com.alibaba.qwen.code.cli` for source +compatibility. The daemon package is intentionally independent of its process +transport, DTOs, sessions, and global executor. -- Current Date: Monday 5 January 2026 -- Operating System: darwin -- Working Directory: /Users/weigeng/repos/qwen-code/packages/sdk-java - -## Project Details - -- **Group ID**: com.alibaba -- **Artifact ID**: qwencode-sdk (as per pom.xml) -- **Version**: 0.0.1-SNAPSHOT -- **Packaging**: JAR -- **Java Version**: 1.8+ (source and target) -- **License**: Apache-2.0 - -## Architecture - -The SDK follows a layered architecture: - -- **API Layer**: Provides the main entry points through `QwenCodeCli` class with simple static methods for basic usage -- **Session Layer**: Manages communication sessions with the Qwen Code CLI through the `Session` class -- **Transport Layer**: Handles the communication mechanism between the SDK and CLI process (currently using process transport via `ProcessTransport`) -- **Protocol Layer**: Defines data structures for communication based on the CLI protocol -- **Utils**: Common utilities for concurrent execution, timeout handling, and error management - -## Key Components - -### Main Classes - -- `QwenCodeCli`: Main entry point with static methods for simple queries -- `Session`: Manages communication sessions with the CLI -- `Transport`: Abstracts the communication mechanism (currently using process transport) -- `ProcessTransport`: Implementation that communicates via process execution -- `TransportOptions`: Configuration class for transport layer settings -- `SessionEventSimpleConsumers`: High-level event handler for processing responses -- `AssistantContentSimpleConsumers`: Handles different types of content within assistant messages - -### Dependencies - -- **Logging**: ch.qos.logback:logback-classic -- **Utilities**: org.apache.commons:commons-lang3 -- **JSON Processing**: com.alibaba.fastjson2:fastjson2 -- **Testing**: JUnit 5 (org.junit.jupiter:junit-jupiter) - -## Building and Running - -### Prerequisites - -- Java 8 or higher -- Apache Maven 3.6.0 or higher - -### Build Commands +Build and test with Maven: ```bash -# Compile the project -mvn compile - -# Run tests mvn test - -# Package the JAR -mvn package - -# Install to local repository -mvn install - -# Run checkstyle verification mvn checkstyle:check - -# Generate Javadoc -mvn javadoc:javadoc -``` - -### Testing - -The project includes basic unit tests using JUnit 5. The main test class `QwenCodeCliTest` demonstrates how to use the SDK to make simple queries to the Qwen Code CLI. - -### Code Quality - -The project uses Checkstyle for code formatting and style enforcement. The configuration is defined in `checkstyle.xml` and includes rules for: - -- Whitespace and indentation -- Naming conventions -- Import ordering -- Code structure -- Line endings (LF only) -- No trailing whitespace -- 8-space indentation for line wrapping - -## Development Conventions - -### Coding Standards - -- Java 8 language features are supported -- Follow standard Java naming conventions -- Use UTF-8 encoding for source files -- Line endings should be LF (Unix-style) -- No trailing whitespace allowed -- Use 8-space indentation for line wrapping - -### Testing Practices - -- Write unit tests using JUnit 5 -- Test classes should be in the `src/test/java` directory -- Follow the naming convention `*Test.java` for test classes -- Use appropriate assertions to validate functionality - -### Documentation - -- API documentation should follow Javadoc conventions -- Update README files when adding new features -- Include examples in documentation - -## API Reference - -### QwenCodeCli Class - -The main class provides several primary methods: - -- `simpleQuery(String prompt)`: Synchronous method that returns a list of responses -- `simpleQuery(String prompt, TransportOptions transportOptions)`: Synchronous method with custom transport options -- `simpleQuery(String prompt, TransportOptions transportOptions, AssistantContentConsumers assistantContentConsumers)`: Advanced method with custom content consumers -- `newSession()`: Creates a new session with default options -- `newSession(TransportOptions transportOptions)`: Creates a new session with custom options - -### Permission Modes - -The SDK supports different permission modes for controlling tool execution: - -- **`default`**: Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`. Read-only tools execute without confirmation. -- **`plan`**: Blocks all write tools, instructing AI to present a plan first. -- **`auto-edit`**: Auto-approve edit tools (`edit`, `write_file`, `notebook_edit`) while other tools require confirmation. -- **`yolo`**: All tools execute automatically without confirmation. - -### Transport Options - -The `TransportOptions` class allows configuration of how the SDK communicates with the Qwen Code CLI: - -- `pathToQwenExecutable`: Path to the Qwen Code CLI executable -- `cwd`: Working directory for the CLI process -- `model`: AI model to use for the session -- `permissionMode`: Permission mode that controls tool execution -- `env`: Environment variables to pass to the CLI process -- `maxSessionTurns`: Limits the number of conversation turns in a session -- `coreTools`: List of core tools that should be available to the AI -- `excludeTools`: List of tools to exclude from being available to the AI -- `allowedTools`: List of tools that are pre-approved for use without additional confirmation -- `authType`: Authentication type to use for the session -- `includePartialMessages`: Enables receiving partial messages during streaming responses -- `turnTimeout`: Timeout for a complete turn of conversation -- `messageTimeout`: Timeout for individual messages within a turn -- `resumeSessionId`: ID of a previous session to resume -- `otherOptions`: Additional command-line options to pass to the CLI - -### Session Control Features - -- **Session creation**: Use `QwenCodeCli.newSession()` to create a new session with custom options -- **Session management**: The `Session` class provides methods to send prompts, handle responses, and manage session state -- **Session cleanup**: Always close sessions using `session.close()` to properly terminate the CLI process -- **Session resumption**: Use `setResumeSessionId()` in `TransportOptions` to resume a previous session -- **Session interruption**: Use `session.interrupt()` to interrupt a currently running prompt -- **Dynamic model switching**: Use `session.setModel()` to change the model during a session -- **Dynamic permission mode switching**: Use `session.setPermissionMode()` to change the permission mode during a session - -### Thread Pool Configuration - -The SDK uses a thread pool for managing concurrent operations with the following default configuration: - -- **Core Pool Size**: 30 threads -- **Maximum Pool Size**: 100 threads -- **Keep-Alive Time**: 60 seconds -- **Queue Capacity**: 300 tasks (using LinkedBlockingQueue) -- **Thread Naming**: "qwen_code_cli-pool-{number}" -- **Daemon Threads**: false -- **Rejected Execution Handler**: CallerRunsPolicy - -### Session Event Consumers and Assistant Content Consumers - -The SDK provides two key interfaces for handling events and content from the CLI: - -#### SessionEventConsumers Interface - -The `SessionEventConsumers` interface provides callbacks for different types of messages during a session: - -- `onSystemMessage`: Handles system messages from the CLI (receives Session and SDKSystemMessage) -- `onResultMessage`: Handles result messages from the CLI (receives Session and SDKResultMessage) -- `onAssistantMessage`: Handles assistant messages (AI responses) (receives Session and SDKAssistantMessage) -- `onPartialAssistantMessage`: Handles partial assistant messages during streaming (receives Session and SDKPartialAssistantMessage) -- `onUserMessage`: Handles user messages (receives Session and SDKUserMessage) -- `onOtherMessage`: Handles other types of messages (receives Session and String message) -- `onControlResponse`: Handles control responses (receives Session and CLIControlResponse) -- `onControlRequest`: Handles control requests (receives Session and CLIControlRequest, returns CLIControlResponse) -- `onPermissionRequest`: Handles permission requests (receives Session and CLIControlRequest, returns Behavior) - -#### AssistantContentConsumers Interface - -The `AssistantContentConsumers` interface handles different types of content within assistant messages: - -- `onText`: Handles text content (receives Session and TextAssistantContent) -- `onThinking`: Handles thinking content (receives Session and ThinkingAssistantContent) -- `onToolUse`: Handles tool use content (receives Session and ToolUseAssistantContent) -- `onToolResult`: Handles tool result content (receives Session and ToolResultAssistantContent) -- `onOtherContent`: Handles other content types (receives Session and AssistantContent) -- `onUsage`: Handles usage information (receives Session and AssistantUsage) -- `onPermissionRequest`: Handles permission requests (receives Session and CLIControlPermissionRequest, returns Behavior) -- `onOtherControlRequest`: Handles other control requests (receives Session and ControlRequestPayload, returns ControlResponsePayload) - -#### Relationship Between the Interfaces - -**Important Note on Event Hierarchy:** - -- `SessionEventConsumers` is the **high-level** event processor that handles different message types (system, assistant, user, etc.) -- `AssistantContentConsumers` is the **low-level** content processor that handles different types of content within assistant messages (text, tools, thinking, etc.) - -**Processor Relationship:** - -- `SessionEventConsumers` → `AssistantContentConsumers` (SessionEventConsumers uses AssistantContentConsumers to process content within assistant messages) - -**Event Derivation Relationships:** - -- `onAssistantMessage` → `onText`, `onThinking`, `onToolUse`, `onToolResult`, `onOtherContent`, `onUsage` -- `onPartialAssistantMessage` → `onText`, `onThinking`, `onToolUse`, `onToolResult`, `onOtherContent` -- `onControlRequest` → `onPermissionRequest`, `onOtherControlRequest` - -**Event Timeout Relationships:** - -Each event handler method has a corresponding timeout method that allows customizing the timeout behavior for that specific event: - -- `onSystemMessage` ↔ `onSystemMessageTimeout` -- `onResultMessage` ↔ `onResultMessageTimeout` -- `onAssistantMessage` ↔ `onAssistantMessageTimeout` -- `onPartialAssistantMessage` ↔ `onPartialAssistantMessageTimeout` -- `onUserMessage` ↔ `onUserMessageTimeout` -- `onOtherMessage` ↔ `onOtherMessageTimeout` -- `onControlResponse` ↔ `onControlResponseTimeout` -- `onControlRequest` ↔ `onControlRequestTimeout` - -For AssistantContentConsumers timeout methods: - -- `onText` ↔ `onTextTimeout` -- `onThinking` ↔ `onThinkingTimeout` -- `onToolUse` ↔ `onToolUseTimeout` -- `onToolResult` ↔ `onToolResultTimeout` -- `onOtherContent` ↔ `onOtherContentTimeout` -- `onPermissionRequest` ↔ `onPermissionRequestTimeout` -- `onOtherControlRequest` ↔ `onOtherControlRequestTimeout` - -**Default Timeout Values:** - -- `SessionEventSimpleConsumers` default timeout: 180 seconds (Timeout.TIMEOUT_180_SECONDS) -- `AssistantContentSimpleConsumers` default timeout: 60 seconds (Timeout.TIMEOUT_60_SECONDS) - -**Timeout Hierarchy Requirements:** - -For proper operation, the following timeout relationships should be maintained: - -- `onAssistantMessageTimeout` return value should be greater than `onTextTimeout`, `onThinkingTimeout`, `onToolUseTimeout`, `onToolResultTimeout`, and `onOtherContentTimeout` return values -- `onControlRequestTimeout` return value should be greater than `onPermissionRequestTimeout` and `onOtherControlRequestTimeout` return values - -#### Relationship Between the Interfaces - -- `AssistantContentSimpleConsumers` is the default implementation of `AssistantContentConsumers` -- `SessionEventSimpleConsumers` is the concrete implementation that combines both interfaces and depends on an `AssistantContentConsumers` instance to handle content within assistant messages -- The timeout methods in `SessionEventConsumers` now include the message object as a parameter (e.g., `onSystemMessageTimeout(Session session, SDKSystemMessage systemMessage)`) - -Event processing is subject to the timeout settings configured in `TransportOptions` and `SessionEventConsumers`. For detailed timeout configuration options, see the "Timeout" section above. - -## Usage Examples - -The SDK includes several example files in `src/test/java/com/alibaba/qwen/code/cli/example/` that demonstrate different aspects of the API: - -### Basic Usage - -- `QuickStartExample.java`: Demonstrates simple query usage, transport options configuration, and streaming content handling - -### Session Control - -- `SessionExample.java`: Shows session control features including permission mode changes, model switching, interruption, and event handling - -### Configuration - -- `ThreadPoolConfigurationExample.java`: Shows how to configure the thread pool used by the SDK - -## Error Handling - -The SDK provides specific exception types for different error scenarios: - -- `SessionControlException`: Thrown when there's an issue with session control (creation, initialization, etc.) -- `SessionSendPromptException`: Thrown when there's an issue sending a prompt or receiving a response -- `SessionClosedException`: Thrown when attempting to use a closed session - -## Project Structure - -``` -src/ -├── example/ -│ └── java/ -│ └── com/ -│ └── alibaba/ -│ └── qwen/ -│ └── code/ -│ └── example/ -├── main/ -│ └── java/ -│ └── com/ -│ └── alibaba/ -│ └── qwen/ -│ └── code/ -│ └── cli/ -│ ├── QwenCodeCli.java -│ ├── protocol/ -│ ├── session/ -│ ├── transport/ -│ └── utils/ -└── test/ - ├── java/ - │ └── com/ - │ └── alibaba/ - │ └── qwen/ - │ └── code/ - │ └── cli/ - │ ├── QwenCodeCliTest.java - │ ├── session/ - │ │ └── SessionTest.java - │ └── transport/ - │ ├── PermissionModeTest.java - │ └── process/ - │ └── ProcessTransportTest.java - └── temp/ +mvn package ``` -## Configuration Files - -- `pom.xml`: Maven build configuration and dependencies -- `checkstyle.xml`: Code style and formatting rules -- `.editorconfig`: Editor configuration settings - -## FAQ / Troubleshooting - -### Q: Do I need to install the Qwen CLI separately? - -A: No, from v0.1.1, the CLI is bundled with the SDK, so no standalone CLI installation is needed. - -### Q: What Java versions are supported? - -A: The SDK requires Java 1.8 or higher. - -### Q: How do I handle long-running requests? - -A: The SDK includes timeout utilities. You can configure timeouts using the `Timeout` class in `TransportOptions`. - -### Q: Why are some tools not executing? - -A: This is likely due to permission modes. Check your permission mode settings and consider using `allowedTools` to pre-approve certain tools. - -### Q: How do I resume a previous session? - -A: Use the `setResumeSessionId()` method in `TransportOptions` to resume a previous session. - -### Q: Can I customize the environment for the CLI process? - -A: Yes, use the `setEnv()` method in `TransportOptions` to pass environment variables to the CLI process. - -### Q: What happens if the CLI process crashes? - -A: The SDK will throw appropriate exceptions. Make sure to handle `SessionControlException` and implement retry logic if needed. - -## Maintainers - -- **Developer**: skyfire (gengwei.gw(at)alibaba-inc.com) -- **Organization**: Alibaba Group +Use the package `README.md` for API examples, compatibility notes, reliability +semantics, and known alpha limitations. The implementation design is tracked +in `docs/design/java-daemon-sdk-alpha.md` at the repository root. diff --git a/packages/sdk-java/qwencode/README.md b/packages/sdk-java/qwencode/README.md index 1934c4b5abc..44eae3d10c4 100644 --- a/packages/sdk-java/qwencode/README.md +++ b/packages/sdk-java/qwencode/README.md @@ -1,18 +1,18 @@ # Qwen Code Java SDK -The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications. +The Qwen Code Java SDK provides a recommended daemon transport for `qwen serve` and retains the experimental legacy stdio API for compatibility. Both APIs ship in the same `com.alibaba:qwencode-sdk` artifact. ## Requirements -- Java >= 1.8 -- Maven >= 3.6.0 (for building from source) -- qwen-code >= 0.5.0 +- Java >= 11 for `0.1.0-alpha` +- Maven >= 3.9.2 when building or publishing this SDK from source +- A compatible `qwen serve` for the daemon API, or qwen-code >= 0.5.0 for the legacy stdio API ### Dependencies -- **Logging**: ch.qos.logback:logback-classic +- **Logging API**: org.slf4j:slf4j-api (choose an SLF4J provider in your application) - **Utilities**: org.apache.commons:commons-lang3 -- **JSON Processing**: com.alibaba.fastjson2:fastjson2 +- **JSON Processing**: Fastjson2 for encoding and Jackson Core for strict decoding - **Testing**: JUnit 5 (org.junit.jupiter:junit-jupiter) ## Installation @@ -23,14 +23,14 @@ Add the following dependency to your Maven `pom.xml`: com.alibaba qwencode-sdk - {$version} + 0.1.0-alpha ``` Or if using Gradle, add to your `build.gradle`: ```gradle -implementation 'com.alibaba:qwencode-sdk:{$version}' +implementation 'com.alibaba:qwencode-sdk:0.1.0-alpha' ``` ## Building and Running @@ -51,9 +51,63 @@ mvn package mvn install ``` -## Quick Start +### Real daemon E2E from source -The simplest way to use the SDK is through the `QwenCodeCli.simpleQuery()` method: +Run the real-daemon Java integration tests from the repository root after building both the workspaces and the root CLI bundle: + +```bash +npm run build +npm run bundle +npx tsx scripts/run-java-daemon-sdk-e2e.ts +``` + +`npm run build` alone does not refresh `dist/cli.js`; the E2E harness launches that bundle and fails with an explicit prerequisite error when it is missing. + +## Recommended daemon API + +Start `qwen serve`, then create an independent thread-scoped session. `promptText` returns only after a matching `turn_complete`; incomplete streams fail with `PromptOutcomeIndeterminateException` rather than returning partial text as success. + +For the lifecycle guarantees assumed by `0.1.0-alpha`, use the qwen-code build released from the same source revision as the SDK. The daemon must contain the idempotent per-client detach ledger from [#7386](https://github.com/QwenLM/qwen-code/pull/7386), the per-epoch terminal guarantee from [#7400](https://github.com/QwenLM/qwen-code/pull/7400), and this release's acknowledged admission cancellation plus FIFO cancel-drain fence. The #7400 commit alone is not sufficient: a same-wire daemon can acknowledge cancel before agent dispatch without stopping the admitted prompt, or let an unacknowledged session-scoped cancel reach a queued successor. The bundled ACP child uses one acknowledged admission-aware cancellation handshake; a custom standards-compliant ACP child without that extension receives one standard `session/cancel` notification. Feature negotiation cannot distinguish older same-wire daemon builds, so the SDK fails closed rather than reporting partial output as success. + +The bundled cancellation handshake deliberately waits for the targeted prompt call to settle before the daemon dispatches its queued successor. It has no timeout that merely acknowledges cancellation: doing so could let a late session-scoped cancel reach the next prompt. If a provider, tool, or custom integration ignores its `AbortSignal` indefinitely, the cancel mutation can therefore remain outcome-unknown and that session must not be reused. Treat a formal prompt terminal received within the caller's observation boundary as authoritative; otherwise close or destroy the session after observation fails. Recovering a wedged shared ACP child without disturbing its sibling sessions requires stronger runtime isolation and is outside this alpha contract. + +```java +import com.alibaba.qwen.code.daemon.DaemonClient; +import com.alibaba.qwen.code.daemon.DaemonSessionClient; +import com.alibaba.qwen.code.daemon.PromptTextResult; +import java.net.URI; + +try (DaemonClient daemon = DaemonClient.builder() + .baseUri(URI.create("http://127.0.0.1:4170")) + .build(); + DaemonSessionClient session = daemon.createSession()) { + PromptTextResult result = session.promptText("Explain this repository"); + System.out.println(result.getText()); +} +``` + +If `qwen serve` requires authentication, add +`.bearerToken(System.getenv("QWEN_SERVER_TOKEN"))` to the `DaemonClient` +builder. The SDK sends the bearer on REST and SSE requests and never puts it in +the URL. + +Use `startPrompt` with a `PromptObserver` when you need ordered text, thought, tool, usage, permission, and raw event callbacks. Its `acceptanceFuture()` and `completionFuture()` views separately expose daemon admission and the reliable turn terminal. `respondToPermission()` returns `false` when the request was already resolved or no longer pending. Cancelling the future views does not cancel the daemon prompt; use `cancelActivePrompt()` for the session-level daemon cancel operation and still wait for the matching terminal. A cooperative cancellation completes with `turn_complete` and `stopReason=cancelled`; `promptText()` returns its `PromptTextResult`, so callers that distinguish cancellation must inspect `result.getTerminal().getStopReason()`. If the agent or provider fails while cancelling, the daemon can instead publish `turn_error`, which makes `promptText()` throw `PromptTurnException`. + +When cancellation, deadline, teardown, or agent settlement race, the daemon's exactly-once latch publishes the first formal terminal and suppresses later candidates. Always branch on the received terminal itself; the last control mutation sent by the client does not determine the terminal kind or error code. + +The SSE transport sends `Accept-Encoding: identity` and `Last-Event-ID`, validates framing and event IDs, deduplicates replay, and reconnects only the SSE GET. Prompt and other mutation requests are never retried automatically. HTTP 408 and 5xx responses to prompt admission, session creation, permission, cancel, heartbeat, detach, or delete are reported as outcome-unknown because they do not prove that the daemon rejected the mutation. Finite response bodies and SSE observation have independent deadlines. + +Creation-time model selection is intentionally not exposed by the Java daemon SDK API in this alpha. The daemon reports a rejected `modelServiceId` only as an SSE event emitted before the create response, while this SDK opens its stream from the later prompt-admission watermark. Until the daemon returns a definitive create result or the SDK owns a separate session-event subscription from `Last-Event-ID: 0`, use the daemon's configured default model. + +`PromptRequest.Builder.deadline(Duration)` requests a daemon-enforced prompt deadline and is accepted only when the daemon advertises `prompt_absolute_deadline`; otherwise the SDK fails before sending the prompt. The value must be between 1 and 2,147,483,647 milliseconds, matching the daemon's Node timer range. This is separate from `observationTimeout(Duration)`, which only bounds local SSE observation and never sends a cancel mutation. + +Before creating a session, the SDK requires the daemon to advertise the REST transport and `session_scope_override`; this prevents an older daemon from silently ignoring the requested `thread` scope and attaching the client to a shared session. When `client_heartbeat` is advertised, an open session sends a fresh heartbeat every minute so the daemon does not reap an otherwise idle client. Set `heartbeatInterval(Duration.ZERO)` on the `DaemonClient` builder to disable this behavior, or choose a different positive interval. A heartbeat is never retried; the next scheduled heartbeat is a separate keepalive. Prompt observation is bounded to 32 concurrent prompts per client by default and can be adjusted with `maximumConcurrentPrompts`. Admission and terminal future callbacks run away from transport workers; callbacks that remain blocked consume bounded publication capacity. SSE stream cleanup is also bounded, and a close that remains blocked retains its cleanup reservation. Either condition can cause a later `startPrompt` to fail with `DaemonClientCapacityException` rather than dropping a timeout close or growing threads and queued work without limit. + +An indeterminate completion is an outcome boundary, not a session-reuse boundary. After `PromptAdmissionUnknownException` or `PromptOutcomeIndeterminateException`, that `DaemonSessionClient` permanently rejects further prompts even if local stream cleanup later succeeds; close or destroy the session instead. An observation timeout is published without waiting forever for a blocked stream close, while cleanup continues asynchronously and retains bounded client capacity until it finishes. + +## Legacy stdio API + +The existing `com.alibaba.qwen.code.cli` API remains available: ```java public static void runSimpleExample() { @@ -126,17 +180,24 @@ public static void runStreamingExample() { other examples see src/test/java/com/alibaba/qwen/code/cli/example +## Java 11 migration and alpha limits + +`0.1.0-alpha` raises the minimum Java version for the whole artifact from 8 to 11. Java 8 applications must remain on `0.0.3-alpha`. Logback is no longer a runtime dependency; add the SLF4J provider your application uses. + +This alpha deliberately fails closed when it cannot prove a prompt terminal. It does not guarantee exactly-once execution across daemon restarts, automatic epoch recovery, snapshot/resync, persisted cursors, or true prompt-ID-targeted cancellation. `prompt_cancelled` and queue events are advisory; only matching `turn_complete` and `turn_error` are terminal. + +If session creation has an ambiguous transport outcome, the daemon may retain a session whose ID never reached the caller. The SDK does not retry creation and cannot detach that unknown session; daemon-side lifecycle reaping is the recovery boundary. + ## Architecture -The SDK follows a layered architecture: +The artifact contains two isolated implementations: + +- **Daemon API**: `DaemonClient` and `DaemonSessionClient` use REST mutations plus resumable SSE and own bounded HTTP, prompt, maintenance, and timer resources. +- **Legacy stdio API**: `QwenCodeCli`, `Session`, and `ProcessTransport` manage a child CLI process using the existing CLI protocol DTOs and utilities. -- **API Layer**: Provides the main entry points through `QwenCodeCli` class with simple static methods for basic usage -- **Session Layer**: Manages communication sessions with the Qwen Code CLI through the `Session` class -- **Transport Layer**: Handles the communication mechanism between the SDK and CLI process (currently using process transport via `ProcessTransport`) -- **Protocol Layer**: Defines data structures for communication based on the CLI protocol -- **Utils**: Common utilities for concurrent execution, timeout handling, and error management +The daemon implementation does not reuse the legacy process transport, session model, DTOs, or global executor. -## Key Features +## Legacy stdio features ### Permission Modes @@ -284,7 +345,7 @@ The SDK provides specific exception types for different error scenarios: ### Q: What Java versions are supported? -A: The SDK requires Java 1.8 or higher. +A: `0.1.0-alpha` requires Java 11 or higher. Java 8 users must remain on `0.0.3-alpha`. ### Q: How do I handle long-running requests? diff --git a/packages/sdk-java/qwencode/RELEASE.md b/packages/sdk-java/qwencode/RELEASE.md index 520ea1e7d13..8ed7e03fa08 100644 --- a/packages/sdk-java/qwencode/RELEASE.md +++ b/packages/sdk-java/qwencode/RELEASE.md @@ -1,6 +1,51 @@ # Release Notes -### Changes in 0.0.2-alpha +## Changes in 0.1.0-alpha + +### Summary + +This release adds the Java 11 daemon transport to the existing `com.alibaba:qwencode-sdk` artifact. The new `com.alibaba.qwen.code.daemon` API uses `POST` admission watermarks and resumable SSE to avoid returning truncated prompt output as success. The legacy stdio API remains available. + +### Compatibility + +- Minimum Java version: 11 +- Java 8 users must remain on `0.0.3-alpha` +- Applications now select their own SLF4J provider; Logback is test-only +- Fastjson2 and Jackson Core remain implementation dependencies and are absent from daemon public API signatures +- Use the qwen-code build released from the same source revision as the SDK; the daemon must contain [#7386](https://github.com/QwenLM/qwen-code/pull/7386), [#7400](https://github.com/QwenLM/qwen-code/pull/7400), and this release's acknowledged admission cancellation plus FIFO cancel-drain fence + +### Reliability contract + +- Prompt, create, permission, cancel, heartbeat, detach, and delete mutations are not retried automatically +- HTTP 408 and 5xx responses to those mutations remain outcome-unknown +- SSE uses identity encoding, replay cursors, ordered callbacks, duplicate suppression, gap detection, and bounded reconnect +- JSON decoding rejects non-standard syntax and duplicate object keys +- Finite HTTP response bodies and SSE observation are independently deadline-bound +- Session creation fails before mutation unless REST and `session_scope_override` are advertised +- A requested daemon prompt deadline fails before mutation unless `prompt_absolute_deadline` is advertised +- When the daemon advertises `client_heartbeat`, open sessions send periodic + heartbeat mutations until detach or destroy +- Only a matching `turn_complete` or `turn_error` is terminal +- A cooperative cancellation is `turn_complete` with `stopReason=cancelled`; an agent or provider failure during cancellation can instead produce `turn_error`, so callers wait for and inspect the formal terminal +- When cancellation, deadline, teardown, and agent settlement race, the daemon's first formal terminal wins; callers must not infer the outcome from the last control mutation they sent +- Missing terminal, resync, session death, observer failure, timeout, and reconnect exhaustion fail closed +- `close()` attempts detach at most once; only `destroySession()` sends DELETE + +### Known alpha limits + +The SDK does not promise exactly-once prompt execution across daemon restarts, automatic epoch recovery, snapshot/resync, persisted cursors, or true prompt-ID-targeted cancellation. Creation-time model selection is omitted because the current daemon reports rejection only through an SSE event emitted before the create response. An ambiguous create may leave an unidentified session until the daemon reaps it. The acknowledged cancellation handshake intentionally has no acknowledgement-only timeout because that could let a late session-scoped cancel reach the next prompt; a provider or tool that ignores its `AbortSignal` can therefore leave the session unusable until stronger runtime isolation is available. + +### Maven configuration + +```xml + + com.alibaba + qwencode-sdk + 0.1.0-alpha + +``` + +## Changes in 0.0.2-alpha ### Summary @@ -24,7 +69,7 @@ January 14, 2026 ``` -### Changes in 0.0.1-alpha +## Changes in 0.0.1-alpha ### Summary @@ -76,17 +121,15 @@ January 5, 2026 ### Known Issues -1. **CLI Bundling**: From v0.1.1, the CLI is bundled with the SDK, eliminating the need for separate CLI installation. However, users upgrading from earlier versions should remove any standalone CLI installations to avoid conflicts. - -2. **Memory Management**: Long-running sessions with extensive streaming content may consume significant memory. Proper session cleanup using `session.close()` is essential. +1. **Memory Management**: Long-running sessions with extensive streaming content may consume significant memory. Proper session cleanup using `session.close()` is essential. -3. **Thread Pool Configuration**: The default thread pool configuration (30 core, 100 max threads) may need adjustment based on application load and concurrent session requirements. +2. **Thread Pool Configuration**: The legacy stdio API's default thread pool configuration (30 core, 100 max threads) may need adjustment based on application load and concurrent session requirements. -4. **Timeout Configuration**: Users experiencing timeout issues should adjust the `turnTimeout` and `messageTimeout` values in `TransportOptions` based on their specific use cases. +3. **Timeout Configuration**: Legacy stdio users experiencing timeout issues should adjust the `turnTimeout` and `messageTimeout` values in `TransportOptions` based on their specific use cases. -5. **Permission Mode Confusion**: The different permission modes (default, plan, auto-edit, yolo) may cause confusion for new users. Clear documentation and examples are needed to guide users in selecting appropriate permission modes. +4. **Permission Mode Confusion**: The different legacy stdio permission modes (default, plan, auto-edit, yolo) may cause confusion for new users. Clear documentation and examples are needed to guide users in selecting appropriate permission modes. -6. **Environment Variable Limitations**: Environment variables passed to the CLI process may have platform-specific limitations on length and character sets. +5. **Environment Variable Limitations**: Environment variables passed to the legacy stdio CLI process may have platform-specific limitations on length and character sets. ### Maven Build Configuration @@ -94,14 +137,14 @@ The project uses Maven for build management with the following key plugins and c #### Compiler Plugin -- Source and Target: Java 1.8 +- Compiler release: Java 11 - Encoding: UTF-8 #### Dependencies -- Logging: ch.qos.logback:logback-classic +- Logging API: org.slf4j:slf4j-api - Utilities: org.apache.commons:commons-lang3 -- JSON Processing: com.alibaba.fastjson2:fastjson2 +- JSON Processing: Fastjson2 for encoding and Jackson Core for strict decoding - Testing: JUnit 5 (org.junit.jupiter:junit-jupiter) #### Build Plugins @@ -113,19 +156,18 @@ The project uses Maven for build management with the following key plugins and c - **Javadoc Plugin**: Generates and attaches Javadoc JARs - **GPG Plugin**: Signs artifacts for secure publishing to Maven Central -#### Distribution Management +#### Publishing -- Snapshot Repository: https://central.sonatype.com/repository/maven-snapshots/ -- Release Repository: https://central.sonatype.org/service/local/staging/deploy/maven2/ +- Releases: Sonatype Central Publisher Portal through the official Maven plugin ### Deployment Instructions -To deploy a new version of the SDK: +To release this version of the SDK: -1. Update the version in `pom.xml` -2. Run `mvn clean deploy` to build and deploy to Maven Central -3. Ensure GPG signing keys are properly configured -4. Verify the deployment in the Sonatype staging repository +1. Merge the version and release notes to protected `main`. +2. Run the `Release Java SDK` workflow in dry-run mode. +3. Approve the protected production environment and rerun with dry-run disabled. +4. The workflow first pins the verified source with an immutable tag, then signs and publishes the artifacts, waits for Maven Central availability, and creates the GitHub Release. A failed publish can safely resume from the matching tag commit even if `main` has advanced. ### Future Enhancements diff --git a/packages/sdk-java/qwencode/pom.xml b/packages/sdk-java/qwencode/pom.xml index 7defb5926e4..ee840eb5b57 100644 --- a/packages/sdk-java/qwencode/pom.xml +++ b/packages/sdk-java/qwencode/pom.xml @@ -5,12 +5,10 @@ com.alibaba qwencode-sdk jar - 0.0.3-alpha + 0.1.0-alpha qwencode-sdk - The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface - to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications. - - https://maven.apache.org + Java APIs for the Qwen Code daemon transport and legacy CLI process transport. + https://github.com/QwenLM/qwen-code/tree/main/packages/sdk-java/qwencode Apache 2 @@ -22,21 +20,25 @@ https://github.com/QwenLM/qwen-code scm:git:https://github.com/QwenLM/qwen-code.git + scm:git:ssh://git@github.com/QwenLM/qwen-code.git - 1.8 - 1.8 + 11 UTF-8 3.6.0 - 0.8.12 + 0.8.14 5.14.1 1.3.16 + 2.0.17 2.0.60 + 2.22.0 3.13.0 - 0.8.0 - 2.2.1 - 2.9.1 - 1.5 + 3.4.2 + 3.5.4 + 0.11.0 + 3.4.0 + 3.12.0 + 3.2.8 @@ -51,10 +53,16 @@ + + org.slf4j + slf4j-api + ${slf4j-api.version} + ch.qos.logback logback-classic ${logback-classic.version} + test org.apache.commons @@ -66,6 +74,11 @@ fastjson2 ${fastjson2.version} + + com.fasterxml.jackson.core + jackson-core + ${jackson-core.version} + org.junit.jupiter junit-jupiter @@ -75,6 +88,32 @@ + + org.apache.maven.plugins + maven-compiler-plugin + ${maven-compiler-plugin.version} + + + org.apache.maven.plugins + maven-jar-plugin + ${maven-jar-plugin.version} + + + + qwencode.sdk + + + + + + org.apache.maven.plugins + maven-surefire-plugin + ${maven-surefire-plugin.version} + + true + integration + + org.apache.maven.plugins maven-checkstyle-plugin @@ -116,6 +155,8 @@ true central + true + published @@ -149,6 +190,12 @@ org.apache.maven.plugins maven-gpg-plugin ${maven-gpg-plugin.version} + + + --pinentry-mode + loopback + + sign-artifacts @@ -180,14 +227,4 @@ - - - central - https://central.sonatype.com/repository/maven-snapshots/ - - - central - https://central.sonatype.org/service/local/staging/deploy/maven2/ - - diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/CreateSessionRequest.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/CreateSessionRequest.java new file mode 100644 index 00000000000..162fc086b47 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/CreateSessionRequest.java @@ -0,0 +1,83 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** Options for creating a daemon session. */ +public final class CreateSessionRequest { + private final String workspaceCwd; + private final String approvalMode; + private final String sessionScope; + + private CreateSessionRequest(Builder builder) { + this.workspaceCwd = builder.workspaceCwd; + this.approvalMode = builder.approvalMode; + this.sessionScope = builder.sessionScope; + } + + public static Builder builder() { + return new Builder(); + } + + public static CreateSessionRequest defaults() { + return builder().build(); + } + + Map toJson() { + Map result = new LinkedHashMap<>(); + if (workspaceCwd != null) { + result.put("cwd", workspaceCwd); + } + if (approvalMode != null) { + result.put("approvalMode", approvalMode); + } + result.put("sessionScope", sessionScope); + return result; + } + + public static final class Builder { + private String workspaceCwd; + private String approvalMode; + private String sessionScope = "thread"; + + private Builder() { + } + + public Builder workspaceCwd(String workspaceCwd) { + this.workspaceCwd = requireNonBlank(workspaceCwd, "workspaceCwd"); + return this; + } + + public Builder approvalMode(DaemonApprovalMode approvalMode) { + if (approvalMode == null) { + throw new IllegalArgumentException("approvalMode must not be null"); + } + this.approvalMode = approvalMode.getWireValue(); + return this; + } + + public Builder rawApprovalMode(String approvalMode) { + this.approvalMode = requireNonBlank(approvalMode, "approvalMode"); + return this; + } + + public Builder sessionScope(String sessionScope) { + if (!"thread".equals(sessionScope) && !"single".equals(sessionScope)) { + throw new IllegalArgumentException("sessionScope must be thread or single"); + } + this.sessionScope = sessionScope; + return this; + } + + public CreateSessionRequest build() { + return new CreateSessionRequest(this); + } + + private static String requireNonBlank(String value, String name) { + if (value == null || value.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return value; + } + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonApprovalMode.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonApprovalMode.java new file mode 100644 index 00000000000..c91e00a94e3 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonApprovalMode.java @@ -0,0 +1,20 @@ +package com.alibaba.qwen.code.daemon; + +/** Approval modes accepted by the current daemon session API. */ +public enum DaemonApprovalMode { + PLAN("plan"), + DEFAULT("default"), + AUTO_EDIT("auto-edit"), + AUTO("auto"), + YOLO("yolo"); + + private final String wireValue; + + DaemonApprovalMode(String wireValue) { + this.wireValue = wireValue; + } + + public String getWireValue() { + return wireValue; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonCapabilities.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonCapabilities.java new file mode 100644 index 00000000000..7416643b7a7 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonCapabilities.java @@ -0,0 +1,60 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.Collections; +import java.util.List; +import java.util.Map; + +/** Validated capabilities returned by {@code GET /capabilities}. */ +public final class DaemonCapabilities { + private final int version; + private final String mode; + private final List features; + private final List transports; + private final String workspaceCwd; + private final String qwenCodeVersion; + private final Map raw; + + DaemonCapabilities(int version, String mode, List features, + List transports, String workspaceCwd, + String qwenCodeVersion, Map raw) { + this.version = version; + this.mode = mode; + this.features = Collections.unmodifiableList(features); + this.transports = Collections.unmodifiableList(transports); + this.workspaceCwd = workspaceCwd; + this.qwenCodeVersion = qwenCodeVersion; + this.raw = Collections.unmodifiableMap(raw); + } + + public int getVersion() { + return version; + } + + public String getMode() { + return mode; + } + + public List getFeatures() { + return features; + } + + public List getTransports() { + return transports; + } + + public String getWorkspaceCwd() { + return workspaceCwd; + } + + public String getQwenCodeVersion() { + return qwenCodeVersion; + } + + public Map getRaw() { + return raw; + } + + public boolean supports(String feature) { + return features.contains(feature); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonClient.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonClient.java new file mode 100644 index 00000000000..f5f928fa97c --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonClient.java @@ -0,0 +1,753 @@ +package com.alibaba.qwen.code.daemon; + +import java.io.IOException; +import java.io.InputStream; +import java.net.URI; +import java.net.URLEncoder; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.ArrayBlockingQueue; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.Executor; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; +import java.util.concurrent.FutureTask; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.RejectedExecutionException; +import java.util.concurrent.ScheduledExecutorService; +import java.util.concurrent.ScheduledThreadPoolExecutor; +import java.util.concurrent.Semaphore; +import java.util.concurrent.ThreadFactory; +import java.util.concurrent.ThreadPoolExecutor; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.TimeoutException; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicLong; +import java.util.function.Supplier; + +/** Java 11 client for the {@code qwen serve} REST and SSE transport. */ +public final class DaemonClient implements AutoCloseable { + private static final AtomicLong CLIENT_SEQUENCE = new AtomicLong(); + + private final String baseUrl; + private final String bearerToken; + private final Duration requestTimeout; + private final Duration promptObservationTimeout; + private final Duration sseIdleTimeout; + private final int maximumReconnectAttempts; + private final int maximumSseFrameBytes; + private final Duration heartbeatInterval; + private final ExecutorService executor; + private final ExecutorService maintenanceExecutor; + private final ExecutorService futureExecutor; + private final ExecutorService httpExecutor; + private final ExecutorService streamCloseExecutor; + private final ScheduledThreadPoolExecutor scheduler; + private final HttpClient httpClient; + private final Set sessions = ConcurrentHashMap.newKeySet(); + private final Semaphore promptSlots; + private final Semaphore streamLifecycleSlots; + private final Semaphore futurePublicationSlots; + private final AtomicBoolean closed = new AtomicBoolean(); + private final AtomicInteger activePromptTasks = new AtomicInteger(); + private final AtomicInteger activeStreamLifecycles = new AtomicInteger(); + private final ThreadLocal futurePublicationThread = new ThreadLocal<>(); + private final Object lifecycleLock = new Object(); + private int activeSessionCreations; + + private DaemonClient(Builder builder) { + this.baseUrl = normalizeBaseUri(builder.baseUri); + this.bearerToken = builder.bearerToken; + this.requestTimeout = builder.requestTimeout; + this.promptObservationTimeout = builder.promptObservationTimeout; + this.sseIdleTimeout = builder.sseIdleTimeout; + this.maximumReconnectAttempts = builder.maximumReconnectAttempts; + this.maximumSseFrameBytes = builder.maximumSseFrameBytes; + this.heartbeatInterval = builder.heartbeatInterval; + long clientNumber = CLIENT_SEQUENCE.incrementAndGet(); + this.promptSlots = new Semaphore(builder.maximumConcurrentPrompts); + int streamLifecycleCapacity = builder.maximumConcurrentPrompts; + this.streamLifecycleSlots = new Semaphore(streamLifecycleCapacity); + this.executor = new ThreadPoolExecutor(builder.maximumConcurrentPrompts, + builder.maximumConcurrentPrompts, 0L, TimeUnit.MILLISECONDS, + new LinkedBlockingQueue<>(builder.maximumConcurrentPrompts), + daemonThreadFactory( + "qwencode-daemon-" + clientNumber + "-worker-")); + this.maintenanceExecutor = new ThreadPoolExecutor(4, 4, 0L, + TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(256), + daemonThreadFactory("qwencode-daemon-" + clientNumber + + "-maintenance-")); + int futureThreads = (int) Math.min(Integer.MAX_VALUE, + Math.max(2L, builder.maximumConcurrentPrompts * 2L)); + int futurePublicationCapacity = (int) Math.min(Integer.MAX_VALUE, + futureThreads * 2L); + this.futurePublicationSlots = new Semaphore(futurePublicationCapacity); + this.futureExecutor = new ThreadPoolExecutor(futureThreads, + futureThreads, 0L, TimeUnit.MILLISECONDS, + new LinkedBlockingQueue<>(futurePublicationCapacity), + daemonThreadFactory( + "qwencode-daemon-" + clientNumber + "-future-")); + int httpThreads = Math.min(16, + Math.max(4, builder.maximumConcurrentPrompts)); + this.httpExecutor = new ThreadPoolExecutor(httpThreads, httpThreads, + 0L, TimeUnit.MILLISECONDS, new ArrayBlockingQueue<>(256), + daemonThreadFactory("qwencode-daemon-" + clientNumber + "-http-")); + this.streamCloseExecutor = new ThreadPoolExecutor( + builder.maximumConcurrentPrompts, + builder.maximumConcurrentPrompts, 0L, TimeUnit.MILLISECONDS, + new ArrayBlockingQueue<>(streamLifecycleCapacity), + daemonThreadFactory("qwencode-daemon-" + clientNumber + + "-stream-close-")); + this.scheduler = new ScheduledThreadPoolExecutor(1, + daemonThreadFactory("qwencode-daemon-" + clientNumber + "-timer-")); + this.scheduler.setRemoveOnCancelPolicy(true); + this.httpClient = HttpClient.newBuilder() + .connectTimeout(builder.connectTimeout) + .executor(httpExecutor) + .followRedirects(HttpClient.Redirect.NEVER) + .version(HttpClient.Version.HTTP_1_1) + .build(); + } + + public static Builder builder() { + return new Builder(); + } + + public DaemonCapabilities capabilities() { + ensureOpen(); + HttpSupport.Response response = sendRead("/capabilities", "GET /capabilities"); + requireStatus(response, 200, "GET /capabilities"); + Map json = JsonSupport.parseObject(response.getBody(), + "GET /capabilities response"); + int version = JsonSupport.requiredInt(json, "v", "capabilities"); + if (version != 1) { + throw new DaemonProtocolException("Unsupported capabilities version: " + version); + } + String mode = JsonSupport.requiredString(json, "mode", "capabilities"); + java.util.List transports = JsonSupport.stringList(json, + "transports"); + return new DaemonCapabilities(version, mode, + JsonSupport.stringList(json, "features"), transports, + JsonSupport.optionalString(json, "workspaceCwd"), + JsonSupport.optionalString(json, "qwenCodeVersion"), json); + } + + public DaemonSessionClient createSession() { + return createSession(CreateSessionRequest.defaults()); + } + + public DaemonSessionClient createSession(CreateSessionRequest request) { + if (request == null) { + throw new IllegalArgumentException("request must not be null"); + } + synchronized (lifecycleLock) { + ensureOpen(); + activeSessionCreations += 1; + } + try { + DaemonCapabilities capabilities = capabilities(); + if (!capabilities.getTransports().contains("rest")) { + throw new DaemonProtocolException( + "The daemon does not advertise the REST transport"); + } + if (!capabilities.supports("session_scope_override")) { + throw new DaemonProtocolException( + "The daemon does not advertise session_scope_override; " + + "the SDK cannot guarantee the requested session scope"); + } + synchronized (lifecycleLock) { + ensureOpen(); + } + HttpSupport.Response response; + try { + response = send("/session", "POST", request.toJson(), null, + requestTimeout); + } catch (IOException | InterruptedException e) { + restoreInterrupt(e); + throw new SessionCreationOutcomeUnknownException(e); + } catch (DaemonTransportException | DaemonProtocolException e) { + throw new SessionCreationOutcomeUnknownException(e); + } + try { + if (isAmbiguousMutationStatus(response.getStatusCode())) { + throw new SessionCreationOutcomeUnknownException( + new DaemonHttpException("POST /session", + response.getStatusCode(), response.getBody())); + } + requireStatus(response, 200, "POST /session"); + Map json = JsonSupport.parseObject(response.getBody(), + "POST /session response"); + String clientId = JsonSupport.requiredString(json, "clientId", + "session"); + validateClientId(clientId); + DaemonSession session = new DaemonSession( + JsonSupport.requiredString(json, "sessionId", "session"), + JsonSupport.requiredString(json, "workspaceCwd", "session"), + JsonSupport.requiredBoolean(json, "attached", "session"), + clientId, + JsonSupport.optionalString(json, "createdAt")); + DaemonSessionClient result = new DaemonSessionClient(this, session, + capabilities.supports("client_heartbeat"), + capabilities.supports("prompt_absolute_deadline")); + synchronized (lifecycleLock) { + if (!closed.get()) { + sessions.add(result); + result.startAutomaticHeartbeat(); + return result; + } + } + IllegalStateException failure = new IllegalStateException( + "DaemonClient is closed"); + try { + result.close(); + } catch (RuntimeException cleanupFailure) { + failure.addSuppressed(cleanupFailure); + } + throw failure; + } catch (DaemonProtocolException e) { + throw new SessionCreationOutcomeUnknownException(e); + } + } finally { + boolean shutdownHttpExecutor = false; + synchronized (lifecycleLock) { + activeSessionCreations -= 1; + if (closed.get() && activeSessionCreations == 0) { + shutdownHttpExecutor = true; + } + } + if (shutdownHttpExecutor) { + httpExecutor.shutdownNow(); + } + } + } + + @Override + public void close() { + List sessionsToClose; + boolean shutdownHttpExecutor; + synchronized (lifecycleLock) { + if (!closed.compareAndSet(false, true)) { + return; + } + sessionsToClose = new ArrayList<>(sessions); + shutdownHttpExecutor = activeSessionCreations == 0; + } + RuntimeException firstFailure = null; + try { + for (DaemonSessionClient session : sessionsToClose) { + try { + session.close(); + } catch (RuntimeException e) { + if (firstFailure == null) { + firstFailure = e; + } else { + firstFailure.addSuppressed(e); + } + } + } + } finally { + executor.shutdown(); + maintenanceExecutor.shutdownNow(); + if (shutdownHttpExecutor) { + httpExecutor.shutdownNow(); + } + awaitTermination(executor); + awaitTermination(maintenanceExecutor); + if (shutdownHttpExecutor) { + awaitTermination(httpExecutor); + } + shutdownPromptSupportIfIdle(); + if (scheduler.isShutdown()) { + awaitTermination(scheduler); + } + if (streamCloseExecutor.isShutdown()) { + awaitTermination(streamCloseExecutor); + } + if (futureExecutor.isShutdown() + && futurePublicationThread.get() == null) { + awaitTermination(futureExecutor); + } + } + if (firstFailure != null) { + throw firstFailure; + } + } + + HttpSupport.Response sendMutation(String path, Map body, + String clientId) throws IOException, + InterruptedException { + return send(path, "POST", body, clientId, requestTimeout); + } + + HttpSupport.Response sendSessionMutation(String path, Map body, + String clientId) throws IOException, InterruptedException { + synchronized (lifecycleLock) { + ensureOpen(); + } + return send(path, "POST", body, clientId, requestTimeout); + } + + HttpSupport.Response sendDelete(String path, String clientId) + throws IOException, InterruptedException { + return send(path, "DELETE", null, clientId, requestTimeout); + } + + HttpResponse openSse(String path, String clientId, long lastEventId, + Duration observationRemaining) + throws IOException, InterruptedException { + HttpRequest request = requestBuilder(path, clientId) + .header("Accept", "text/event-stream") + .header("Accept-Encoding", "identity") + .header("Cache-Control", "no-cache") + .header("Last-Event-ID", Long.toString(lastEventId)) + .timeout(shorter(requestTimeout, observationRemaining)) + .GET() + .build(); + try { + return httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream()); + } catch (RejectedExecutionException e) { + throw new IOException("HTTP executor is saturated", e); + } + } + + void submit(Runnable task, Runnable afterCompletion, + Runnable afterCapacityRelease, + Supplier> streamCleanup) { + synchronized (lifecycleLock) { + ensureOpen(); + if (!promptSlots.tryAcquire()) { + throw new DaemonClientCapacityException( + new RejectedExecutionException( + "Prompt capacity is exhausted")); + } + if (!streamLifecycleSlots.tryAcquire()) { + promptSlots.release(); + throw new DaemonClientCapacityException( + new RejectedExecutionException( + "Stream cleanup capacity is exhausted")); + } + activePromptTasks.incrementAndGet(); + activeStreamLifecycles.incrementAndGet(); + FutureTask submitted = new FutureTask(() -> { + task.run(); + return null; + }) { + @Override + protected void done() { + try { + afterCompletion.run(); + } finally { + try { + registerStreamCleanup(streamCleanup); + } finally { + promptSlots.release(); + try { + afterCapacityRelease.run(); + } finally { + activePromptTasks.decrementAndGet(); + shutdownPromptSupportIfIdle(); + } + } + } + } + }; + try { + executor.execute(submitted); + } catch (RejectedExecutionException e) { + promptSlots.release(); + activePromptTasks.decrementAndGet(); + releaseStreamLifecycle(); + shutdownPromptSupportIfIdle(); + throw new DaemonClientCapacityException(e); + } + } + } + + Future submitMaintenance(Runnable task) { + try { + return maintenanceExecutor.submit(task); + } catch (RejectedExecutionException ignored) { + return null; + } + } + + CompletableFuture closeStreamAsync(InputStream stream) { + CompletableFuture completion = new CompletableFuture<>(); + try { + streamCloseExecutor.execute(() -> { + try { + stream.close(); + completion.complete(null); + } catch (IOException | RuntimeException e) { + completion.completeExceptionally(e); + } catch (Error e) { + completion.completeExceptionally(e); + throw e; + } + }); + } catch (RejectedExecutionException e) { + completion.completeExceptionally(e); + } + return completion; + } + + Executor reserveFuturePublications() { + if (!futurePublicationSlots.tryAcquire(2)) { + throw new DaemonClientCapacityException( + new RejectedExecutionException( + "Future publication capacity is exhausted")); + } + AtomicInteger remaining = new AtomicInteger(2); + return command -> { + if (remaining.getAndDecrement() <= 0) { + throw new IllegalStateException( + "Prompt future publication reservation is exhausted"); + } + Runnable publication = () -> { + futurePublicationSlots.release(); + futurePublicationThread.set(Boolean.TRUE); + try { + command.run(); + } finally { + futurePublicationThread.remove(); + } + }; + try { + futureExecutor.execute(publication); + } catch (RejectedExecutionException e) { + publication.run(); + } + }; + } + + void unregister(DaemonSessionClient session) { + sessions.remove(session); + } + + ScheduledExecutorService scheduler() { + return scheduler; + } + + Duration promptObservationTimeout() { + return promptObservationTimeout; + } + + Duration sseIdleTimeout() { + return sseIdleTimeout; + } + + Duration requestTimeout() { + return requestTimeout; + } + + Duration heartbeatInterval() { + return heartbeatInterval; + } + + int maximumReconnectAttempts() { + return maximumReconnectAttempts; + } + + int maximumSseFrameBytes() { + return maximumSseFrameBytes; + } + + static void requireStatus(HttpSupport.Response response, int expected, + String operation) { + if (response.getStatusCode() != expected) { + if (response.isSuccess()) { + throw new DaemonProtocolException(operation + + " returned unexpected successful HTTP " + + response.getStatusCode()); + } + throw new DaemonHttpException(operation, response.getStatusCode(), + response.getBody()); + } + } + + static boolean isAmbiguousMutationStatus(int statusCode) { + return statusCode == 408 || statusCode >= 500; + } + + static String encodePathSegment(String value) { + return URLEncoder.encode(value, StandardCharsets.UTF_8) + .replace("+", "%20"); + } + + private HttpSupport.Response sendRead(String path, String operation) { + try { + return send(path, "GET", null, null, requestTimeout); + } catch (IOException e) { + throw new DaemonTransportException(operation + " transport failed", e); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw new DaemonTransportException(operation + " was interrupted", e); + } + } + + private HttpSupport.Response send(String path, String method, + Map body, String clientId, Duration timeout) + throws IOException, InterruptedException { + HttpRequest.Builder builder = requestBuilder(path, clientId) + .header("Accept", "application/json") + .header("Accept-Encoding", "identity") + .timeout(timeout); + if (body == null) { + builder.method(method, HttpRequest.BodyPublishers.noBody()); + } else { + builder.header("Content-Type", "application/json; charset=utf-8") + .method(method, HttpRequest.BodyPublishers.ofString( + JsonSupport.encode(body), StandardCharsets.UTF_8)); + } + java.util.concurrent.CompletableFuture> future; + try { + future = httpClient.sendAsync(builder.build(), HttpSupport.bodyHandler()); + } catch (RejectedExecutionException e) { + throw new IOException("HTTP executor is saturated", e); + } + HttpResponse response; + try { + response = future.get(timeoutNanos(timeout), TimeUnit.NANOSECONDS); + } catch (InterruptedException e) { + future.cancel(true); + throw e; + } catch (TimeoutException e) { + future.cancel(true); + throw new java.net.http.HttpTimeoutException( + method + " " + path + " response timed out"); + } catch (ExecutionException e) { + Throwable cause = e.getCause(); + if (cause instanceof IOException) { + throw (IOException) cause; + } + if (cause instanceof RejectedExecutionException) { + throw new IOException("HTTP executor is saturated", cause); + } + if (cause instanceof RuntimeException) { + throw (RuntimeException) cause; + } + throw new IOException(method + " " + path + " failed", cause); + } + return HttpSupport.consume(response, method + " " + path); + } + + private HttpRequest.Builder requestBuilder(String path, String clientId) { + HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(baseUrl + path)); + if (bearerToken != null) { + builder.header("Authorization", "Bearer " + bearerToken); + } + if (clientId != null) { + builder.header("X-Qwen-Client-Id", clientId); + } + return builder; + } + + private void ensureOpen() { + if (closed.get()) { + throw new IllegalStateException("DaemonClient is closed"); + } + } + + private static String normalizeBaseUri(URI baseUri) { + String scheme = baseUri.getScheme(); + if (!("http".equalsIgnoreCase(scheme) || "https".equalsIgnoreCase(scheme))) { + throw new IllegalArgumentException("baseUri must use http or https"); + } + if (baseUri.getHost() == null || baseUri.getUserInfo() != null + || baseUri.getQuery() != null + || baseUri.getFragment() != null) { + throw new IllegalArgumentException( + "baseUri must be an absolute HTTP origin or path without credentials"); + } + String value = baseUri.toString(); + while (value.endsWith("/")) { + value = value.substring(0, value.length() - 1); + } + return value; + } + + private static void validateClientId(String clientId) { + if (clientId.length() > 128 + || !clientId.matches("[A-Za-z0-9._:-]+")) { + throw new DaemonProtocolException( + "session.clientId is not a valid daemon client identifier"); + } + } + + private static ThreadFactory daemonThreadFactory(String prefix) { + AtomicLong sequence = new AtomicLong(); + return runnable -> { + Thread thread = new Thread(runnable, prefix + sequence.incrementAndGet()); + thread.setDaemon(true); + return thread; + }; + } + + private static void restoreInterrupt(Exception exception) { + if (exception instanceof InterruptedException) { + Thread.currentThread().interrupt(); + } + } + + private static void awaitTermination(ExecutorService service) { + try { + service.awaitTermination(5, TimeUnit.SECONDS); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + + private void shutdownPromptSupportIfIdle() { + if (closed.get() && activePromptTasks.get() == 0) { + futureExecutor.shutdown(); + scheduler.shutdownNow(); + } + if (closed.get() && activeStreamLifecycles.get() == 0) { + streamCloseExecutor.shutdown(); + } + } + + private void releaseStreamLifecycle() { + streamLifecycleSlots.release(); + activeStreamLifecycles.decrementAndGet(); + shutdownPromptSupportIfIdle(); + } + + private void registerStreamCleanup( + Supplier> streamCleanup) { + try { + CompletableFuture cleanup = streamCleanup.get(); + if (cleanup == null) { + throw new IllegalStateException( + "Prompt stream cleanup future is null"); + } + cleanup.whenComplete((ignored, failure) -> + releaseStreamLifecycle()); + } catch (RuntimeException e) { + releaseStreamLifecycle(); + throw e; + } + } + + private static Duration shorter(Duration first, Duration second) { + return first.compareTo(second) <= 0 ? first : second; + } + + private static long timeoutNanos(Duration timeout) { + try { + return timeout.toNanos(); + } catch (ArithmeticException e) { + return Long.MAX_VALUE; + } + } + + public static final class Builder { + private URI baseUri = URI.create("http://127.0.0.1:4170"); + private String bearerToken; + private Duration connectTimeout = Duration.ofSeconds(10); + private Duration requestTimeout = Duration.ofSeconds(30); + private Duration promptObservationTimeout = Duration.ofMinutes(30); + private Duration sseIdleTimeout = Duration.ofSeconds(45); + private Duration heartbeatInterval = Duration.ofMinutes(1); + private int maximumReconnectAttempts = 8; + private int maximumSseFrameBytes = 16 * 1024 * 1024; + private int maximumConcurrentPrompts = 32; + + private Builder() { + } + + public Builder baseUri(URI baseUri) { + if (baseUri == null) { + throw new IllegalArgumentException("baseUri must not be null"); + } + this.baseUri = baseUri; + return this; + } + + public Builder bearerToken(String bearerToken) { + if (bearerToken == null || bearerToken.trim().isEmpty()) { + throw new IllegalArgumentException("bearerToken must not be blank"); + } + this.bearerToken = bearerToken; + return this; + } + + public Builder connectTimeout(Duration connectTimeout) { + this.connectTimeout = positive(connectTimeout, "connectTimeout"); + return this; + } + + public Builder requestTimeout(Duration requestTimeout) { + this.requestTimeout = positive(requestTimeout, "requestTimeout"); + return this; + } + + public Builder promptObservationTimeout(Duration timeout) { + this.promptObservationTimeout = positive(timeout, + "promptObservationTimeout"); + return this; + } + + public Builder sseIdleTimeout(Duration sseIdleTimeout) { + this.sseIdleTimeout = positive(sseIdleTimeout, "sseIdleTimeout"); + return this; + } + + public Builder heartbeatInterval(Duration heartbeatInterval) { + if (heartbeatInterval == null || heartbeatInterval.isNegative()) { + throw new IllegalArgumentException( + "heartbeatInterval must be non-negative"); + } + this.heartbeatInterval = heartbeatInterval; + return this; + } + + public Builder maximumReconnectAttempts(int attempts) { + if (attempts < 0) { + throw new IllegalArgumentException( + "maximumReconnectAttempts must be non-negative"); + } + this.maximumReconnectAttempts = attempts; + return this; + } + + public Builder maximumSseFrameBytes(int bytes) { + if (bytes < 1024) { + throw new IllegalArgumentException( + "maximumSseFrameBytes must be at least 1024"); + } + this.maximumSseFrameBytes = bytes; + return this; + } + + public Builder maximumConcurrentPrompts(int prompts) { + if (prompts <= 0) { + throw new IllegalArgumentException( + "maximumConcurrentPrompts must be positive"); + } + this.maximumConcurrentPrompts = prompts; + return this; + } + + public DaemonClient build() { + return new DaemonClient(this); + } + + private static Duration positive(Duration duration, String name) { + if (duration == null || duration.isZero() || duration.isNegative()) { + throw new IllegalArgumentException(name + " must be positive"); + } + return duration; + } + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonClientCapacityException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonClientCapacityException.java new file mode 100644 index 00000000000..957f5026133 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonClientCapacityException.java @@ -0,0 +1,8 @@ +package com.alibaba.qwen.code.daemon; + +/** The configured client-wide prompt or publication capacity is exhausted. */ +public final class DaemonClientCapacityException extends DaemonException { + DaemonClientCapacityException(Throwable cause) { + super("DaemonClient capacity is exhausted", cause); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonEvent.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonEvent.java new file mode 100644 index 00000000000..fe7f8864511 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonEvent.java @@ -0,0 +1,121 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.Collections; +import java.util.Map; + +/** One validated daemon SSE event envelope. */ +public final class DaemonEvent { + private final Long id; + private final int version; + private final String type; + private final Object data; + private final String promptId; + private final String originatorClientId; + private final Map metadata; + + DaemonEvent(Long id, int version, String type, Object data, + String promptId, String originatorClientId, + Map metadata) { + this.id = id; + this.version = version; + this.type = type; + this.data = data; + this.promptId = promptId; + this.originatorClientId = originatorClientId; + this.metadata = Collections.unmodifiableMap(metadata); + } + + public Long getId() { + return id; + } + + public int getVersion() { + return version; + } + + public String getType() { + return type; + } + + public Object getData() { + return data; + } + + public String getPromptId() { + return promptId; + } + + public String getOriginatorClientId() { + return originatorClientId; + } + + public Map getMetadata() { + return metadata; + } + + boolean belongsTo(String expectedPromptId) { + if (!("turn_complete".equals(type) || "turn_error".equals(type))) { + return expectedPromptId.equals(promptId); + } + Map object = dataObject(); + String dataPromptId = object == null ? null + : JsonSupport.optionalString(object, "promptId"); + if (promptId != null && dataPromptId != null + && !promptId.equals(dataPromptId)) { + throw new DaemonProtocolException( + "SSE envelope promptId conflicts with data.promptId"); + } + String canonicalPromptId = promptId == null ? dataPromptId : promptId; + return expectedPromptId.equals(canonicalPromptId); + } + + String updateKind() { + return JsonSupport.requiredString(update(), "sessionUpdate", + "session_update.data.update"); + } + + String textChunk() { + Map content = JsonSupport.requiredObject(update(), + "content", "session_update.data.update"); + String contentType = JsonSupport.requiredString(content, "type", + "session_update.data.update.content"); + if (!"text".equals(contentType)) { + return null; + } + Object text = content.get("text"); + if (!(text instanceof String)) { + throw new DaemonProtocolException( + "session_update.data.update.content.text must be a string"); + } + return (String) text; + } + + Map update() { + return JsonSupport.requiredObject( + requireDataObject("session_update.data"), "update", + "session_update.data"); + } + + Map requireDataObject(String context) { + Map object = dataObject(); + if (object == null) { + throw new DaemonProtocolException(context + " must be an object"); + } + return object; + } + + void requireSessionId(String expectedSessionId, String context) { + String actualSessionId = JsonSupport.requiredString( + requireDataObject(context + ".data"), "sessionId", + context + ".data"); + if (!expectedSessionId.equals(actualSessionId)) { + throw new DaemonProtocolException(context + + ".data.sessionId does not match the session"); + } + } + + @SuppressWarnings("unchecked") + private Map dataObject() { + return data instanceof Map ? (Map) data : null; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonException.java new file mode 100644 index 00000000000..8d11cf586af --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonException.java @@ -0,0 +1,12 @@ +package com.alibaba.qwen.code.daemon; + +/** Base class for daemon client failures. */ +public class DaemonException extends RuntimeException { + public DaemonException(String message) { + super(message); + } + + public DaemonException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonHttpException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonHttpException.java new file mode 100644 index 00000000000..7b1f777ac75 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonHttpException.java @@ -0,0 +1,22 @@ +package com.alibaba.qwen.code.daemon; + +/** A received non-success HTTP response from the daemon or an intermediary. */ +public final class DaemonHttpException extends DaemonException { + private final int statusCode; + private final String responseBody; + + DaemonHttpException(String operation, int statusCode, String responseBody) { + super(operation + " failed with HTTP " + statusCode + + (responseBody.isEmpty() ? "" : ": " + responseBody)); + this.statusCode = statusCode; + this.responseBody = responseBody; + } + + public int getStatusCode() { + return statusCode; + } + + public String getResponseBody() { + return responseBody; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonProtocolException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonProtocolException.java new file mode 100644 index 00000000000..ab4af6ad4eb --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonProtocolException.java @@ -0,0 +1,12 @@ +package com.alibaba.qwen.code.daemon; + +/** A malformed or unsupported daemon protocol response. */ +public final class DaemonProtocolException extends DaemonException { + DaemonProtocolException(String message) { + super(message); + } + + DaemonProtocolException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSession.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSession.java new file mode 100644 index 00000000000..1e0608fade3 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSession.java @@ -0,0 +1,39 @@ +package com.alibaba.qwen.code.daemon; + +/** Identity returned by {@code POST /session}. */ +public final class DaemonSession { + private final String sessionId; + private final String workspaceCwd; + private final boolean attached; + private final String clientId; + private final String createdAt; + + DaemonSession(String sessionId, String workspaceCwd, boolean attached, + String clientId, String createdAt) { + this.sessionId = sessionId; + this.workspaceCwd = workspaceCwd; + this.attached = attached; + this.clientId = clientId; + this.createdAt = createdAt; + } + + public String getSessionId() { + return sessionId; + } + + public String getWorkspaceCwd() { + return workspaceCwd; + } + + public boolean isAttached() { + return attached; + } + + public String getClientId() { + return clientId; + } + + public String getCreatedAt() { + return createdAt; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSessionClient.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSessionClient.java new file mode 100644 index 00000000000..1f95b9408a9 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonSessionClient.java @@ -0,0 +1,1198 @@ +package com.alibaba.qwen.code.daemon; + +import java.io.IOException; +import java.io.InputStream; +import java.net.http.HttpHeaders; +import java.net.http.HttpResponse; +import java.time.Duration; +import java.time.ZonedDateTime; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.Collections; +import java.util.Map; +import java.util.Objects; +import java.util.Set; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionException; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.Future; +import java.util.concurrent.ScheduledFuture; +import java.util.concurrent.ThreadLocalRandom; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.TimeoutException; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicLong; +import java.util.concurrent.atomic.AtomicReference; + +/** One independently attached daemon session. */ +public final class DaemonSessionClient implements AutoCloseable { + public static final long DEFAULT_MAXIMUM_TEXT_BYTES = 4L * 1024L * 1024L; + + private static final Set SESSION_FAILURE_EVENTS = Set.of( + "client_evicted", "session_closed", "session_died", + "state_resync_required", "stream_error"); + private static final Set IDLESS_SYNTHETIC_EVENTS = Set.of( + "client_evicted", "slow_client_warning", "stream_error", + "state_resync_required", "replay_complete"); + private static final Set OBSERVABLE_STREAM_EVENTS = Set.of( + "slow_client_warning", "replay_complete"); + private static final Set RETRYABLE_SSE_STATUS = Set.of( + 408, 429, 500, 502, 503, 504); + + private final DaemonClient client; + private final DaemonSession session; + private final boolean automaticHeartbeatSupported; + private final boolean promptDeadlineSupported; + private final AtomicBoolean closed = new AtomicBoolean(); + private final AtomicBoolean detachAttempted = new AtomicBoolean(); + private final AtomicBoolean destroySucceeded = new AtomicBoolean(); + private final AtomicReference activePrompt = new AtomicReference<>(); + private final AtomicBoolean heartbeatUnsupported = new AtomicBoolean(); + private final AtomicBoolean heartbeatInFlight = new AtomicBoolean(); + private final Object lifecycleLock = new Object(); + private ScheduledFuture heartbeatTask; + private boolean automaticHeartbeatRunning; + + DaemonSessionClient(DaemonClient client, DaemonSession session, + boolean automaticHeartbeatSupported, boolean promptDeadlineSupported) { + this.client = client; + this.session = session; + this.automaticHeartbeatSupported = automaticHeartbeatSupported; + this.promptDeadlineSupported = promptDeadlineSupported; + } + + public DaemonSession getSession() { + return session; + } + + public String getSessionId() { + return session.getSessionId(); + } + + public String getClientId() { + return session.getClientId(); + } + + public PromptCall startPrompt(PromptRequest request, PromptObserver observer) { + Objects.requireNonNull(request, "request"); + Objects.requireNonNull(observer, "observer"); + synchronized (lifecycleLock) { + ensureOpen(); + if (request.getDeadlineMillis() != null && !promptDeadlineSupported) { + throw new DaemonProtocolException( + "The daemon does not advertise prompt_absolute_deadline; " + + "the SDK cannot guarantee the requested deadline"); + } + if (activePrompt.get() != null) { + throw new PromptAlreadyActiveException(); + } + PromptExecution execution = new PromptExecution(request, observer); + activePrompt.set(execution); + try { + client.submit(execution::run, + execution::publishCompletion, + execution::releaseTerminalPublication, + execution::streamCleanupCompletion); + } catch (RuntimeException e) { + activePrompt.compareAndSet(execution, null); + execution.failBeforeStart(e); + } + return execution.call; + } + } + + public PromptTextResult promptText(String text) { + return promptText(PromptRequest.text(text), DEFAULT_MAXIMUM_TEXT_BYTES); + } + + public PromptTextResult promptText(PromptRequest request) { + return promptText(request, DEFAULT_MAXIMUM_TEXT_BYTES); + } + + public PromptTextResult promptText(PromptRequest request, long maximumBytes) { + if (maximumBytes <= 0) { + throw new IllegalArgumentException("maximumBytes must be positive"); + } + TextCollector collector = new TextCollector(maximumBytes); + PromptTerminal terminal; + try { + terminal = startPrompt(request, collector).completionFuture().join(); + } catch (CompletionException e) { + Throwable cause = e.getCause(); + if (cause instanceof PromptContentLimitException) { + throw (PromptContentLimitException) cause; + } + String partialText; + try { + collector.finish(); + partialText = collector.getText(); + } catch (PromptContentLimitException contentLimit) { + partialText = contentLimit.getPartialText(); + } + if (cause instanceof PromptOutcomeIndeterminateException) { + PromptOutcomeIndeterminateException indeterminate = + (PromptOutcomeIndeterminateException) cause; + throw new PromptOutcomeIndeterminateException( + indeterminate.getMessage(), indeterminate, + partialText); + } + if (cause instanceof RuntimeException) { + throw (RuntimeException) cause; + } + throw e; + } + collector.finish(); + if (terminal.getKind() == PromptTerminal.Kind.ERROR) { + throw new PromptTurnException(terminal, collector.getText()); + } + return new PromptTextResult(collector.getText(), terminal); + } + + public boolean respondToPermission(String requestId, PermissionResponse response) { + if (requestId == null || requestId.isEmpty()) { + throw new IllegalArgumentException("requestId must not be empty"); + } + Objects.requireNonNull(response, "response"); + synchronized (lifecycleLock) { + ensureOpen(); + String path = sessionPath() + "/permission/" + + DaemonClient.encodePathSegment(requestId); + HttpSupport.Response httpResponse = sendMutation(path, + "POST /session/:id/permission/:requestId", response.toJson()); + if (httpResponse.getStatusCode() == 404) { + if (isCurrentPermissionNotFound(httpResponse, requestId)) { + return false; + } + throw new DaemonHttpException( + "POST /session/:id/permission/:requestId", + httpResponse.getStatusCode(), httpResponse.getBody()); + } + requireMutationStatus(httpResponse, 200, + "POST /session/:id/permission/:requestId"); + return true; + } + } + + public void cancelActivePrompt() { + synchronized (lifecycleLock) { + ensureOpen(); + HttpSupport.Response response = sendMutation(sessionPath() + "/cancel", + "POST /session/:id/cancel", Collections.emptyMap()); + requireMutationStatus(response, 204, "POST /session/:id/cancel"); + } + } + + public HeartbeatResult heartbeat() { + synchronized (lifecycleLock) { + ensureOpen(); + return sendHeartbeat(); + } + } + + public void detach() { + close(); + } + + public void destroySession() { + synchronized (lifecycleLock) { + if (destroySucceeded.get()) { + return; + } + closed.set(true); + cancelAutomaticHeartbeat(); + awaitAutomaticHeartbeat(); + stopActivePrompt("Session was destroyed locally"); + try { + HttpSupport.Response response; + try { + response = client.sendDelete(sessionPath(), + detachAttempted.get() ? null : session.getClientId()); + } catch (IOException | InterruptedException e) { + restoreInterrupt(e); + throw new MutationOutcomeUnknownException( + "DELETE /session/:id", e); + } catch (DaemonTransportException | DaemonProtocolException e) { + throw new MutationOutcomeUnknownException( + "DELETE /session/:id", e); + } + if (response.getStatusCode() == 404) { + if (!isCurrentSessionNotFound(response)) { + throw new DaemonHttpException("DELETE /session/:id", + response.getStatusCode(), response.getBody()); + } + } else { + requireMutationStatus(response, 204, "DELETE /session/:id"); + } + destroySucceeded.set(true); + } finally { + client.unregister(this); + } + } + } + + @Override + public void close() { + synchronized (lifecycleLock) { + if (!closed.compareAndSet(false, true)) { + return; + } + cancelAutomaticHeartbeat(); + awaitAutomaticHeartbeat(); + stopActivePrompt("Session was detached locally"); + try { + if (!destroySucceeded.get() + && detachAttempted.compareAndSet(false, true)) { + HttpSupport.Response response; + try { + response = client.sendMutation(sessionPath() + "/detach", + Collections.emptyMap(), + session.getClientId()); + } catch (IOException | InterruptedException e) { + restoreInterrupt(e); + throw new DetachOutcomeUnknownException(e); + } catch (DaemonTransportException | DaemonProtocolException e) { + throw new DetachOutcomeUnknownException(e); + } + if (DaemonClient.isAmbiguousMutationStatus( + response.getStatusCode())) { + throw new DetachOutcomeUnknownException( + new DaemonHttpException( + "POST /session/:id/detach", + response.getStatusCode(), + response.getBody())); + } + try { + DaemonClient.requireStatus(response, 204, + "POST /session/:id/detach"); + } catch (DaemonProtocolException e) { + throw new DetachOutcomeUnknownException(e); + } + } + } finally { + client.unregister(this); + } + } + } + + private HttpSupport.Response sendMutation(String path, String operation, + Map body) { + try { + return client.sendSessionMutation(path, body, session.getClientId()); + } catch (IOException | InterruptedException e) { + restoreInterrupt(e); + throw new MutationOutcomeUnknownException(operation, e); + } catch (DaemonTransportException | DaemonProtocolException e) { + throw new MutationOutcomeUnknownException(operation, e); + } + } + + private static void requireMutationStatus(HttpSupport.Response response, + int expected, String operation) { + if (DaemonClient.isAmbiguousMutationStatus(response.getStatusCode())) { + throw new MutationOutcomeUnknownException(operation, + new DaemonHttpException(operation, + response.getStatusCode(), response.getBody())); + } + try { + DaemonClient.requireStatus(response, expected, operation); + } catch (DaemonProtocolException e) { + throw new MutationOutcomeUnknownException(operation, e); + } + } + + void startAutomaticHeartbeat() { + Duration interval = client.heartbeatInterval(); + if (interval.isZero() || !automaticHeartbeatSupported) { + return; + } + synchronized (lifecycleLock) { + if (closed.get() || heartbeatTask != null) { + return; + } + long delayMillis = saturatedMillis(interval); + heartbeatTask = client.scheduler().scheduleWithFixedDelay( + this::submitAutomaticHeartbeat, + delayMillis, delayMillis, TimeUnit.MILLISECONDS); + } + } + + private void submitAutomaticHeartbeat() { + if (closed.get() + || !heartbeatInFlight.compareAndSet(false, true)) { + return; + } + Future submitted = client.submitMaintenance(this::runAutomaticHeartbeat); + if (submitted == null) { + heartbeatInFlight.set(false); + } + } + + private void runAutomaticHeartbeat() { + synchronized (lifecycleLock) { + if (closed.get()) { + heartbeatInFlight.set(false); + return; + } + automaticHeartbeatRunning = true; + } + try { + automaticHeartbeat(); + } finally { + finishAutomaticHeartbeat(); + } + } + + private void automaticHeartbeat() { + if (closed.get() || heartbeatUnsupported.get()) { + return; + } + try { + sendHeartbeat(); + } catch (DaemonHttpException e) { + if (e.getStatusCode() == 404 || e.getStatusCode() == 405) { + heartbeatUnsupported.set(true); + } + } catch (DaemonException ignored) { + // A later scheduled heartbeat is a new keepalive, not a request retry. + } + } + + private HeartbeatResult sendHeartbeat() { + HttpSupport.Response response = sendMutation( + sessionPath() + "/heartbeat", + "POST /session/:id/heartbeat", Collections.emptyMap()); + try { + requireMutationStatus(response, 200, + "POST /session/:id/heartbeat"); + Map json = JsonSupport.parseObject(response.getBody(), + "heartbeat response"); + String responseSessionId = JsonSupport.requiredString(json, + "sessionId", "heartbeat"); + if (!session.getSessionId().equals(responseSessionId)) { + throw new DaemonProtocolException( + "Heartbeat response sessionId does not match the session"); + } + String responseClientId = JsonSupport.requiredString(json, + "clientId", "heartbeat"); + if (!session.getClientId().equals(responseClientId)) { + throw new DaemonProtocolException( + "Heartbeat response clientId does not match the client"); + } + return new HeartbeatResult(responseSessionId, + responseClientId, + JsonSupport.requiredNonNegativeLong(json, "lastSeenAt", + "heartbeat")); + } catch (DaemonProtocolException e) { + throw new MutationOutcomeUnknownException( + "POST /session/:id/heartbeat", e); + } + } + + private void finishAutomaticHeartbeat() { + synchronized (lifecycleLock) { + automaticHeartbeatRunning = false; + heartbeatInFlight.set(false); + lifecycleLock.notifyAll(); + } + } + + private void awaitAutomaticHeartbeat() { + boolean interrupted = false; + while (automaticHeartbeatRunning) { + try { + lifecycleLock.wait(); + } catch (InterruptedException e) { + interrupted = true; + } + } + if (interrupted) { + Thread.currentThread().interrupt(); + } + } + + private void cancelAutomaticHeartbeat() { + ScheduledFuture task = heartbeatTask; + if (task != null) { + task.cancel(false); + heartbeatTask = null; + } + } + + private String sessionPath() { + return "/session/" + DaemonClient.encodePathSegment(session.getSessionId()); + } + + private boolean isCurrentSessionNotFound(HttpSupport.Response response) { + try { + Map body = JsonSupport.parseObject(response.getBody(), + "DELETE /session/:id error response"); + String responseSessionId = JsonSupport.optionalString(body, "sessionId"); + String code = JsonSupport.optionalString(body, "code"); + return session.getSessionId().equals(responseSessionId) + && (code == null || "session_not_found".equals(code)); + } catch (DaemonProtocolException e) { + return false; + } + } + + private boolean isCurrentPermissionNotFound(HttpSupport.Response response, + String requestId) { + try { + Map body = JsonSupport.parseObject(response.getBody(), + "permission response error"); + String responseSessionId = JsonSupport.optionalString(body, "sessionId"); + String responseRequestId = JsonSupport.optionalString(body, "requestId"); + String code = JsonSupport.optionalString(body, "code"); + return session.getSessionId().equals(responseSessionId) + && (responseRequestId == null + || requestId.equals(responseRequestId)) + && (code == null || "session_not_found".equals(code)); + } catch (DaemonProtocolException e) { + return false; + } + } + + private void ensureOpen() { + if (closed.get()) { + throw new IllegalStateException("DaemonSessionClient is closed"); + } + } + + private void stopActivePrompt(String message) { + PromptExecution execution = activePrompt.get(); + if (execution != null) { + execution.stop(new PromptOutcomeIndeterminateException(message, "")); + } + } + + private static void restoreInterrupt(Exception exception) { + if (exception instanceof InterruptedException) { + Thread.currentThread().interrupt(); + } + } + + private final class PromptExecution { + private final PromptRequest request; + private final PromptObserver observer; + private final CompletableFuture acceptance = + new CompletableFuture<>(); + private final CompletableFuture completion = + new CompletableFuture<>(); + private final CountDownLatch terminalPublicationGate = + new CountDownLatch(1); + private final PromptCall call = new PromptCall(acceptance, completion, + client.reserveFuturePublications(), terminalPublicationGate); + private final AtomicReference activeStream = new AtomicReference<>(); + private final Object streamLifecycleLock = new Object(); + private final Object observerLifecycleLock = new Object(); + private final Object outcomeLock = new Object(); + private final AtomicReference stopFailure = + new AtomicReference<>(); + private volatile CompletableFuture streamClose = + CompletableFuture.completedFuture(null); + private volatile boolean admissionStarted; + private volatile PromptTerminal terminalResult; + private volatile Throwable terminalFailure; + private volatile Thread runner; + private boolean observerInProgress; + private boolean outcomeClaimed; + + PromptExecution(PromptRequest request, PromptObserver observer) { + this.request = request; + this.observer = observer; + } + + void failBeforeStart(RuntimeException failure) { + terminalPublicationGate.countDown(); + acceptance.completeExceptionally(failure); + completion.completeExceptionally(failure); + } + + void releaseTerminalPublication() { + terminalPublicationGate.countDown(); + } + + CompletableFuture streamCleanupCompletion() { + synchronized (streamLifecycleLock) { + return streamClose; + } + } + + void stop(PromptOutcomeIndeterminateException failure) { + synchronized (outcomeLock) { + if (outcomeClaimed) { + return; + } + outcomeClaimed = true; + stopFailure.set(failure); + } + synchronized (observerLifecycleLock) { + if (!observerInProgress && acceptance.isDone()) { + completion.completeExceptionally(failure); + terminalPublicationGate.countDown(); + } + } + InputStream stream = activeStream.get(); + if (stream != null) { + requestStreamClose(stream); + } + Thread currentRunner = runner; + if (currentRunner != null + && currentRunner != Thread.currentThread()) { + currentRunner.interrupt(); + } + } + + void run() { + runner = Thread.currentThread(); + try { + PromptAcceptance admitted; + synchronized (lifecycleLock) { + ensureOpen(); + admissionStarted = true; + admitted = admit(); + } + acceptance.complete(admitted); + try { + PromptTerminal terminal = observe(admitted); + activePrompt.compareAndSet(this, null); + terminalResult = terminal; + } catch (PromptOutcomeIndeterminateException e) { + throw e; + } catch (Throwable e) { + throw new PromptOutcomeIndeterminateException( + "Prompt observation failed", e, ""); + } + } catch (Throwable failure) { + if (!acceptance.isDone() + && failure instanceof DaemonHttpException) { + activePrompt.compareAndSet(this, null); + } + if (!acceptance.isDone()) { + PromptOutcomeIndeterminateException stopped = stopFailure.get(); + acceptance.completeExceptionally(stopped != null + && !admissionStarted + ? new DaemonException( + "Prompt stopped before admission was dispatched") + : failure); + } + PromptOutcomeIndeterminateException stopped = stopFailure.get(); + terminalFailure = stopped == null ? failure : stopped; + } finally { + runner = null; + } + } + + void publishCompletion() { + PromptTerminal terminal = terminalResult; + Throwable failure = terminalFailure; + PromptOutcomeIndeterminateException stopped = stopFailure.get(); + if (!acceptance.isDone()) { + acceptance.completeExceptionally(stopped != null + && !admissionStarted + ? new DaemonException( + "Prompt stopped before admission was dispatched") + : failure == null ? new PromptOutcomeIndeterminateException( + "Prompt ended without an admission outcome", "") + : failure); + } + if (terminal != null) { + completion.complete(terminal); + } else { + completion.completeExceptionally(stopped != null + ? stopped + : failure == null ? new PromptOutcomeIndeterminateException( + "Prompt ended without a terminal outcome", "") + : failure); + } + } + + private PromptAcceptance admit() { + HttpSupport.Response response; + try { + response = client.sendMutation(sessionPath() + "/prompt", + request.toJson(), + session.getClientId()); + } catch (IOException | InterruptedException e) { + restoreInterrupt(e); + throw new PromptAdmissionUnknownException(e); + } catch (DaemonTransportException | DaemonProtocolException e) { + throw new PromptAdmissionUnknownException(e); + } + if (response.getStatusCode() != 202) { + if (DaemonClient.isAmbiguousMutationStatus( + response.getStatusCode())) { + throw new PromptAdmissionUnknownException( + new DaemonHttpException("POST /session/:id/prompt", + response.getStatusCode(), response.getBody())); + } + if (!response.isSuccess()) { + throw new DaemonHttpException("POST /session/:id/prompt", + response.getStatusCode(), response.getBody()); + } + throw new PromptAdmissionUnknownException( + "Expected 202 admission watermark but received HTTP " + + response.getStatusCode()); + } + try { + Map json = JsonSupport.parseObject(response.getBody(), + "prompt admission response"); + return new PromptAcceptance( + JsonSupport.requiredString(json, "promptId", "prompt admission"), + JsonSupport.requiredNonNegativeLong(json, "lastEventId", + "prompt admission")); + } catch (DaemonProtocolException e) { + throw new PromptAdmissionUnknownException(e); + } + } + + private PromptTerminal observe(PromptAcceptance admitted) { + Duration timeout = request.observationTimeoutOr( + client.promptObservationTimeout()); + long deadline = deadlineAfter(timeout); + long cursor = admitted.getLastEventId(); + int consecutiveFailures = 0; + Duration serverRetry = null; + while (true) { + checkStoppedOrExpired(deadline); + awaitPriorStreamClose(deadline); + checkStoppedOrExpired(deadline); + HttpResponse response; + try { + response = client.openSse(sessionPath() + "/events", + session.getClientId(), cursor, + Duration.ofMillis(remainingMillis(deadline))); + } catch (IOException e) { + reconnectOrThrow(++consecutiveFailures, + serverRetry, deadline, e); + continue; + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw stoppedOrIndeterminate("SSE connection was interrupted", e); + } + if (response.statusCode() != 200) { + int statusCode = response.statusCode(); + Duration retryAfter = retryAfter(response.headers()); + Duration retryDelay = retryAfter == null + ? serverRetry : retryAfter; + String body; + try { + body = readSseError(response, deadline); + } catch (DaemonProtocolException e) { + throw indeterminate("SSE error response was malformed", e); + } catch (DaemonTransportException e) { + if (!RETRYABLE_SSE_STATUS.contains(statusCode)) { + throw indeterminate("SSE failed with HTTP " + + statusCode, e); + } + reconnectOrThrow(++consecutiveFailures, + retryDelay, deadline, e); + continue; + } + if (!RETRYABLE_SSE_STATUS.contains(statusCode)) { + Throwable responseFailure = statusCode >= 200 + && statusCode < 300 + ? new DaemonProtocolException( + "GET /session/:id/events returned " + + "unexpected successful HTTP " + + statusCode) + : new DaemonHttpException( + "GET /session/:id/events", + statusCode, body); + throw indeterminate("SSE failed with HTTP " + + statusCode, responseFailure); + } + reconnectOrThrow(++consecutiveFailures, + retryDelay, deadline, + new DaemonHttpException("GET /session/:id/events", + statusCode, body)); + continue; + } + InputStream stream = response.body(); + activeStream.set(stream); + AtomicLong lastActivity = new AtomicLong(System.nanoTime()); + AtomicBoolean idleClosed = new AtomicBoolean(); + ScheduledFuture watchdog = null; + ScheduledFuture deadlineWatchdog = null; + SseReader reader = null; + try { + checkStoppedOrExpired(deadline); + validateSseHeaders(response.headers()); + watchdog = scheduleIdleWatchdog(stream, + lastActivity, idleClosed); + deadlineWatchdog = scheduleDeadlineWatchdog(deadline); + reader = new SseReader(stream, + client.maximumSseFrameBytes(), + () -> lastActivity.set(System.nanoTime())); + while (true) { + checkStoppedOrExpired(deadline); + SseReader.Frame frame = reader.next(); + if (frame == null) { + throw new IOException("SSE stream ended before terminal"); + } + DaemonEvent event = parseEvent(frame); + Long eventId = event.getId(); + if (eventId != null && eventId <= cursor) { + continue; + } + if (eventId != null && eventId != cursor + 1) { + throw new DaemonProtocolException("SSE event ID gap: expected " + + (cursor + 1) + " but received " + eventId); + } + PromptTerminal terminal = processEvent(event, admitted.getPromptId()); + if (terminal == null) { + checkStoppedOrExpired(deadline); + } + if (eventId != null) { + cursor = eventId; + consecutiveFailures = 0; + } + if (terminal != null) { + if (!claimTerminal(terminal, deadline)) { + PromptOutcomeIndeterminateException stopped = + stopFailure.get(); + if (stopped == null) { + stop(indeterminate( + "Prompt observation timed out", null)); + stopped = stopFailure.get(); + } + throw stopped == null + ? indeterminate( + "Prompt outcome was already settled", + null) + : stopped; + } + return terminal; + } + } + } catch (IOException e) { + requestStreamClose(stream); + checkStoppedOrExpired(deadline); + String reason = idleClosed.get() + ? "SSE idle timeout" : "SSE stream failed"; + if (reader != null && reader.getRetryMillis() != null) { + serverRetry = Duration.ofMillis(reader.getRetryMillis()); + } + reconnectOrThrow(++consecutiveFailures, + serverRetry, deadline, + new IOException(reason, e)); + } catch (DaemonProtocolException e) { + throw indeterminate(e.getMessage(), e); + } catch (RuntimeException e) { + if (e instanceof PromptOutcomeIndeterminateException) { + throw e; + } + throw indeterminate("Prompt observer failed", e); + } finally { + if (watchdog != null) { + watchdog.cancel(false); + } + if (deadlineWatchdog != null) { + deadlineWatchdog.cancel(false); + } + requestStreamClose(stream); + } + } + } + + private PromptTerminal processEvent(DaemonEvent event, String promptId) { + if (SESSION_FAILURE_EVENTS.contains(event.getType())) { + throw indeterminate("Daemon session stream reported " + + event.getType(), null); + } + if (OBSERVABLE_STREAM_EVENTS.contains(event.getType())) { + notifyObserver(() -> observer.onEvent(event)); + return null; + } + if (!event.belongsTo(promptId)) { + return null; + } + if ("turn_complete".equals(event.getType()) + || "turn_error".equals(event.getType())) { + PromptTerminal terminal = PromptTerminal.from(event, promptId, + session.getSessionId()); + dispatch(event); + return terminal; + } + dispatch(event); + return null; + } + + private void dispatch(DaemonEvent event) { + notifyObserver(() -> dispatchToObserver(event)); + } + + private void dispatchToObserver(DaemonEvent event) { + if ("permission_request".equals(event.getType())) { + event.requireSessionId(session.getSessionId(), "permission_request"); + observer.onPermission(PermissionRequest.from(event), event); + } + if ("session_update".equals(event.getType())) { + event.requireSessionId(session.getSessionId(), "session_update"); + Map update = event.update(); + String kind = event.updateKind(); + if ("agent_message_chunk".equals(kind)) { + String text = event.textChunk(); + if (text != null) { + observer.onText(text, event); + } + Map metadata = JsonSupport.extensionObject( + update.get("_meta")); + Map usage = metadata == null ? null + : JsonSupport.extensionObject(metadata.get("usage")); + if (usage != null) { + observer.onUsage(usage, event); + } + } else if ("agent_thought_chunk".equals(kind)) { + String text = event.textChunk(); + if (text != null) { + observer.onThought(text, event); + } + } else if ("tool_call".equals(kind) + || "tool_call_update".equals(kind)) { + observer.onTool(update, event); + } else if ("usage_update".equals(kind)) { + JsonSupport.requiredNonNegativeLong(update, "used", + "session_update.data.update"); + JsonSupport.requiredNonNegativeLong(update, "size", + "session_update.data.update"); + observer.onUsage(update, event); + } + } + observer.onEvent(event); + } + + private void notifyObserver(Runnable callback) { + synchronized (observerLifecycleLock) { + PromptOutcomeIndeterminateException stopped = stopFailure.get(); + if (stopped != null) { + throw stopped; + } + observerInProgress = true; + } + try { + callback.run(); + } finally { + synchronized (observerLifecycleLock) { + observerInProgress = false; + } + } + } + + private void reconnectOrThrow(int failures, + Duration retryAfter, long deadline, Throwable cause) { + checkStoppedOrExpired(deadline); + if (failures > client.maximumReconnectAttempts()) { + throw indeterminate("SSE reconnect attempts exhausted", cause); + } + long maximumDelayMillis = Math.min(5000L, + 250L << Math.min(failures - 1, 4)); + long delayMillis = retryAfter == null + ? ThreadLocalRandom.current().nextLong(maximumDelayMillis + 1) + : Math.min(5000L, retryAfter.toMillis()); + long remainingMillis = remainingMillis(deadline); + if (remainingMillis <= 0) { + throw indeterminate("Prompt observation timed out", cause); + } + delayMillis = Math.min(delayMillis, remainingMillis); + try { + Thread.sleep(delayMillis); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw stoppedOrIndeterminate("SSE reconnect was interrupted", e); + } + } + + private ScheduledFuture scheduleIdleWatchdog(InputStream stream, + AtomicLong lastActivity, AtomicBoolean idleClosed) { + long idleNanos = saturatedNanos(client.sseIdleTimeout()); + long intervalMillis = Math.max(100L, + saturatedMillis(client.sseIdleTimeout()) / 2L); + return client.scheduler().scheduleAtFixedRate(() -> { + if (System.nanoTime() - lastActivity.get() >= idleNanos + && idleClosed.compareAndSet(false, true)) { + requestStreamClose(stream); + } + }, intervalMillis, intervalMillis, TimeUnit.MILLISECONDS); + } + + private String readSseError(HttpResponse response, + long deadline) { + InputStream stream = response.body(); + activeStream.set(stream); + ScheduledFuture watchdog = null; + ScheduledFuture deadlineWatchdog = null; + try { + checkStoppedOrExpired(deadline); + long remaining = remainingMillis(deadline); + long requestLimit = saturatedMillis(client.requestTimeout()); + watchdog = client.scheduler().schedule( + () -> requestStreamClose(stream), + Math.min(remaining, requestLimit), TimeUnit.MILLISECONDS); + deadlineWatchdog = scheduleDeadlineWatchdog(deadline); + return HttpSupport.readError(stream, + "GET /session/:id/events"); + } finally { + if (watchdog != null) { + watchdog.cancel(false); + } + if (deadlineWatchdog != null) { + deadlineWatchdog.cancel(false); + } + requestStreamClose(stream); + } + } + + private ScheduledFuture scheduleDeadlineWatchdog(long deadline) { + return client.scheduler().schedule( + () -> stop(indeterminate( + "Prompt observation timed out", null)), + remainingNanos(deadline), TimeUnit.NANOSECONDS); + } + + private boolean claimTerminal(PromptTerminal terminal, long deadline) { + synchronized (outcomeLock) { + if (outcomeClaimed || System.nanoTime() >= deadline) { + return false; + } + outcomeClaimed = true; + terminalResult = terminal; + return true; + } + } + + private void requestStreamClose(InputStream stream) { + synchronized (streamLifecycleLock) { + if (activeStream.compareAndSet(stream, null)) { + streamClose = client.closeStreamAsync(stream); + } + } + } + + private void awaitPriorStreamClose(long deadline) { + CompletableFuture cleanup; + synchronized (streamLifecycleLock) { + cleanup = streamClose; + } + try { + cleanup.get(remainingMillis(deadline), TimeUnit.MILLISECONDS); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw stoppedOrIndeterminate( + "SSE stream closure was interrupted", e); + } catch (ExecutionException e) { + throw indeterminate("SSE stream closure failed", e.getCause()); + } catch (TimeoutException e) { + throw indeterminate( + "SSE stream closure exceeded the observation timeout", e); + } + } + + private void checkStoppedOrExpired(long deadline) { + PromptOutcomeIndeterminateException stopped = stopFailure.get(); + if (stopped != null) { + throw stopped; + } + if (System.nanoTime() >= deadline) { + throw indeterminate("Prompt observation timed out", null); + } + } + + private PromptOutcomeIndeterminateException stoppedOrIndeterminate( + String message, Throwable cause) { + PromptOutcomeIndeterminateException stopped = stopFailure.get(); + return stopped == null ? indeterminate(message, cause) : stopped; + } + + private PromptOutcomeIndeterminateException indeterminate( + String message, Throwable cause) { + return cause == null + ? new PromptOutcomeIndeterminateException(message, "") + : new PromptOutcomeIndeterminateException(message, cause, ""); + } + } + + private static DaemonEvent parseEvent(SseReader.Frame frame) { + Map envelope = JsonSupport.parseObject(frame.getData(), + "SSE data"); + int version = JsonSupport.requiredInt(envelope, "v", "SSE envelope"); + if (version != 1) { + throw new DaemonProtocolException("Unsupported SSE event version: " + version); + } + String type = JsonSupport.requiredString(envelope, "type", "SSE envelope"); + if (frame.getEvent() != null && !frame.getEvent().equals(type)) { + throw new DaemonProtocolException("SSE event field does not match envelope type"); + } + Long envelopeId = JsonSupport.optionalPositiveLong(envelope, "id", + "SSE envelope"); + if (!Objects.equals(frame.getId(), envelopeId)) { + throw new DaemonProtocolException("SSE id field does not match envelope id"); + } + if (envelopeId == null && !IDLESS_SYNTHETIC_EVENTS.contains(type)) { + throw new DaemonProtocolException( + "SSE event " + type + " must have a replayable event ID"); + } + if (!envelope.containsKey("data")) { + throw new DaemonProtocolException("SSE envelope.data is required"); + } + Object data = envelope.get("data"); + Map metadata = JsonSupport.optionalObject(envelope, "_meta"); + return new DaemonEvent(envelopeId, version, type, data, + JsonSupport.optionalString(envelope, "promptId"), + JsonSupport.optionalString(envelope, "originatorClientId"), + metadata == null ? Collections.emptyMap() : metadata); + } + + private static void validateSseHeaders(HttpHeaders headers) { + String contentType = headers.firstValue("Content-Type").orElse(""); + String mediaType = contentType.split(";", 2)[0].trim(); + if (!"text/event-stream".equalsIgnoreCase(mediaType)) { + throw new DaemonProtocolException( + "SSE response Content-Type is not text/event-stream"); + } + String contentEncoding = headers.firstValue("Content-Encoding") + .orElse("identity"); + if (!"identity".equalsIgnoreCase(contentEncoding)) { + throw new DaemonProtocolException("SSE response used unsupported Content-Encoding: " + + contentEncoding); + } + } + + private static Duration retryAfter(HttpHeaders headers) { + String value = headers.firstValue("Retry-After").orElse(null); + if (value == null) { + return null; + } + try { + long seconds = Long.parseLong(value.trim()); + return Duration.ofSeconds(Math.min(5, Math.max(0, seconds))); + } catch (NumberFormatException ignored) { + try { + ZonedDateTime time = ZonedDateTime.parse(value, + DateTimeFormatter.RFC_1123_DATE_TIME); + Duration result = Duration.between(ZonedDateTime.now(time.getZone()), time); + return result.isNegative() ? Duration.ZERO : result; + } catch (DateTimeParseException invalidDate) { + return null; + } + } + } + + private static long deadlineAfter(Duration timeout) { + long now = System.nanoTime(); + long nanos; + try { + nanos = timeout.toNanos(); + return Math.addExact(now, nanos); + } catch (ArithmeticException e) { + return Long.MAX_VALUE; + } + } + + private static long remainingMillis(long deadline) { + long remaining = deadline - System.nanoTime(); + if (remaining <= 0) { + return 0; + } + return Math.max(1L, TimeUnit.NANOSECONDS.toMillis(remaining)); + } + + private static long remainingNanos(long deadline) { + return Math.max(0L, deadline - System.nanoTime()); + } + + private static long saturatedMillis(Duration duration) { + try { + return Math.max(1L, duration.toMillis()); + } catch (ArithmeticException e) { + return Long.MAX_VALUE; + } + } + + private static long saturatedNanos(Duration duration) { + try { + return duration.toNanos(); + } catch (ArithmeticException e) { + return Long.MAX_VALUE; + } + } + + private static final class TextCollector implements PromptObserver { + private final long maximumBytes; + private final StringBuilder text = new StringBuilder(); + private long bytes; + private boolean pendingHighSurrogate; + + TextCollector(long maximumBytes) { + this.maximumBytes = maximumBytes; + } + + @Override + public void onText(String chunk, DaemonEvent event) { + boolean resolvesPendingSurrogate = pendingHighSurrogate + && !chunk.isEmpty(); + long chunkBytes = utf8Bytes(chunk); + if (chunkBytes > maximumBytes - bytes) { + String partialText = resolvesPendingSurrogate + ? text.substring(0, text.length() - 1) + : text.toString(); + throw new PromptContentLimitException(maximumBytes, partialText); + } + text.append(chunk); + bytes += chunkBytes; + } + + void finish() { + if (!pendingHighSurrogate) { + return; + } + if (bytes == maximumBytes) { + throw new PromptContentLimitException(maximumBytes, + text.substring(0, text.length() - 1)); + } + bytes++; + pendingHighSurrogate = false; + } + + private long utf8Bytes(String chunk) { + long result = 0; + int index = 0; + if (pendingHighSurrogate && !chunk.isEmpty()) { + if (Character.isLowSurrogate(chunk.charAt(0))) { + result += 4; + index = 1; + } else { + result++; + } + pendingHighSurrogate = false; + } + while (index < chunk.length()) { + char current = chunk.charAt(index++); + if (Character.isHighSurrogate(current)) { + if (index == chunk.length()) { + pendingHighSurrogate = true; + } else if (Character.isLowSurrogate(chunk.charAt(index))) { + result += 4; + index++; + } else { + result++; + } + } else if (Character.isLowSurrogate(current)) { + result++; + } else if (current <= 0x7f) { + result++; + } else if (current <= 0x7ff) { + result += 2; + } else { + result += 3; + } + } + return result; + } + + String getText() { + return text.toString(); + } + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonTransportException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonTransportException.java new file mode 100644 index 00000000000..f278204bc46 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DaemonTransportException.java @@ -0,0 +1,8 @@ +package com.alibaba.qwen.code.daemon; + +/** A transport failure for an operation whose outcome is otherwise known. */ +public class DaemonTransportException extends DaemonException { + DaemonTransportException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DetachOutcomeUnknownException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DetachOutcomeUnknownException.java new file mode 100644 index 00000000000..f0788ff005f --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/DetachOutcomeUnknownException.java @@ -0,0 +1,8 @@ +package com.alibaba.qwen.code.daemon; + +/** Detach may have succeeded, and close will not issue another detach. */ +public final class DetachOutcomeUnknownException extends MutationOutcomeUnknownException { + DetachOutcomeUnknownException(Throwable cause) { + super("POST /session/:id/detach", cause); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/HeartbeatResult.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/HeartbeatResult.java new file mode 100644 index 00000000000..8e49063b8c5 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/HeartbeatResult.java @@ -0,0 +1,26 @@ +package com.alibaba.qwen.code.daemon; + +/** Server timestamp returned after a session heartbeat. */ +public final class HeartbeatResult { + private final String sessionId; + private final String clientId; + private final long lastSeenAt; + + HeartbeatResult(String sessionId, String clientId, long lastSeenAt) { + this.sessionId = sessionId; + this.clientId = clientId; + this.lastSeenAt = lastSeenAt; + } + + public String getSessionId() { + return sessionId; + } + + public String getClientId() { + return clientId; + } + + public long getLastSeenAt() { + return lastSeenAt; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/HttpSupport.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/HttpSupport.java new file mode 100644 index 00000000000..515a3671ca0 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/HttpSupport.java @@ -0,0 +1,190 @@ +package com.alibaba.qwen.code.daemon; + +import java.io.ByteArrayOutputStream; +import java.net.http.HttpResponse; +import java.nio.ByteBuffer; +import java.nio.charset.CharacterCodingException; +import java.nio.charset.CodingErrorAction; +import java.nio.charset.StandardCharsets; +import java.util.List; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionStage; +import java.util.concurrent.Flow; + +final class HttpSupport { + static final int MAXIMUM_ERROR_BYTES = 64 * 1024; + static final int MAXIMUM_JSON_BYTES = 1024 * 1024; + + private HttpSupport() { + } + + static HttpResponse.BodyHandler bodyHandler() { + return responseInfo -> { + boolean success = responseInfo.statusCode() >= 200 + && responseInfo.statusCode() < 300; + return new BoundedBodySubscriber( + success ? MAXIMUM_JSON_BYTES : MAXIMUM_ERROR_BYTES); + }; + } + + static Response consume(HttpResponse response, String operation) { + Body body = response.body(); + byte[] bytes = body.getBytes(); + boolean success = response.statusCode() >= 200 + && response.statusCode() < 300; + if (body.isOverflow()) { + if (success) { + throw new DaemonProtocolException("JSON response exceeds " + + MAXIMUM_JSON_BYTES + " bytes"); + } + bytes = appendTruncationSuffix(bytes); + } + return new Response(response.statusCode(), + success ? decode(bytes, operation + " response") + : decodeError(bytes)); + } + + static String readError(java.io.InputStream input, + String operation) { + try { + byte[] bytes = input.readNBytes(MAXIMUM_ERROR_BYTES + 1); + if (bytes.length > MAXIMUM_ERROR_BYTES) { + byte[] prefix = new byte[MAXIMUM_ERROR_BYTES]; + System.arraycopy(bytes, 0, prefix, 0, prefix.length); + bytes = appendTruncationSuffix(prefix); + } + return decodeError(bytes); + } catch (java.io.IOException e) { + throw new DaemonTransportException(operation + + " response body could not be read", e); + } + } + + private static byte[] appendTruncationSuffix(byte[] bytes) { + byte[] suffix = "... (truncated)".getBytes(StandardCharsets.UTF_8); + int prefixLength = Math.max(0, MAXIMUM_ERROR_BYTES - suffix.length); + prefixLength = Math.min(prefixLength, bytes.length); + byte[] result = new byte[prefixLength + suffix.length]; + System.arraycopy(bytes, 0, result, 0, prefixLength); + System.arraycopy(suffix, 0, result, prefixLength, suffix.length); + return result; + } + + private static String decode(byte[] bytes, String context) { + try { + return StandardCharsets.UTF_8.newDecoder() + .onMalformedInput(CodingErrorAction.REPORT) + .onUnmappableCharacter(CodingErrorAction.REPORT) + .decode(ByteBuffer.wrap(bytes)).toString(); + } catch (CharacterCodingException e) { + throw new DaemonProtocolException(context + " contains invalid UTF-8", e); + } + } + + private static String decodeError(byte[] bytes) { + return new String(bytes, StandardCharsets.UTF_8); + } + + static final class Body { + private final byte[] bytes; + private final boolean overflow; + + Body(byte[] bytes, boolean overflow) { + this.bytes = bytes; + this.overflow = overflow; + } + + byte[] getBytes() { + return bytes; + } + + boolean isOverflow() { + return overflow; + } + } + + private static final class BoundedBodySubscriber + implements HttpResponse.BodySubscriber { + private final int limit; + private final ByteArrayOutputStream output = new ByteArrayOutputStream(); + private final CompletableFuture body = new CompletableFuture<>(); + private Flow.Subscription subscription; + + BoundedBodySubscriber(int limit) { + this.limit = limit; + } + + @Override + public CompletionStage getBody() { + return body; + } + + @Override + public void onSubscribe(Flow.Subscription newSubscription) { + if (subscription != null) { + newSubscription.cancel(); + return; + } + subscription = newSubscription; + newSubscription.request(Long.MAX_VALUE); + } + + @Override + public void onNext(List buffers) { + if (body.isDone()) { + return; + } + for (ByteBuffer buffer : buffers) { + int remainingCapacity = limit - output.size(); + if (buffer.remaining() > remainingCapacity) { + copy(buffer, remainingCapacity); + subscription.cancel(); + body.complete(new Body(output.toByteArray(), true)); + return; + } + copy(buffer, buffer.remaining()); + } + } + + @Override + public void onError(Throwable throwable) { + body.completeExceptionally(throwable); + } + + @Override + public void onComplete() { + body.complete(new Body(output.toByteArray(), false)); + } + + private void copy(ByteBuffer buffer, int count) { + if (count <= 0) { + return; + } + byte[] bytes = new byte[count]; + buffer.get(bytes); + output.write(bytes, 0, bytes.length); + } + } + + static final class Response { + private final int statusCode; + private final String body; + + Response(int statusCode, String body) { + this.statusCode = statusCode; + this.body = body; + } + + int getStatusCode() { + return statusCode; + } + + String getBody() { + return body; + } + + boolean isSuccess() { + return statusCode >= 200 && statusCode < 300; + } + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/JsonSupport.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/JsonSupport.java new file mode 100644 index 00000000000..366d19dc67d --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/JsonSupport.java @@ -0,0 +1,292 @@ +package com.alibaba.qwen.code.daemon; + +import com.alibaba.fastjson2.JSON; +import com.fasterxml.jackson.core.JsonFactory; +import com.fasterxml.jackson.core.JsonParser; +import com.fasterxml.jackson.core.JsonToken; +import com.fasterxml.jackson.core.StreamReadFeature; +import java.io.IOException; +import java.math.BigDecimal; +import java.math.BigInteger; +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +final class JsonSupport { + private static final JsonFactory STRICT_JSON = JsonFactory.builder() + .enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION) + .build(); + + private JsonSupport() { + } + + static String encode(Object value) { + return JSON.toJSONString(value); + } + + static Map parseObject(String json, String context) { + try (JsonParser parser = STRICT_JSON.createParser(json)) { + if (parser.nextToken() != JsonToken.START_OBJECT) { + throw new DaemonProtocolException(context + " must be a JSON object"); + } + Map parsed = readObject(parser, context); + if (parser.nextToken() != null) { + throw new DaemonProtocolException( + context + " must contain exactly one JSON value"); + } + return immutableObject(parsed); + } catch (IOException e) { + throw new DaemonProtocolException(context + " contains invalid JSON", e); + } + } + + private static Map readObject(JsonParser parser, String context) + throws IOException { + Map result = new LinkedHashMap<>(); + while (parser.nextToken() != JsonToken.END_OBJECT) { + if (parser.currentToken() != JsonToken.FIELD_NAME) { + throw new DaemonProtocolException(context + + " contains a malformed JSON object"); + } + String field = parser.currentName(); + JsonToken valueToken = parser.nextToken(); + if (valueToken == null) { + throw new DaemonProtocolException(context + + " contains an incomplete JSON object"); + } + result.put(field, readValue(parser, valueToken, context)); + } + return result; + } + + private static List readArray(JsonParser parser, String context) + throws IOException { + List result = new ArrayList<>(); + JsonToken token; + while ((token = parser.nextToken()) != JsonToken.END_ARRAY) { + if (token == null) { + throw new DaemonProtocolException(context + + " contains an incomplete JSON array"); + } + result.add(readValue(parser, token, context)); + } + return result; + } + + private static Object readValue(JsonParser parser, JsonToken token, + String context) throws IOException { + switch (token) { + case START_OBJECT: + return readObject(parser, context); + case START_ARRAY: + return readArray(parser, context); + case VALUE_STRING: + return parser.getText(); + case VALUE_NUMBER_INT: + return narrowInteger(parser.getBigIntegerValue()); + case VALUE_NUMBER_FLOAT: + return parser.getDecimalValue(); + case VALUE_TRUE: + return Boolean.TRUE; + case VALUE_FALSE: + return Boolean.FALSE; + case VALUE_NULL: + return null; + default: + throw new DaemonProtocolException(context + + " contains an unsupported JSON token"); + } + } + + private static Number narrowInteger(BigInteger value) { + if (value.bitLength() < Integer.SIZE) { + return value.intValue(); + } + if (value.bitLength() < Long.SIZE) { + return value.longValue(); + } + return value; + } + + static Map immutableObject(Map source) { + Map copy = new LinkedHashMap<>(); + for (Map.Entry entry : source.entrySet()) { + if (entry.getKey() == null) { + throw new IllegalArgumentException("JSON object key must not be null"); + } + copy.put(entry.getKey(), immutableValue(entry.getValue())); + } + return Collections.unmodifiableMap(copy); + } + + static String requiredString(Map object, String field, + String context) { + Object value = object.get(field); + if (!(value instanceof String) || ((String) value).isEmpty()) { + throw new DaemonProtocolException(context + "." + field + + " must be a non-empty string"); + } + return (String) value; + } + + static String optionalString(Map object, String field) { + Object value = object.get(field); + if (value == null) { + return null; + } + if (!(value instanceof String)) { + throw new DaemonProtocolException(field + " must be a string"); + } + return (String) value; + } + + static boolean requiredBoolean(Map object, String field, + String context) { + Object value = object.get(field); + if (!(value instanceof Boolean)) { + throw new DaemonProtocolException(context + "." + field + + " must be a boolean"); + } + return (Boolean) value; + } + + static long requiredNonNegativeLong(Map object, String field, + String context) { + Object value = object.get(field); + long result = exactLong(value, context + "." + field); + if (result < 0) { + throw new DaemonProtocolException(context + "." + field + + " must be non-negative"); + } + return result; + } + + static Long optionalPositiveLong(Map object, String field, + String context) { + Object value = object.get(field); + if (value == null) { + return null; + } + long result = exactLong(value, context + "." + field); + if (result <= 0) { + throw new DaemonProtocolException(context + "." + field + + " must be positive"); + } + return result; + } + + static int requiredInt(Map object, String field, + String context) { + long value = exactLong(object.get(field), context + "." + field); + if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE) { + throw new DaemonProtocolException(context + "." + field + + " is outside the integer range"); + } + return (int) value; + } + + static Map requiredObject(Map object, + String field, String context) { + Map value = optionalObject(object, field); + if (value == null) { + throw new DaemonProtocolException(context + "." + field + + " must be an object"); + } + return value; + } + + static Map optionalObject(Map object, + String field) { + Object value = object.get(field); + if (value == null) { + return null; + } + if (!(value instanceof Map)) { + throw new DaemonProtocolException(field + " must be an object"); + } + return castObject(value); + } + + static Map extensionObject(Object value) { + return value instanceof Map ? castObject(value) : null; + } + + static List optionalList(Map object, String field) { + Object value = object.get(field); + if (value == null) { + return null; + } + if (!(value instanceof List)) { + throw new DaemonProtocolException(field + " must be an array"); + } + return castList(value); + } + + static List stringList(Map object, String field) { + List values = optionalList(object, field); + if (values == null) { + throw new DaemonProtocolException(field + " must be an array"); + } + List result = new ArrayList<>(); + for (Object value : values) { + if (!(value instanceof String)) { + throw new DaemonProtocolException(field + " must contain only strings"); + } + result.add((String) value); + } + return result; + } + + private static long exactLong(Object value, String context) { + try { + if (value instanceof Byte || value instanceof Short + || value instanceof Integer || value instanceof Long) { + return ((Number) value).longValue(); + } + if (value instanceof BigInteger) { + return ((BigInteger) value).longValueExact(); + } + if (value instanceof BigDecimal) { + return ((BigDecimal) value).longValueExact(); + } + } catch (ArithmeticException e) { + throw new DaemonProtocolException(context + " must be an exact integer", e); + } + throw new DaemonProtocolException(context + " must be an integer"); + } + + private static Object immutableValue(Object value) { + if (value instanceof Map) { + return immutableObject(castObject(value)); + } + if (value instanceof List) { + List copy = new ArrayList<>(); + for (Object item : (List) value) { + copy.add(immutableValue(item)); + } + return Collections.unmodifiableList(copy); + } + if ((value instanceof Double && !Double.isFinite((Double) value)) + || (value instanceof Float && !Float.isFinite((Float) value))) { + throw new IllegalArgumentException("JSON numbers must be finite"); + } + if (value == null || value instanceof String || value instanceof Number + || value instanceof Boolean) { + return value; + } + throw new IllegalArgumentException("Unsupported JSON value type: " + + value.getClass().getName()); + } + + @SuppressWarnings("unchecked") + private static Map castObject(Object value) { + return (Map) value; + } + + @SuppressWarnings("unchecked") + private static List castList(Object value) { + return (List) value; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/MutationOutcomeUnknownException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/MutationOutcomeUnknownException.java new file mode 100644 index 00000000000..772800cac92 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/MutationOutcomeUnknownException.java @@ -0,0 +1,15 @@ +package com.alibaba.qwen.code.daemon; + +/** A non-idempotent request may have reached the daemon, so it was not retried. */ +public class MutationOutcomeUnknownException extends DaemonException { + private final String operation; + + MutationOutcomeUnknownException(String operation, Throwable cause) { + super(operation + " may have reached the daemon; the SDK did not retry it", cause); + this.operation = operation; + } + + public String getOperation() { + return operation; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PermissionRequest.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PermissionRequest.java new file mode 100644 index 00000000000..e29f4fc3745 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PermissionRequest.java @@ -0,0 +1,58 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.Collections; +import java.util.List; +import java.util.Map; + +/** A daemon permission request observed during a prompt. */ +public final class PermissionRequest { + private final String requestId; + private final Map toolCall; + private final List options; + + PermissionRequest(String requestId, Map toolCall, + List options) { + this.requestId = requestId; + this.toolCall = Collections.unmodifiableMap(toolCall); + this.options = Collections.unmodifiableList(options); + } + + static PermissionRequest from(DaemonEvent event) { + Map data = event.requireDataObject( + "permission_request.data"); + String requestId = JsonSupport.requiredString(data, "requestId", + "permission_request.data"); + Map toolCall = JsonSupport.requiredObject(data, "toolCall", + "permission_request.data"); + JsonSupport.requiredString(toolCall, "toolCallId", + "permission_request.data.toolCall"); + List options = JsonSupport.optionalList(data, "options"); + if (options == null) { + throw new DaemonProtocolException( + "permission_request.data.options must be an array"); + } + for (int i = 0; i < options.size(); i++) { + Map option = JsonSupport.extensionObject(options.get(i)); + if (option == null) { + throw new DaemonProtocolException( + "permission_request.data.options[" + i + + "] must be an object"); + } + JsonSupport.requiredString(option, "optionId", + "permission_request.data.options[" + i + "]"); + } + return new PermissionRequest(requestId, toolCall, options); + } + + public String getRequestId() { + return requestId; + } + + public Map getToolCall() { + return toolCall; + } + + public List getOptions() { + return options; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PermissionResponse.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PermissionResponse.java new file mode 100644 index 00000000000..da09636e85b --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PermissionResponse.java @@ -0,0 +1,57 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; + +/** A selected or cancelled response to a permission request. */ +public final class PermissionResponse { + private final Map outcome; + private final Map answers; + + private PermissionResponse(Map outcome, + Map answers) { + this.outcome = outcome; + this.answers = answers; + } + + public static PermissionResponse cancelled() { + Map outcome = new LinkedHashMap<>(); + outcome.put("outcome", "cancelled"); + return new PermissionResponse(outcome, Collections.emptyMap()); + } + + public static PermissionResponse selected(String optionId) { + if (optionId == null || optionId.isEmpty()) { + throw new IllegalArgumentException("optionId must not be empty"); + } + Map outcome = new LinkedHashMap<>(); + outcome.put("outcome", "selected"); + outcome.put("optionId", optionId); + return new PermissionResponse(outcome, Collections.emptyMap()); + } + + public PermissionResponse withAnswers(Map answers) { + if (answers == null) { + throw new IllegalArgumentException("answers must not be null"); + } + for (Map.Entry answer : answers.entrySet()) { + if (answer.getKey() == null || answer.getKey().isEmpty() + || answer.getValue() == null) { + throw new IllegalArgumentException( + "answer keys must be non-empty and values must not be null"); + } + } + return new PermissionResponse(outcome, + Collections.unmodifiableMap(new LinkedHashMap<>(answers))); + } + + Map toJson() { + Map result = new LinkedHashMap<>(); + result.put("outcome", outcome); + if (!answers.isEmpty()) { + result.put("answers", answers); + } + return result; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAcceptance.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAcceptance.java new file mode 100644 index 00000000000..c3259501e74 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAcceptance.java @@ -0,0 +1,20 @@ +package com.alibaba.qwen.code.daemon; + +/** The validated 202 admission watermark for a prompt. */ +public final class PromptAcceptance { + private final String promptId; + private final long lastEventId; + + PromptAcceptance(String promptId, long lastEventId) { + this.promptId = promptId; + this.lastEventId = lastEventId; + } + + public String getPromptId() { + return promptId; + } + + public long getLastEventId() { + return lastEventId; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAdmissionUnknownException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAdmissionUnknownException.java new file mode 100644 index 00000000000..a66a80d03f3 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAdmissionUnknownException.java @@ -0,0 +1,12 @@ +package com.alibaba.qwen.code.daemon; + +/** Prompt admission may have succeeded, so reposting could execute it twice. */ +public final class PromptAdmissionUnknownException extends MutationOutcomeUnknownException { + PromptAdmissionUnknownException(Throwable cause) { + super("POST /session/:id/prompt", cause); + } + + PromptAdmissionUnknownException(String message) { + super("POST /session/:id/prompt", new DaemonProtocolException(message)); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAlreadyActiveException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAlreadyActiveException.java new file mode 100644 index 00000000000..6f5666e5a6e --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptAlreadyActiveException.java @@ -0,0 +1,8 @@ +package com.alibaba.qwen.code.daemon; + +/** This session client already owns an unfinished local prompt call. */ +public final class PromptAlreadyActiveException extends DaemonException { + PromptAlreadyActiveException() { + super("DaemonSessionClient permits only one local prompt at a time"); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptCall.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptCall.java new file mode 100644 index 00000000000..6a4a4b58046 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptCall.java @@ -0,0 +1,73 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Executor; + +/** Independent prompt admission and reliable terminal stages. */ +public final class PromptCall { + private final CompletableFuture acceptance; + private final CompletableFuture completion; + + PromptCall(CompletableFuture acceptance, + CompletableFuture completion, Executor futureExecutor, + CountDownLatch terminalPublicationGate) { + this.acceptance = asyncView(acceptance, futureExecutor, null); + this.completion = asyncView(completion, futureExecutor, + terminalPublicationGate); + } + + /** + * Cancelling the returned view does not cancel the daemon prompt. + * + * @return an observation-only admission future + */ + public CompletableFuture acceptanceFuture() { + return acceptance.copy(); + } + + /** + * Cancelling the returned view does not cancel the daemon prompt. + * An indeterminate local timeout may complete this view before a blocked + * transport stream has finished closing; that outcome is not a signal that + * the session is safe to reuse. + * + * @return an observation-only terminal future + */ + public CompletableFuture completionFuture() { + return completion.copy(); + } + + private static CompletableFuture asyncView( + CompletableFuture source, Executor executor, + CountDownLatch publicationGate) { + CompletableFuture result = new CompletableFuture<>(); + source.whenCompleteAsync((value, failure) -> { + await(publicationGate); + if (failure == null) { + result.complete(value); + } else { + result.completeExceptionally(failure); + } + }, executor); + return result; + } + + private static void await(CountDownLatch gate) { + if (gate == null) { + return; + } + boolean interrupted = false; + while (true) { + try { + gate.await(); + break; + } catch (InterruptedException e) { + interrupted = true; + } + } + if (interrupted) { + Thread.currentThread().interrupt(); + } + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptContentLimitException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptContentLimitException.java new file mode 100644 index 00000000000..5add638716b --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptContentLimitException.java @@ -0,0 +1,15 @@ +package com.alibaba.qwen.code.daemon; + +/** Text collection stopped before a terminal because its configured cap was exceeded. */ +public final class PromptContentLimitException extends PromptOutcomeIndeterminateException { + private final long maximumBytes; + + PromptContentLimitException(long maximumBytes, String partialText) { + super("Prompt text exceeded the " + maximumBytes + " byte collection limit", partialText); + this.maximumBytes = maximumBytes; + } + + public long getMaximumBytes() { + return maximumBytes; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptObserver.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptObserver.java new file mode 100644 index 00000000000..f31d055986e --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptObserver.java @@ -0,0 +1,27 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.Map; + +/** Sequential callbacks for events correlated with one admitted prompt. */ +public interface PromptObserver { + PromptObserver NOOP = new PromptObserver() { + }; + + default void onText(String text, DaemonEvent event) { + } + + default void onThought(String thought, DaemonEvent event) { + } + + default void onTool(Map update, DaemonEvent event) { + } + + default void onUsage(Map usage, DaemonEvent event) { + } + + default void onPermission(PermissionRequest request, DaemonEvent event) { + } + + default void onEvent(DaemonEvent event) { + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptOutcomeIndeterminateException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptOutcomeIndeterminateException.java new file mode 100644 index 00000000000..0d9c9308685 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptOutcomeIndeterminateException.java @@ -0,0 +1,24 @@ +package com.alibaba.qwen.code.daemon; + +/** The SDK cannot prove whether or how the admitted prompt ended. */ +public class PromptOutcomeIndeterminateException extends DaemonException { + private final String partialText; + + PromptOutcomeIndeterminateException(String message, String partialText) { + super(message); + this.partialText = partialText; + } + + PromptOutcomeIndeterminateException(String message, Throwable cause, String partialText) { + super(message, cause); + this.partialText = partialText; + } + + public String getPartialText() { + return partialText; + } + + public boolean hasIncompletePartialText() { + return !partialText.isEmpty(); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptRequest.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptRequest.java new file mode 100644 index 00000000000..3f962335740 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptRequest.java @@ -0,0 +1,138 @@ +package com.alibaba.qwen.code.daemon; + +import java.time.Duration; +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** Prompt content plus daemon and local observation deadlines. */ +public final class PromptRequest { + private static final long MAX_DAEMON_DEADLINE_MILLIS = Integer.MAX_VALUE; + + private final List> content; + private final Long deadlineMillis; + private final Duration observationTimeout; + + private PromptRequest(List> content, + Long deadlineMillis, Duration observationTimeout) { + List> immutableContent = new ArrayList<>(); + for (Map block : content) { + immutableContent.add(JsonSupport.immutableObject(block)); + } + this.content = Collections.unmodifiableList(immutableContent); + this.deadlineMillis = deadlineMillis; + this.observationTimeout = observationTimeout; + } + + public static PromptRequest text(String text) { + if (text == null || text.isEmpty()) { + throw new IllegalArgumentException("text must not be empty"); + } + Map block = new LinkedHashMap<>(); + block.put("type", "text"); + block.put("text", text); + return new PromptRequest(Collections.singletonList(block), null, null); + } + + public static Builder builder() { + return new Builder(); + } + + public PromptRequest withObservationTimeout(Duration timeout) { + validateDuration(timeout, "observationTimeout"); + return new PromptRequest(new ArrayList<>(content), deadlineMillis, timeout); + } + + Map toJson() { + Map result = new LinkedHashMap<>(); + result.put("prompt", content); + if (deadlineMillis != null) { + result.put("deadlineMs", deadlineMillis); + } + return result; + } + + Duration observationTimeoutOr(Duration fallback) { + return observationTimeout == null ? fallback : observationTimeout; + } + + public List> getContent() { + return content; + } + + public Long getDeadlineMillis() { + return deadlineMillis; + } + + public Duration getObservationTimeout() { + return observationTimeout; + } + + private static void validateDuration(Duration duration, String name) { + if (duration == null || duration.isZero() || duration.isNegative()) { + throw new IllegalArgumentException(name + " must be positive"); + } + } + + public static final class Builder { + private final List> content = new ArrayList<>(); + private Long deadlineMillis; + private Duration observationTimeout; + + private Builder() { + } + + public Builder addText(String text) { + if (text == null || text.isEmpty()) { + throw new IllegalArgumentException("text must not be empty"); + } + Map block = new LinkedHashMap<>(); + block.put("type", "text"); + block.put("text", text); + content.add(block); + return this; + } + + public Builder addContent(Map block) { + if (block == null || block.isEmpty()) { + throw new IllegalArgumentException("content block must not be empty"); + } + content.add(JsonSupport.immutableObject(block)); + return this; + } + + public Builder deadline(Duration deadline) { + validateDuration(deadline, "deadline"); + try { + this.deadlineMillis = deadline.toMillis(); + } catch (ArithmeticException e) { + throw new IllegalArgumentException( + "deadline is outside the millisecond range", e); + } + if (deadlineMillis <= 0) { + throw new IllegalArgumentException("deadline must be at least one millisecond"); + } + if (deadlineMillis > MAX_DAEMON_DEADLINE_MILLIS) { + throw new IllegalArgumentException( + "deadline must not exceed 2147483647 milliseconds"); + } + return this; + } + + public Builder observationTimeout(Duration observationTimeout) { + validateDuration(observationTimeout, "observationTimeout"); + this.observationTimeout = observationTimeout; + return this; + } + + public PromptRequest build() { + if (content.isEmpty()) { + throw new IllegalStateException("at least one content block is required"); + } + return new PromptRequest(new ArrayList<>(content), deadlineMillis, + observationTimeout); + } + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTerminal.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTerminal.java new file mode 100644 index 00000000000..8bc403d6f94 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTerminal.java @@ -0,0 +1,68 @@ +package com.alibaba.qwen.code.daemon; + +import java.util.Map; + +/** A reliable terminal event correlated to an admitted prompt. */ +public final class PromptTerminal { + public enum Kind { + COMPLETE, + ERROR + } + + private final Kind kind; + private final String promptId; + private final String stopReason; + private final String code; + private final String message; + private final DaemonEvent event; + + PromptTerminal(Kind kind, String promptId, String stopReason, + String code, String message, DaemonEvent event) { + this.kind = kind; + this.promptId = promptId; + this.stopReason = stopReason; + this.code = code; + this.message = message; + this.event = event; + } + + static PromptTerminal from(DaemonEvent event, String promptId, + String sessionId) { + Map data = event.requireDataObject( + event.getType() + ".data"); + event.requireSessionId(sessionId, event.getType()); + if ("turn_complete".equals(event.getType())) { + return new PromptTerminal(Kind.COMPLETE, promptId, + JsonSupport.requiredString(data, "stopReason", + "turn_complete.data"), null, null, event); + } + return new PromptTerminal(Kind.ERROR, promptId, null, + JsonSupport.optionalString(data, "code"), + JsonSupport.requiredString(data, "message", "turn_error.data"), + event); + } + + public Kind getKind() { + return kind; + } + + public String getPromptId() { + return promptId; + } + + public String getStopReason() { + return stopReason; + } + + public String getCode() { + return code; + } + + public String getMessage() { + return message; + } + + public DaemonEvent getEvent() { + return event; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTextResult.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTextResult.java new file mode 100644 index 00000000000..2805aba58a8 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTextResult.java @@ -0,0 +1,20 @@ +package com.alibaba.qwen.code.daemon; + +/** Complete collected assistant text and its reliable terminal. */ +public final class PromptTextResult { + private final String text; + private final PromptTerminal terminal; + + PromptTextResult(String text, PromptTerminal terminal) { + this.text = text; + this.terminal = terminal; + } + + public String getText() { + return text; + } + + public PromptTerminal getTerminal() { + return terminal; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTurnException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTurnException.java new file mode 100644 index 00000000000..a1c3e3ac782 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/PromptTurnException.java @@ -0,0 +1,21 @@ +package com.alibaba.qwen.code.daemon; + +/** The daemon emitted a reliable matching turn_error terminal. */ +public final class PromptTurnException extends DaemonException { + private final PromptTerminal terminal; + private final String partialText; + + PromptTurnException(PromptTerminal terminal, String partialText) { + super(terminal.getMessage() == null ? "Prompt turn failed" : terminal.getMessage()); + this.terminal = terminal; + this.partialText = partialText; + } + + public PromptTerminal getTerminal() { + return terminal; + } + + public String getPartialText() { + return partialText; + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/SessionCreationOutcomeUnknownException.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/SessionCreationOutcomeUnknownException.java new file mode 100644 index 00000000000..7ee6c1ac17e --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/SessionCreationOutcomeUnknownException.java @@ -0,0 +1,8 @@ +package com.alibaba.qwen.code.daemon; + +/** Session creation may have succeeded, but its response was unavailable. */ +public final class SessionCreationOutcomeUnknownException extends MutationOutcomeUnknownException { + SessionCreationOutcomeUnknownException(Throwable cause) { + super("POST /session", cause); + } +} diff --git a/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/SseReader.java b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/SseReader.java new file mode 100644 index 00000000000..a6893a652e8 --- /dev/null +++ b/packages/sdk-java/qwencode/src/main/java/com/alibaba/qwen/code/daemon/SseReader.java @@ -0,0 +1,210 @@ +package com.alibaba.qwen.code.daemon; + +import java.io.BufferedInputStream; +import java.io.ByteArrayOutputStream; +import java.io.FilterInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.nio.ByteBuffer; +import java.nio.charset.CharacterCodingException; +import java.nio.charset.CodingErrorAction; +import java.nio.charset.StandardCharsets; + +final class SseReader { + private final BufferedInputStream input; + private final int maximumFrameBytes; + private Long retryMillis; + + SseReader(InputStream input, int maximumFrameBytes, Runnable activity) { + this.input = new BufferedInputStream(new ActivityInputStream(input, activity)); + this.maximumFrameBytes = maximumFrameBytes; + } + + Frame next() throws IOException { + ByteArrayOutputStream data = new ByteArrayOutputStream(); + String event = null; + Long id = null; + boolean hasData = false; + int frameBytes = 0; + while (true) { + byte[] line = readLine(); + if (line == null) { + return null; + } + frameBytes += line.length + 1; + if (frameBytes > maximumFrameBytes) { + throw new DaemonProtocolException("SSE frame exceeds " + + maximumFrameBytes + " bytes"); + } + String decoded = decode(line); + if (decoded.isEmpty()) { + if (!hasData) { + event = null; + id = null; + frameBytes = 0; + continue; + } + String payload = decode(data.toByteArray()); + if (payload.endsWith("\n")) { + payload = payload.substring(0, payload.length() - 1); + } + return new Frame(event, id, payload); + } + if (decoded.charAt(0) == ':') { + continue; + } + int colon = decoded.indexOf(':'); + String field = colon < 0 ? decoded : decoded.substring(0, colon); + String value = colon < 0 ? "" : decoded.substring(colon + 1); + if (value.startsWith(" ")) { + value = value.substring(1); + } + switch (field) { + case "data": + if (hasData) { + data.write('\n'); + } + data.write(value.getBytes(StandardCharsets.UTF_8)); + hasData = true; + break; + case "event": + if (value.isEmpty()) { + throw new DaemonProtocolException("SSE event name must not be empty"); + } + event = value; + break; + case "id": + id = parseId(value); + break; + case "retry": + Long parsedRetry = parseRetry(value); + if (parsedRetry != null) { + retryMillis = parsedRetry; + } + break; + default: + break; + } + } + } + + private static final class ActivityInputStream extends FilterInputStream { + private final Runnable activity; + + ActivityInputStream(InputStream input, Runnable activity) { + super(input); + this.activity = activity; + } + + @Override + public int read() throws IOException { + int result = super.read(); + if (result >= 0) { + activity.run(); + } + return result; + } + + @Override + public int read(byte[] bytes, int offset, int length) throws IOException { + int result = super.read(bytes, offset, length); + if (result > 0) { + activity.run(); + } + return result; + } + } + + private byte[] readLine() throws IOException { + ByteArrayOutputStream line = new ByteArrayOutputStream(); + while (true) { + int next = input.read(); + if (next < 0) { + return null; + } + if (next == '\n') { + byte[] bytes = line.toByteArray(); + if (bytes.length > 0 && bytes[bytes.length - 1] == '\r') { + byte[] withoutCarriageReturn = new byte[bytes.length - 1]; + System.arraycopy(bytes, 0, withoutCarriageReturn, 0, + withoutCarriageReturn.length); + return withoutCarriageReturn; + } + return bytes; + } + line.write(next); + if (line.size() > maximumFrameBytes) { + throw new DaemonProtocolException("SSE line exceeds " + + maximumFrameBytes + " bytes"); + } + } + } + + private static String decode(byte[] bytes) { + try { + return StandardCharsets.UTF_8.newDecoder() + .onMalformedInput(CodingErrorAction.REPORT) + .onUnmappableCharacter(CodingErrorAction.REPORT) + .decode(ByteBuffer.wrap(bytes)).toString(); + } catch (CharacterCodingException e) { + throw new DaemonProtocolException("SSE contains invalid UTF-8", e); + } + } + + private static Long parseId(String value) { + if (value.isEmpty() || !value.chars().allMatch(Character::isDigit)) { + throw new DaemonProtocolException("SSE id must be a positive integer"); + } + try { + long id = Long.parseLong(value); + if (id <= 0) { + throw new DaemonProtocolException("SSE id must be positive"); + } + return id; + } catch (NumberFormatException e) { + throw new DaemonProtocolException("SSE id is outside the long range", e); + } + } + + Long getRetryMillis() { + return retryMillis; + } + + private static Long parseRetry(String value) { + if (value.isEmpty()) { + return null; + } + if (!value.chars().allMatch(Character::isDigit)) { + throw new DaemonProtocolException("SSE retry must be a non-negative integer"); + } + try { + return Long.parseLong(value); + } catch (NumberFormatException e) { + throw new DaemonProtocolException("SSE retry is outside the long range", e); + } + } + + static final class Frame { + private final String event; + private final Long id; + private final String data; + + Frame(String event, Long id, String data) { + this.event = event; + this.id = id; + this.data = data; + } + + String getEvent() { + return event; + } + + Long getId() { + return id; + } + + String getData() { + return data; + } + } +} diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/QwenCodeCliTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/QwenCodeCliTest.java index ca10173f71e..a10e34d0907 100644 --- a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/QwenCodeCliTest.java +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/QwenCodeCliTest.java @@ -5,11 +5,13 @@ import com.alibaba.qwen.code.cli.transport.TransportOptions; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Tag; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import static org.junit.jupiter.api.Assertions.*; +@Tag("integration") class QwenCodeCliTest { private static final Logger log = LoggerFactory.getLogger(QwenCodeCliTest.class); diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/session/SessionTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/session/SessionTest.java index eef0fde6163..fdafe382daa 100644 --- a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/session/SessionTest.java +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/session/SessionTest.java @@ -26,6 +26,7 @@ import org.apache.commons.lang3.StringUtils; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Tag; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -34,6 +35,7 @@ class SessionTest { private static final Logger log = LoggerFactory.getLogger(SessionTest.class); @Test + @Tag("integration") void partialSendPromptSuccessfully() throws SessionControlException, SessionSendPromptException { Session session = QwenCodeCli.newSession(new TransportOptions().setIncludePartialMessages(true)); session.sendPrompt("in the dir src/test/temp/, create file empty file test.touch", new SessionEventSimpleConsumers() { @@ -70,6 +72,7 @@ public void onUsage(Session session, AssistantUsage assistantUsage) { } @Test + @Tag("integration") void setPermissionModeSuccessfully() throws SessionControlException, SessionSendPromptException { Session session = QwenCodeCli.newSession(new TransportOptions()); @@ -92,6 +95,7 @@ void setPermissionModeSuccessfully() throws SessionControlException, SessionSend } @Test + @Tag("integration") void sendPromptAndSetModelSuccessfully() throws SessionControlException, SessionSendPromptException { Session session = QwenCodeCli.newSession(new TransportOptions()); @@ -117,6 +121,7 @@ void sendPromptAndSetModelSuccessfully() throws SessionControlException, Session } @Test + @Tag("integration") void sendPromptAndInterruptContinueSuccessfully() throws SessionControlException, SessionSendPromptException { Session session = QwenCodeCli.newSession(); diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/transport/process/ProcessTransportTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/transport/process/ProcessTransportTest.java index adff3c115b2..1813d421e05 100644 --- a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/transport/process/ProcessTransportTest.java +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/cli/transport/process/ProcessTransportTest.java @@ -4,7 +4,8 @@ import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; -import java.util.Collections; +import java.util.HashMap; +import java.util.Map; import java.util.UUID; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeoutException; @@ -20,6 +21,10 @@ import com.alibaba.qwen.code.cli.transport.TransportOptions; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.condition.DisabledOnOs; +import org.junit.jupiter.api.condition.EnabledOnOs; +import org.junit.jupiter.api.condition.OS; import org.junit.jupiter.api.io.TempDir; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -36,6 +41,7 @@ class ProcessTransportTest { Path tempDir; @Test + @Tag("integration") void shouldStartAndCloseSuccessfully() throws IOException { TransportOptions transportOptions = new TransportOptions(); Transport transport = new ProcessTransport(transportOptions); @@ -43,11 +49,14 @@ void shouldStartAndCloseSuccessfully() throws IOException { } @Test + @DisabledOnOs(OS.WINDOWS) void shouldPassCustomEnvToProcess() throws IOException { Path executable = createEnvPrinter(); + Map environment = new HashMap<>(System.getenv()); + environment.put(CUSTOM_ENV_NAME, CUSTOM_ENV_VALUE); TransportOptions transportOptions = new TransportOptions() .setPathToQwenExecutable(executable.toString()) - .setEnv(Collections.singletonMap(CUSTOM_ENV_NAME, CUSTOM_ENV_VALUE)); + .setEnv(environment); ProcessTransport transport = new ProcessTransport(transportOptions); try { @@ -58,6 +67,16 @@ void shouldPassCustomEnvToProcess() throws IOException { } @Test + @EnabledOnOs(OS.WINDOWS) + void shouldStartAndCloseNativeWindowsProcess() throws IOException { + TransportOptions transportOptions = new TransportOptions() + .setPathToQwenExecutable("where.exe"); + Transport transport = new ProcessTransport(transportOptions); + transport.close(); + } + + @Test + @Tag("integration") void shouldInputWaitForOneLineSuccessfully() throws IOException, ExecutionException, InterruptedException, TimeoutException { TransportOptions transportOptions = new TransportOptions(); Transport transport = new ProcessTransport(transportOptions); @@ -67,6 +86,7 @@ void shouldInputWaitForOneLineSuccessfully() throws IOException, ExecutionExcept } @Test + @Tag("integration") void shouldInitializeSuccessfully() throws IOException, ExecutionException, InterruptedException, TimeoutException { Transport transport = new ProcessTransport(); @@ -79,6 +99,7 @@ void shouldInitializeSuccessfully() throws IOException, ExecutionException, Inte } @Test + @Tag("integration") void shouldSdkMessageSuccessfully() throws IOException, ExecutionException, InterruptedException, TimeoutException { Transport transport = new ProcessTransport(); String message = CLIControlRequest.create(new CLIControlInitializeRequest()).toString(); diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonServeE2ETest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonServeE2ETest.java new file mode 100644 index 00000000000..895fe264c82 --- /dev/null +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonServeE2ETest.java @@ -0,0 +1,242 @@ +package com.alibaba.qwen.code.daemon; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.time.Duration; +import java.util.Map; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable; + +@Tag("daemon-integration") +@EnabledIfEnvironmentVariable(named = "QWEN_DAEMON_E2E_BASE_URL", matches = ".+") +class DaemonServeE2ETest { + @Test + void runsPromptToolPermissionAndTerminalAgainstRealDaemon() throws Exception { + String workspace = System.getenv("QWEN_DAEMON_E2E_WORKSPACE"); + String expectedText = System.getenv().getOrDefault( + "QWEN_DAEMON_E2E_EXPECTED_TEXT", "java daemon e2e complete"); + + try (DaemonClient daemon = newDaemonClient(); + DaemonSessionClient session = createSession(daemon)) { + AtomicInteger tools = new AtomicInteger(); + AtomicInteger permissions = new AtomicInteger(); + StringBuilder text = new StringBuilder(); + PromptObserver observer = new PromptObserver() { + @Override + public void onText(String chunk, DaemonEvent event) { + text.append(chunk); + } + + @Override + public void onTool(Map update, + DaemonEvent event) { + tools.incrementAndGet(); + } + + @Override + public void onPermission(PermissionRequest permission, + DaemonEvent event) { + permissions.incrementAndGet(); + assertTrue(session.respondToPermission( + permission.getRequestId(), + PermissionResponse.selected(firstOption(permission)))); + } + + @Override + public void onEvent(DaemonEvent event) { + System.out.println("Java daemon E2E event: " + + event.getType() + " #" + event.getId()); + } + }; + + PromptTerminal terminal = session.startPrompt(PromptRequest.text( + "Create the requested test file, then report completion."), + observer).completionFuture() + .orTimeout(30, TimeUnit.SECONDS).join(); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + assertTrue(text.toString().contains(expectedText)); + assertTrue(tools.get() > 0); + assertTrue(permissions.get() > 0); + if (workspace != null && !workspace.isBlank()) { + assertEquals("created by Java daemon E2E", Files.readString( + Path.of(workspace, "created.txt"), + StandardCharsets.UTF_8)); + } + } + } + + @Test + void deadlineTerminalIsReliableAndSessionRemainsReusable() { + String deadlinePrompt = requiredEnvironment( + "QWEN_DAEMON_E2E_DEADLINE_PROMPT"); + String directPrompt = requiredEnvironment( + "QWEN_DAEMON_E2E_DIRECT_PROMPT"); + String expectedText = System.getenv().getOrDefault( + "QWEN_DAEMON_E2E_EXPECTED_TEXT", "java daemon e2e complete"); + + try (DaemonClient daemon = newDaemonClient(); + DaemonSessionClient session = createSession(daemon)) { + PromptTurnException failure = assertThrows(PromptTurnException.class, + () -> session.promptText(PromptRequest.builder() + .addText(deadlinePrompt) + .deadline(Duration.ofMillis(500)) + .build())); + assertEquals("prompt_deadline_exceeded", + failure.getTerminal().getCode()); + + PromptTextResult followUp = session.promptText(directPrompt); + assertEquals(PromptTerminal.Kind.COMPLETE, + followUp.getTerminal().getKind()); + assertTrue(followUp.getText().contains(expectedText)); + } + } + + @Test + void cancelledPromptReceivesReliableTerminal() throws Exception { + String cancelPrompt = requiredEnvironment( + "QWEN_DAEMON_E2E_CANCEL_PROMPT"); + String directPrompt = requiredEnvironment( + "QWEN_DAEMON_E2E_DIRECT_PROMPT"); + String expectedText = System.getenv().getOrDefault( + "QWEN_DAEMON_E2E_EXPECTED_TEXT", "java daemon e2e complete"); + CountDownLatch streamReady = new CountDownLatch(1); + + try (DaemonClient daemon = newDaemonClient(); + DaemonSessionClient session = createSession(daemon)) { + PromptCall call = session.startPrompt(PromptRequest.text(cancelPrompt), + streamReadyObserver(streamReady)); + call.acceptanceFuture().get(5, TimeUnit.SECONDS); + assertTrue(streamReady.await(5, TimeUnit.SECONDS)); + session.cancelActivePrompt(); + + PromptTerminal terminal = call.completionFuture() + .get(10, TimeUnit.SECONDS); + if (terminal.getKind() == PromptTerminal.Kind.COMPLETE) { + assertEquals("cancelled", terminal.getStopReason()); + } else { + assertEquals("-32603", terminal.getCode()); + assertEquals("Request was aborted.", terminal.getMessage()); + } + + PromptTextResult followUp = session.promptText(directPrompt); + assertTrue(followUp.getText().contains(expectedText)); + } + } + + @Test + void teardownDeliversTerminalBeforeSessionFailure() throws Exception { + String teardownPrompt = requiredEnvironment( + "QWEN_DAEMON_E2E_TEARDOWN_PROMPT"); + String baseUrl = requiredEnvironment("QWEN_DAEMON_E2E_BASE_URL"); + String token = System.getenv("QWEN_DAEMON_E2E_TOKEN"); + CountDownLatch permissionPending = new CountDownLatch(1); + + try (DaemonClient daemon = newDaemonClient()) { + DaemonSessionClient session = createSession(daemon); + try { + PromptCall call = session.startPrompt( + PromptRequest.text(teardownPrompt), + eventObserver("permission_request", permissionPending)); + call.acceptanceFuture().get(5, TimeUnit.SECONDS); + assertTrue(permissionPending.await(10, TimeUnit.SECONDS)); + + HttpRequest.Builder request = HttpRequest.newBuilder() + .uri(URI.create(baseUrl + "/session/" + + session.getSessionId())) + .header("X-Qwen-Client-Id", session.getClientId()) + .DELETE(); + if (token != null && !token.isBlank()) { + request.header("Authorization", "Bearer " + token); + } + try { + HttpResponse response = HttpClient.newBuilder() + .version(HttpClient.Version.HTTP_1_1) + .build() + .send(request.build(), + HttpResponse.BodyHandlers.discarding()); + assertEquals(204, response.statusCode()); + } catch (java.io.IOException ignored) { + // The terminal below proves that the ambiguous DELETE ran. + } + + PromptTerminal terminal = call.completionFuture() + .get(10, TimeUnit.SECONDS); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + assertEquals("cancelled", terminal.getStopReason()); + } finally { + session.destroySession(); + } + } + } + + private static DaemonClient newDaemonClient() { + String token = System.getenv("QWEN_DAEMON_E2E_TOKEN"); + DaemonClient.Builder builder = DaemonClient.builder() + .baseUri(URI.create(requiredEnvironment( + "QWEN_DAEMON_E2E_BASE_URL"))) + .heartbeatInterval(Duration.ZERO); + if (token != null && !token.isBlank()) { + builder.bearerToken(token); + } + return builder.build(); + } + + private static DaemonSessionClient createSession(DaemonClient daemon) { + String workspace = System.getenv("QWEN_DAEMON_E2E_WORKSPACE"); + CreateSessionRequest.Builder request = CreateSessionRequest.builder() + .approvalMode(DaemonApprovalMode.DEFAULT); + if (workspace != null && !workspace.isBlank()) { + request.workspaceCwd(workspace); + } + return daemon.createSession(request.build()); + } + + private static PromptObserver streamReadyObserver(CountDownLatch ready) { + return eventObserver("replay_complete", ready); + } + + private static PromptObserver eventObserver(String eventType, + CountDownLatch ready) { + return new PromptObserver() { + @Override + public void onEvent(DaemonEvent event) { + if (eventType.equals(event.getType())) { + ready.countDown(); + } + } + }; + } + + private static String requiredEnvironment(String name) { + String value = System.getenv(name); + if (value == null || value.isBlank()) { + throw new IllegalStateException(name + " is required"); + } + return value; + } + + private static String firstOption(PermissionRequest permission) { + for (Object option : permission.getOptions()) { + if (option instanceof Map) { + Object optionId = ((Map) option).get("optionId"); + if (optionId instanceof String) { + return (String) optionId; + } + } + } + throw new AssertionError("Permission request did not contain an optionId"); + } +} diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonSessionClientTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonSessionClientTest.java new file mode 100644 index 00000000000..cd964d11b87 --- /dev/null +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/DaemonSessionClientTest.java @@ -0,0 +1,2726 @@ +package com.alibaba.qwen.code.daemon; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.fail; + +import com.sun.net.httpserver.HttpExchange; +import com.sun.net.httpserver.HttpHandler; +import com.sun.net.httpserver.HttpServer; +import java.io.ByteArrayInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.net.InetSocketAddress; +import java.net.URI; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionException; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +class DaemonSessionClientTest { + + private HttpServer server; + private ExecutorService serverExecutor; + private URI baseUri; + private AtomicReference createBody; + + @BeforeEach + void setUp() throws IOException { + server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0); + serverExecutor = Executors.newCachedThreadPool(); + createBody = new AtomicReference<>(); + server.setExecutor(serverExecutor); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[" + + "\"session_scope_override\",\"client_heartbeat\"," + + "\"prompt_absolute_deadline\"]," + + "\"transports\":[\"rest\"]}")); + server.createContext("/session", exchange -> { + if ("POST".equals(exchange.getRequestMethod()) + && "/session".equals(exchange.getRequestURI().getPath())) { + createBody.set(new String(exchange.getRequestBody().readAllBytes(), + StandardCharsets.UTF_8)); + sendJson(exchange, 200, sessionJson()); + return; + } + sendJson(exchange, 404, "{}"); + }); + server.start(); + baseUri = URI.create("http://127.0.0.1:" + server.getAddress().getPort()); + } + + @AfterEach + void tearDown() { + if (server != null) { + server.stop(0); + } + if (serverExecutor != null) { + serverExecutor.shutdownNow(); + } + } + + @Test + void replaysTextAndTerminalEmittedBeforeAdmissionResponse() { + AtomicReference lastEventId = new AtomicReference<>(); + AtomicReference acceptEncoding = new AtomicReference<>(); + AtomicReference authorization = new AtomicReference<>(); + AtomicReference clientId = new AtomicReference<>(); + AtomicReference promptBody = new AtomicReference<>(); + AtomicReference replay = new AtomicReference<>(); + server.createContext("/session/session-1/prompt", exchange -> { + promptBody.set(new String(exchange.getRequestBody().readAllBytes(), + StandardCharsets.UTF_8)); + replay.set(textEvent(1, "hello") + terminalEvent(2)); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> { + lastEventId.set(exchange.getRequestHeaders().getFirst("Last-Event-ID")); + acceptEncoding.set(exchange.getRequestHeaders().getFirst("Accept-Encoding")); + authorization.set(exchange.getRequestHeaders().getFirst("Authorization")); + clientId.set(exchange.getRequestHeaders().getFirst("X-Qwen-Client-Id")); + sendSse(exchange, replay.get()); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder().bearerToken("test-token").build(); + DaemonSessionClient session = daemon.createSession()) { + PromptTextResult result = session.promptText(PromptRequest.builder() + .addText("say hello") + .deadline(Duration.ofMillis(1234)) + .build()); + assertEquals("hello", result.getText()); + assertEquals(PromptTerminal.Kind.COMPLETE, result.getTerminal().getKind()); + assertEquals("0", lastEventId.get()); + assertEquals("identity", acceptEncoding.get()); + assertEquals("Bearer test-token", authorization.get()); + assertEquals("client-1", clientId.get()); + assertTrue(createBody.get().contains("\"sessionScope\":\"thread\"")); + assertTrue(promptBody.get().contains("\"deadlineMs\":1234")); + } + } + + @Test + void exposesCapabilitiesWithoutFastjsonTypes() { + server.removeContext("/capabilities"); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[" + + "\"session_events\"],\"transports\":[\"rest\"]," + + "\"workspaceCwd\":\"/tmp/work\"}")); + + try (DaemonClient daemon = newClient()) { + DaemonCapabilities capabilities = daemon.capabilities(); + assertTrue(capabilities.supports("session_events")); + assertEquals(List.of("rest"), capabilities.getTransports()); + assertTrue(!capabilities.getRaw().getClass().getName() + .startsWith("com.alibaba.fastjson2")); + } + } + + @Test + void rejectsCredentialsInBaseUri() { + IllegalArgumentException failure = assertThrows( + IllegalArgumentException.class, + () -> DaemonClient.builder() + .baseUri(URI.create("http://user:password@127.0.0.1:4170")) + .build()); + assertTrue(failure.getMessage().contains("without credentials")); + } + + @Test + void rejectsMissingCapabilitiesTransports() { + server.removeContext("/capabilities"); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[]}")); + + try (DaemonClient daemon = newClient()) { + assertThrows(DaemonProtocolException.class, daemon::capabilities); + } + } + + @Test + void refusesToCreateWhenThreadScopeCannotBeGuaranteed() { + server.removeContext("/capabilities"); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[]," + + "\"transports\":[\"rest\"]}")); + + try (DaemonClient daemon = newClient()) { + assertThrows(DaemonProtocolException.class, daemon::createSession); + assertEquals(null, createBody.get()); + } + } + + @Test + void refusesToCreateWhenRestTransportIsNotAdvertised() { + server.removeContext("/capabilities"); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[" + + "\"session_scope_override\"]," + + "\"transports\":[\"websocket\"]}")); + + try (DaemonClient daemon = newClient()) { + assertThrows(DaemonProtocolException.class, daemon::createSession); + assertEquals(null, createBody.get()); + } + } + + @Test + void slowSessionCreationDoesNotBlockExistingSessionMutation() + throws Exception { + CountDownLatch createStarted = new CountDownLatch(1); + CountDownLatch releaseCreate = new CountDownLatch(1); + CountDownLatch cancelReceived = new CountDownLatch(1); + server.createContext("/session/session-1/cancel", exchange -> { + cancelReceived.countDown(); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + server.createContext("/session/session-2/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient first = daemon.createSession()) { + server.removeContext("/session"); + server.createContext("/session", exchange -> { + createStarted.countDown(); + await(releaseCreate); + sendJson(exchange, 200, + sessionJson("session-2", "client-2")); + }); + CompletableFuture creating = + CompletableFuture.supplyAsync(daemon::createSession); + try { + assertTrue(createStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture cancelling = CompletableFuture.runAsync( + first::cancelActivePrompt); + assertTrue(cancelReceived.await(1, TimeUnit.SECONDS)); + cancelling.get(1, TimeUnit.SECONDS); + } finally { + releaseCreate.countDown(); + } + try (DaemonSessionClient second = creating.get(1, TimeUnit.SECONDS)) { + assertEquals("session-2", second.getSessionId()); + } + } + } + + @Test + void clientCloseDetachesSessionCreatedByLosingRace() throws Exception { + CountDownLatch createStarted = new CountDownLatch(1); + CountDownLatch releaseCreate = new CountDownLatch(1); + CountDownLatch detachReceived = new CountDownLatch(1); + AtomicReference detachedClient = new AtomicReference<>(); + server.removeContext("/session"); + server.createContext("/session", exchange -> { + createStarted.countDown(); + await(releaseCreate); + sendJson(exchange, 200, sessionJson("session-2", "client-2")); + }); + server.createContext("/session/session-2/detach", exchange -> { + detachedClient.set(exchange.getRequestHeaders() + .getFirst("X-Qwen-Client-Id")); + detachReceived.countDown(); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + + DaemonClient daemon = newClient(); + CompletableFuture creating = + CompletableFuture.supplyAsync(daemon::createSession); + try { + assertTrue(createStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture.runAsync(daemon::close) + .get(1, TimeUnit.SECONDS); + assertTrue(!creating.isDone()); + releaseCreate.countDown(); + CompletionException failure = assertThrows( + CompletionException.class, creating::join); + assertInstanceOf(IllegalStateException.class, failure.getCause()); + assertTrue(detachReceived.await(1, TimeUnit.SECONDS)); + assertEquals("client-2", detachedClient.get()); + } finally { + releaseCreate.countDown(); + daemon.close(); + } + } + + @Test + void refusesDeadlineBeforePromptWhenDaemonCannotGuaranteeIt() { + AtomicInteger promptRequests = new AtomicInteger(); + server.removeContext("/capabilities"); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[" + + "\"session_scope_override\"]," + + "\"transports\":[\"rest\"]}")); + server.createContext("/session/session-1/prompt", exchange -> { + promptRequests.incrementAndGet(); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptRequest request = PromptRequest.builder() + .addText("go") + .deadline(Duration.ofSeconds(1)) + .build(); + assertThrows(DaemonProtocolException.class, + () -> session.startPrompt(request, PromptObserver.NOOP)); + assertEquals(0, promptRequests.get()); + } + } + + @Test + void rejectsDeadlineOutsideMillisecondRange() { + assertThrows(IllegalArgumentException.class, + () -> PromptRequest.builder().addText("go") + .deadline(Duration.ofSeconds(Long.MAX_VALUE))); + } + + @Test + void enforcesDaemonDeadlineTimerRange() { + PromptRequest maximum = PromptRequest.builder().addText("go") + .deadline(Duration.ofMillis(Integer.MAX_VALUE)) + .build(); + assertEquals(Long.valueOf(Integer.MAX_VALUE), + maximum.getDeadlineMillis()); + assertThrows(IllegalArgumentException.class, + () -> PromptRequest.builder().addText("go") + .deadline(Duration.ofMillis( + (long) Integer.MAX_VALUE + 1L))); + } + + @Test + void reconnectsFromCommittedCursorAndDeduplicatesReplay() { + AtomicInteger subscriptions = new AtomicInteger(); + List cursors = new ArrayList<>(); + List observed = new ArrayList<>(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + synchronized (cursors) { + cursors.add(exchange.getRequestHeaders().getFirst("Last-Event-ID")); + } + if (subscriptions.incrementAndGet() == 1) { + sendSse(exchange, textEvent(1, "one")); + } else { + sendSse(exchange, textEvent(1, "duplicate") + terminalEvent(2)); + } + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onText(String text, DaemonEvent event) { + observed.add(text); + } + }); + assertEquals(PromptTerminal.Kind.COMPLETE, + call.completionFuture().join().getKind()); + } + assertEquals(List.of("one"), observed); + assertEquals(List.of("0", "1"), cursors); + } + + @Test + void retainsServerRetryDelayAcrossSseConnections() { + AtomicInteger subscriptions = new AtomicInteger(); + List openedAt = new ArrayList<>(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + synchronized (openedAt) { + openedAt.add(System.nanoTime()); + } + int attempt = subscriptions.incrementAndGet(); + if (attempt == 1) { + byte[] retry = "retry: 1000\n\n".getBytes(StandardCharsets.UTF_8); + exchange.getResponseHeaders().set("Content-Type", + "text/event-stream"); + exchange.sendResponseHeaders(200, retry.length); + exchange.getResponseBody().write(retry); + exchange.close(); + } else if (attempt == 2) { + exchange.getResponseHeaders().set("Content-Type", + "text/event-stream"); + exchange.sendResponseHeaders(200, -1); + exchange.close(); + } else { + sendSse(exchange, terminalEvent(1)); + } + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + assertEquals(PromptTerminal.Kind.COMPLETE, + session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join().getKind()); + } + assertEquals(3, openedAt.size()); + assertTrue(Duration.ofNanos(openedAt.get(1) - openedAt.get(0)) + .toMillis() >= 800); + assertTrue(Duration.ofNanos(openedAt.get(2) - openedAt.get(1)) + .toMillis() >= 800); + } + + @Test + void failsClosedOnIdGapAndReturnsIncompletePartialText() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "partial") + terminalEvent(3))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptOutcomeIndeterminateException failure = assertThrows( + PromptOutcomeIndeterminateException.class, + () -> session.promptText("go")); + assertEquals("partial", failure.getPartialText()); + assertTrue(failure.hasIncompletePartialText()); + } + } + + @Test + void malformedTextChunkCannotBecomeTruncatedSuccess() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + updateEvent(1, "agent_message_chunk", + "\"content\":{\"type\":\"text\"}") + + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptOutcomeIndeterminateException failure = assertThrows( + PromptOutcomeIndeterminateException.class, + () -> session.promptText("go")); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + assertThrows(PromptAlreadyActiveException.class, + () -> session.startPrompt( + PromptRequest.text("unsafe-reuse"), + PromptObserver.NOOP)); + } + } + + @Test + void updateForAnotherSessionCannotContaminatePromptText() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + String wrongSessionUpdate = textEvent(1, "wrong") + .replace("\"sessionId\":\"session-1\"", + "\"sessionId\":\"session-2\""); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + wrongSessionUpdate + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptOutcomeIndeterminateException failure = assertThrows( + PromptOutcomeIndeterminateException.class, + () -> session.promptText("go")); + assertEquals("", failure.getPartialText()); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + } + } + + @Test + void malformedTerminalCannotBecomeSuccess() { + AtomicInteger rawEvents = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + "id: 1\nevent: turn_complete\ndata: {\"id\":1,\"v\":1," + + "\"type\":\"turn_complete\",\"promptId\":" + + "\"prompt-1\",\"data\":{\"sessionId\":" + + "\"session-1\",\"promptId\":\"prompt-1\"}}\n\n")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onEvent(DaemonEvent event) { + rawEvents.incrementAndGet(); + } + }).completionFuture().join()); + PromptOutcomeIndeterminateException outcome = assertInstanceOf( + PromptOutcomeIndeterminateException.class, failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, outcome.getCause()); + assertEquals(0, rawEvents.get()); + } + } + + @Test + void duplicateTerminalFieldCannotBecomeSuccess() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + "id: 1\nevent: turn_complete\ndata: {\"id\":1,\"v\":1," + + "\"type\":\"turn_complete\",\"promptId\":" + + "\"prompt-1\",\"data\":{\"sessionId\":" + + "\"session-1\",\"promptId\":\"prompt-1\"," + + "\"stopReason\":\"end_turn\"," + + "\"stopReason\":\"other\"}}\n\n")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join()); + PromptOutcomeIndeterminateException outcome = assertInstanceOf( + PromptOutcomeIndeterminateException.class, failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, outcome.getCause()); + } + } + + @Test + void terminalForAnotherSessionCannotCompletePrompt() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEventForSession(1, "session-2"))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join()); + PromptOutcomeIndeterminateException outcome = assertInstanceOf( + PromptOutcomeIndeterminateException.class, failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, outcome.getCause()); + } + } + + @Test + void malformedPermissionRequestFailsClosed() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + String malformedPermission = permissionEvent(1) + .replace("\"toolCallId\":\"tool-1\"", + "\"toolCallId\":null"); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, malformedPermission + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onPermission(PermissionRequest request, + DaemonEvent event) { + fail("Malformed permission must not be dispatched"); + } + }).completionFuture().join()); + PromptOutcomeIndeterminateException outcome = assertInstanceOf( + PromptOutcomeIndeterminateException.class, failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, outcome.getCause()); + } + } + + @Test + void observerFailureDoesNotBecomeSuccess() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "hello") + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onText(String text, DaemonEvent event) { + throw new IllegalStateException("observer failed"); + } + }); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + } + } + + @Test + void slowTerminalObserverCannotOutrunObservationTimeout() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptRequest request = PromptRequest.text("go") + .withObservationTimeout(Duration.ofMillis(100)); + PromptCall call = session.startPrompt(request, new PromptObserver() { + @Override + public void onEvent(DaemonEvent event) { + sleep(200); + } + }); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + } + } + + @Test + void dispatchesThoughtToolUsagePermissionAndRawEventsInOrder() { + List calls = new ArrayList<>(); + AtomicReference permissionBody = new AtomicReference<>(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + updateEvent(1, "agent_thought_chunk", + "\"content\":{\"type\":\"text\",\"text\":\"think\"}") + + updateEvent(2, "tool_call", + "\"toolCallId\":\"tool-1\",\"title\":\"Read\"," + + "\"content\":[{\"type\":\"text\"," + + "\"text\":\"starting\"}]") + + updateEvent(3, "agent_message_chunk", + "\"content\":{\"type\":\"text\",\"text\":\"\"}," + + "\"_meta\":{\"usage\":{\"inputTokens\":3}}") + + permissionEvent(4) + terminalEvent(5))); + server.createContext("/session/session-1/permission/request-1", exchange -> { + permissionBody.set(new String(exchange.getRequestBody().readAllBytes(), + StandardCharsets.UTF_8)); + sendJson(exchange, 200, "{}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptObserver observer = new PromptObserver() { + @Override + public void onThought(String thought, DaemonEvent event) { + calls.add("thought:" + thought); + } + + @Override + public void onTool(java.util.Map update, + DaemonEvent event) { + calls.add("tool:" + update.get("toolCallId")); + } + + @Override + public void onUsage(java.util.Map usage, + DaemonEvent event) { + calls.add("usage:" + usage.get("inputTokens")); + } + + @Override + public void onPermission(PermissionRequest request, + DaemonEvent event) { + calls.add("permission:" + request.getRequestId()); + assertTrue(session.respondToPermission(request.getRequestId(), + PermissionResponse.selected("allow_once"))); + } + + @Override + public void onEvent(DaemonEvent event) { + calls.add("raw:" + event.getId()); + } + }; + PromptTerminal terminal = session.startPrompt(PromptRequest.text("go"), + observer).completionFuture().join(); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + } + assertEquals(List.of("thought:think", "raw:1", "tool:tool-1", "raw:2", + "usage:3", "raw:3", "permission:request-1", "raw:4", "raw:5"), + calls); + assertTrue(permissionBody.get().contains("\"optionId\":\"allow_once\"")); + } + + @Test + void dispatchesAcpUsageUpdateToTypedObserver() { + AtomicReference> observed = new AtomicReference<>(); + AtomicInteger usageCalls = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + updateEvent(1, "usage_update", "\"used\":12,\"size\":100," + + "\"_meta\":{\"usage\":{\"inputTokens\":3}}") + + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTerminal terminal = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onUsage(Map usage, + DaemonEvent event) { + usageCalls.incrementAndGet(); + observed.set(usage); + } + }).completionFuture().join(); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + } + assertEquals(12L, ((Number) observed.get().get("used")).longValue()); + assertEquals(100L, ((Number) observed.get().get("size")).longValue()); + assertEquals(1, usageCalls.get()); + } + + @Test + void ignoresOpaqueUsageMetadata() { + AtomicInteger rawEvents = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + updateEvent(1, "agent_message_chunk", + "\"content\":{\"type\":\"text\",\"text\":\"ok\"}," + + "\"_meta\":{\"usage\":\"opaque\"}") + + updateEvent(2, "agent_thought_chunk", + "\"content\":{\"type\":\"text\",\"text\":\"t\"}," + + "\"_meta\":\"opaque\"") + + terminalEvent(3))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTerminal terminal = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onUsage(Map usage, + DaemonEvent event) { + fail("Opaque usage metadata must be ignored"); + } + + @Override + public void onEvent(DaemonEvent event) { + rawEvents.incrementAndGet(); + } + }).completionFuture().join(); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + } + assertEquals(3, rawEvents.get()); + } + + @Test + void rejectsCompressedSseResponse() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", "text/event-stream"); + exchange.getResponseHeaders().set("Content-Encoding", "gzip"); + byte[] body = terminalEvent(1).getBytes(StandardCharsets.UTF_8); + exchange.sendResponseHeaders(200, body.length); + exchange.getResponseBody().write(body); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + } + } + + @Test + void rejectsLookalikeSseContentType() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", + "application/nottext/event-stream"); + byte[] body = terminalEvent(1).getBytes(StandardCharsets.UTF_8); + exchange.sendResponseHeaders(200, body.length); + exchange.getResponseBody().write(body); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + } + } + + @Test + void unexpectedSuccessfulSseStatusIsProtocolFailure() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptOutcomeIndeterminateException failure = assertThrows( + PromptOutcomeIndeterminateException.class, + () -> session.promptText("go")); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + } + } + + @Test + void rejectsConflictingPromptIdsInReliableTerminal() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, conflictingTerminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + } + } + + @Test + void rejectsIdlessReliableTerminal() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, "event: turn_complete\ndata: {\"v\":1," + + "\"type\":\"turn_complete\",\"promptId\":" + + "\"prompt-1\",\"data\":{\"promptId\":" + + "\"prompt-1\",\"stopReason\":\"end_turn\"}}\n\n")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP).completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + } + } + + @Test + void toleratesOpaqueDataOnUnknownEvent() { + List observed = new ArrayList<>(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + "id: 1\nevent: future_event\ndata: {\"id\":1,\"v\":1," + + "\"type\":\"future_event\",\"promptId\":" + + "\"prompt-1\",\"data\":{\"promptId\":42}}\n\n" + + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTerminal terminal = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onEvent(DaemonEvent event) { + observed.add(event.getType()); + } + }).completionFuture().join(); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + } + assertEquals(List.of("future_event", "turn_complete"), observed); + } + + @Test + void sessionFailureEventMakesOutcomeIndeterminate() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + "event: state_resync_required\ndata: {\"v\":1,\"type\":" + + "\"state_resync_required\",\"data\":{}}\n\n")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptOutcomeIndeterminateException failure = assertThrows( + PromptOutcomeIndeterminateException.class, + () -> session.promptText("go")); + assertTrue(failure.getMessage().contains("state_resync_required")); + } + } + + @Test + void dispatchesSubscriberControlFramesAsRawEvents() { + List observed = new ArrayList<>(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + syntheticEvent("slow_client_warning") + + syntheticEvent("replay_complete") + + terminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTerminal terminal = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onEvent(DaemonEvent event) { + observed.add(event.getType()); + } + }).completionFuture().join(); + assertEquals(PromptTerminal.Kind.COMPLETE, terminal.getKind()); + } + assertEquals(List.of("slow_client_warning", "replay_complete", + "turn_complete"), observed); + } + + @Test + void localObservationTimeoutDoesNotSendCancel() { + AtomicInteger cancels = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", "text/event-stream"); + exchange.sendResponseHeaders(200, 0); + exchange.getResponseBody().write(": heartbeat\n\n" + .getBytes(StandardCharsets.UTF_8)); + exchange.getResponseBody().flush(); + }); + server.createContext("/session/session-1/cancel", exchange -> { + cancels.incrementAndGet(); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptRequest request = PromptRequest.text("go") + .withObservationTimeout(Duration.ofMillis(150)); + long started = System.nanoTime(); + assertThrows(PromptOutcomeIndeterminateException.class, + () -> session.promptText(request)); + assertTrue(Duration.ofNanos(System.nanoTime() - started).toMillis() < 900); + } + assertEquals(0, cancels.get()); + } + + @Test + void localObservationTimeoutAlsoBoundsSseHandshake() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + try { + Thread.sleep(2000); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } finally { + exchange.close(); + } + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptRequest request = PromptRequest.text("go") + .withObservationTimeout(Duration.ofMillis(150)); + long started = System.nanoTime(); + assertThrows(PromptOutcomeIndeterminateException.class, + () -> session.promptText(request)); + assertTrue(Duration.ofNanos(System.nanoTime() - started).toMillis() < 900); + } + } + + @Test + void requestTimeoutBoundsStalledAdmissionResponseBody() { + AtomicInteger prompts = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + prompts.incrementAndGet(); + exchange.getResponseHeaders().set("Content-Type", "application/json"); + exchange.sendResponseHeaders(202, 100); + exchange.getResponseBody().write('{'); + exchange.getResponseBody().flush(); + sleep(2000); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .requestTimeout(Duration.ofMillis(150)).build(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + long started = System.nanoTime(); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.acceptanceFuture().join()); + assertInstanceOf(PromptAdmissionUnknownException.class, + failure.getCause()); + assertThrows(PromptAlreadyActiveException.class, + () -> session.startPrompt( + PromptRequest.text("unsafe-reuse"), + PromptObserver.NOOP)); + assertTrue(Duration.ofNanos(System.nanoTime() - started).toMillis() < 900); + } + assertEquals(1, prompts.get()); + } + + @Test + void requestTimeoutBoundsStalledSseErrorBody() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.sendResponseHeaders(503, 100); + exchange.getResponseBody().write('{'); + exchange.getResponseBody().flush(); + sleep(2000); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .requestTimeout(Duration.ofMillis(150)) + .maximumReconnectAttempts(0).build(); + DaemonSessionClient session = daemon.createSession()) { + long started = System.nanoTime(); + assertThrows(PromptOutcomeIndeterminateException.class, + () -> session.promptText("go")); + assertTrue(Duration.ofNanos(System.nanoTime() - started).toMillis() < 900); + } + } + + @Test + void slowSseLineBytesKeepIdleWatchdogAlive() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", "text/event-stream"); + exchange.sendResponseHeaders(200, 0); + byte[] bytes = terminalEvent(1).getBytes(StandardCharsets.UTF_8); + for (int offset = 0; offset < bytes.length; offset += 20) { + int count = Math.min(20, bytes.length - offset); + exchange.getResponseBody().write(bytes, offset, count); + exchange.getResponseBody().flush(); + sleep(50); + } + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .sseIdleTimeout(Duration.ofMillis(150)).build(); + DaemonSessionClient session = daemon.createSession()) { + assertEquals(PromptTerminal.Kind.COMPLETE, + session.promptText("go").getTerminal().getKind()); + } + } + + @Test + void turnErrorIsReliableButPromptTextThrowsTurnFailure() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + textEvent(1, "partial") + errorTerminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTurnException failure = assertThrows(PromptTurnException.class, + () -> session.promptText("go")); + assertEquals(PromptTerminal.Kind.ERROR, failure.getTerminal().getKind()); + assertEquals("partial", failure.getPartialText()); + } + } + + @Test + void deadlineTerminalIsReliableAndSessionRemainsReusable() { + AtomicInteger prompts = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + int prompt = prompts.incrementAndGet(); + sendJson(exchange, 202, "{\"promptId\":\"prompt-" + prompt + + "\",\"lastEventId\":" + (prompt - 1) + "}"); + }); + server.createContext("/session/session-1/events", exchange -> { + String cursor = exchange.getRequestHeaders().getFirst("Last-Event-ID"); + if ("0".equals(cursor)) { + sendSse(exchange, errorTerminalEvent(1, "prompt-1", + "prompt_deadline_exceeded", + "prompt exceeded the 50ms deadline")); + } else { + sendSse(exchange, terminalEventForPrompt(2, "prompt-2")); + } + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTurnException failure = assertThrows(PromptTurnException.class, + () -> session.promptText(PromptRequest.builder() + .addText("slow") + .deadline(Duration.ofMillis(50)) + .build())); + assertEquals("prompt_deadline_exceeded", + failure.getTerminal().getCode()); + assertEquals("prompt-1", failure.getTerminal().getPromptId()); + + PromptTextResult followUp = session.promptText("continue"); + assertEquals(PromptTerminal.Kind.COMPLETE, + followUp.getTerminal().getKind()); + assertEquals("prompt-2", followUp.getTerminal().getPromptId()); + } + assertEquals(2, prompts.get()); + } + + @Test + void teardownTerminalWinsOverFollowingSessionFailure() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> sendSse(exchange, + errorTerminalEvent(1, "prompt-1", "session_closed", + "session closed before the prompt completed") + + sessionClosedEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTurnException failure = assertThrows(PromptTurnException.class, + () -> session.promptText("go")); + assertEquals("session_closed", failure.getTerminal().getCode()); + assertEquals(PromptTerminal.Kind.ERROR, + failure.getTerminal().getKind()); + } + } + + @Test + void cancelledTurnCompleteIsReliableAndExposesStopReason() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1, "prompt-1", "cancelled"))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptTextResult result = session.promptText("go"); + assertEquals("", result.getText()); + assertEquals(PromptTerminal.Kind.COMPLETE, + result.getTerminal().getKind()); + assertEquals("cancelled", result.getTerminal().getStopReason()); + } + } + + @Test + void enforcesTextCollectionLimitBeforeReliableTerminal() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "hello") + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptContentLimitException failure = assertThrows( + PromptContentLimitException.class, + () -> session.promptText(PromptRequest.text("go"), 4)); + assertEquals(4, failure.getMaximumBytes()); + } + } + + @Test + void countsUtf8BytesAcrossSplitSurrogatePairs() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "\\uD83D") + + textEvent(2, "\\uDE00") + terminalEvent(3))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptContentLimitException failure = assertThrows( + PromptContentLimitException.class, + () -> session.promptText(PromptRequest.text("go"), 3)); + assertEquals(3, failure.getMaximumBytes()); + assertEquals("", failure.getPartialText()); + } + } + + @Test + void keepsPartialTextBoundedWhenSplitSurrogateIsUnpaired() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "a\\uD83D") + + textEvent(2, "b") + terminalEvent(3))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptContentLimitException failure = assertThrows( + PromptContentLimitException.class, + () -> session.promptText(PromptRequest.text("go"), 1)); + assertEquals("a", failure.getPartialText()); + assertEquals(1, failure.getPartialText() + .getBytes(StandardCharsets.UTF_8).length); + } + } + + @Test + void preservesIndeterminateOutcomeWhenFinalizingBoundedPartialText() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "a\\uD83D") + + terminalEvent(3))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptOutcomeIndeterminateException failure = assertThrows( + PromptOutcomeIndeterminateException.class, + () -> session.promptText(PromptRequest.text("go"), 1)); + assertEquals("a", failure.getPartialText()); + assertEquals(1, failure.getPartialText() + .getBytes(StandardCharsets.UTF_8).length); + assertInstanceOf(DaemonProtocolException.class, + failure.getCause().getCause()); + assertThrows(PromptAlreadyActiveException.class, + () -> session.startPrompt( + PromptRequest.text("unsafe-reuse"), + PromptObserver.NOOP)); + } + } + + @Test + void rejectsSecondLocalPromptUntilFirstSettles() { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", "text/event-stream"); + exchange.sendResponseHeaders(200, 0); + exchange.getResponseBody().write(": keep-alive\n\n" + .getBytes(StandardCharsets.UTF_8)); + exchange.getResponseBody().flush(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + session.startPrompt(PromptRequest.text("first"), PromptObserver.NOOP); + assertThrows(PromptAlreadyActiveException.class, + () -> session.startPrompt(PromptRequest.text("second"), + PromptObserver.NOOP)); + } + } + + @Test + void rejectsClientWidePromptCapacityBeforeMutation() throws Exception { + server.removeContext("/session"); + AtomicInteger created = new AtomicInteger(); + server.createContext("/session", exchange -> { + int number = created.incrementAndGet(); + sendJson(exchange, 200, sessionJson("session-" + number, + "client-" + number)); + }); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + CountDownLatch streamOpened = new CountDownLatch(1); + CountDownLatch releaseStream = new CountDownLatch(1); + server.createContext("/session/session-1/events", exchange -> { + streamOpened.countDown(); + await(releaseStream); + sendSse(exchange, terminalEvent(1)); + }); + AtomicInteger secondPromptRequests = new AtomicInteger(); + server.createContext("/session/session-2/prompt", exchange -> { + secondPromptRequests.incrementAndGet(); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-2\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/detach", noContent()); + server.createContext("/session/session-2/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1).build(); + DaemonSessionClient first = daemon.createSession(); + DaemonSessionClient second = daemon.createSession()) { + PromptCall running = first.startPrompt(PromptRequest.text("first"), + PromptObserver.NOOP); + assertEquals("prompt-1", + running.acceptanceFuture().join().getPromptId()); + assertTrue(streamOpened.await(1, TimeUnit.SECONDS)); + + PromptCall rejected = second.startPrompt(PromptRequest.text("second"), + PromptObserver.NOOP); + CompletionException admissionFailure = assertThrows( + CompletionException.class, + () -> rejected.acceptanceFuture().join()); + CompletionException completionFailure = assertThrows( + CompletionException.class, + () -> rejected.completionFuture().join()); + assertInstanceOf(DaemonClientCapacityException.class, + admissionFailure.getCause()); + assertInstanceOf(DaemonClientCapacityException.class, + completionFailure.getCause()); + assertEquals(0, secondPromptRequests.get()); + + releaseStream.countDown(); + assertEquals(PromptTerminal.Kind.COMPLETE, + running.completionFuture().join().getKind()); + } finally { + releaseStream.countDown(); + } + } + + @Test + void closeAttemptsDetachOnlyOnceAndDestroyUsesDelete() { + AtomicInteger detaches = new AtomicInteger(); + AtomicInteger deletes = new AtomicInteger(); + AtomicReference detachClientId = new AtomicReference<>(); + server.createContext("/session/session-1/detach", exchange -> { + detaches.incrementAndGet(); + detachClientId.set(exchange.getRequestHeaders() + .getFirst("X-Qwen-Client-Id")); + exchange.close(); + }); + server.createContext("/session/session-1", exchange -> { + if ("DELETE".equals(exchange.getRequestMethod())) { + deletes.incrementAndGet(); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + return; + } + sendJson(exchange, 404, "{}"); + }); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + assertThrows(DetachOutcomeUnknownException.class, session::close); + session.close(); + session.destroySession(); + } + assertEquals(1, detaches.get()); + assertEquals(1, deletes.get()); + assertEquals("client-1", detachClientId.get()); + } + + @Test + void clientClosePreservesEverySessionDetachFailure() { + AtomicInteger detaches = new AtomicInteger(); + server.createContext("/session/session-1/detach", exchange -> { + detaches.incrementAndGet(); + exchange.close(); + }); + + DaemonClient daemon = newClient(); + daemon.createSession(); + daemon.createSession(); + DetachOutcomeUnknownException failure = assertThrows( + DetachOutcomeUnknownException.class, daemon::close); + assertEquals(1, failure.getSuppressed().length); + assertEquals(2, detaches.get()); + } + + @Test + void destroyAfterDetachOmitsRetiredClientIdAndAcceptsNotFound() { + AtomicReference deleteClientId = new AtomicReference<>(); + server.createContext("/session/session-1/detach", noContent()); + server.createContext("/session/session-1", exchange -> { + deleteClientId.set(exchange.getRequestHeaders() + .getFirst("X-Qwen-Client-Id")); + sendJson(exchange, 404, + "{\"error\":\"not found\",\"sessionId\":\"session-1\"}"); + }); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + session.detach(); + session.destroySession(); + } + assertEquals(null, deleteClientId.get()); + } + + @Test + void destroyDoesNotTreatGenericNotFoundAsAlreadyDeleted() { + server.createContext("/session/session-1", exchange -> + sendJson(exchange, 404, "{\"error\":\"route not found\"}")); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + DaemonHttpException failure = assertThrows( + DaemonHttpException.class, session::destroySession); + assertEquals(404, failure.getStatusCode()); + } + } + + @Test + void malformedSuccessfulMutationResponseIsOutcomeUnknown() { + server.createContext("/session/session-1/permission/request-1", exchange -> { + byte[] bytes = {(byte) 0xC3, (byte) 0x28}; + exchange.sendResponseHeaders(200, bytes.length); + exchange.getResponseBody().write(bytes); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + MutationOutcomeUnknownException failure = assertThrows( + MutationOutcomeUnknownException.class, + () -> session.respondToPermission("request-1", + PermissionResponse.cancelled())); + assertInstanceOf(DaemonProtocolException.class, failure.getCause()); + } + } + + @Test + void permissionResponseReportsAlreadyResolvedWithoutStoppingObservation() { + server.createContext("/session/session-1/permission/request-1", exchange -> + sendJson(exchange, 404, + "{\"error\":\"already resolved\"," + + "\"sessionId\":\"session-1\"," + + "\"requestId\":\"request-1\"}")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + assertTrue(!session.respondToPermission("request-1", + PermissionResponse.cancelled())); + } + } + + @Test + void permissionResponseRejectsGenericNotFound() { + server.createContext("/session/session-1/permission/request-1", exchange -> + sendJson(exchange, 404, "{\"error\":\"route not found\"}")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + DaemonHttpException failure = assertThrows(DaemonHttpException.class, + () -> session.respondToPermission("request-1", + PermissionResponse.cancelled())); + assertEquals(404, failure.getStatusCode()); + } + } + + @Test + void unexpectedSuccessfulMutationStatusIsOutcomeUnknown() { + server.createContext("/session/session-1/permission/request-1", exchange -> + sendJson(exchange, 202, "{}")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + MutationOutcomeUnknownException failure = assertThrows( + MutationOutcomeUnknownException.class, + () -> session.respondToPermission("request-1", + PermissionResponse.cancelled())); + assertInstanceOf(DaemonProtocolException.class, failure.getCause()); + } + } + + @Test + void ambiguousHttpMutationStatusesAreOutcomeUnknown() { + AtomicInteger requests = new AtomicInteger(); + server.createContext("/session/session-1/permission/request-1", exchange -> { + requests.incrementAndGet(); + sendJson(exchange, 503, "{\"error\":\"unavailable\"}"); + }); + server.createContext("/session/session-1/cancel", exchange -> { + requests.incrementAndGet(); + sendJson(exchange, 408, "{\"error\":\"timeout\"}"); + }); + server.createContext("/session/session-1/heartbeat", exchange -> { + requests.incrementAndGet(); + sendJson(exchange, 502, "{\"error\":\"bad gateway\"}"); + }); + server.createContext("/session/session-1", exchange -> { + requests.incrementAndGet(); + sendJson(exchange, 504, "{\"error\":\"gateway timeout\"}"); + }); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + assertAmbiguousHttpMutation(() -> session.respondToPermission( + "request-1", PermissionResponse.cancelled()), 503); + assertAmbiguousHttpMutation(session::cancelActivePrompt, 408); + assertAmbiguousHttpMutation(session::heartbeat, 502); + assertAmbiguousHttpMutation(session::destroySession, 504); + } + assertEquals(4, requests.get()); + } + + @Test + void ambiguousDetachHttpStatusIsSpecializedAndNotRetried() { + AtomicInteger detaches = new AtomicInteger(); + server.createContext("/session/session-1/detach", exchange -> { + detaches.incrementAndGet(); + sendJson(exchange, 503, "{\"error\":\"unavailable\"}"); + }); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + DetachOutcomeUnknownException failure = assertThrows( + DetachOutcomeUnknownException.class, session::close); + DaemonHttpException cause = assertInstanceOf(DaemonHttpException.class, + failure.getCause()); + assertEquals(503, cause.getStatusCode()); + session.close(); + } + assertEquals(1, detaches.get()); + } + + @Test + void definitiveHttpErrorToleratesMalformedErrorText() { + server.createContext("/session/session-1/permission/request-1", exchange -> { + byte[] bytes = {(byte) 0xC3, (byte) 0x28}; + exchange.sendResponseHeaders(400, bytes.length); + exchange.getResponseBody().write(bytes); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + DaemonHttpException failure = assertThrows(DaemonHttpException.class, + () -> session.respondToPermission("request-1", + PermissionResponse.cancelled())); + assertEquals(400, failure.getStatusCode()); + } + } + + @Test + void unexpectedSuccessfulCreateStatusIsOutcomeUnknown() { + server.removeContext("/session"); + server.createContext("/session", exchange -> + sendJson(exchange, 201, sessionJson())); + + try (DaemonClient daemon = newClient()) { + SessionCreationOutcomeUnknownException failure = assertThrows( + SessionCreationOutcomeUnknownException.class, + daemon::createSession); + assertInstanceOf(DaemonProtocolException.class, failure.getCause()); + } + } + + @Test + void requestTimeoutHttpCreateFailureIsOutcomeUnknown() { + server.removeContext("/session"); + AtomicInteger creates = new AtomicInteger(); + server.createContext("/session", exchange -> { + creates.incrementAndGet(); + sendJson(exchange, 408, "{\"error\":\"request timeout\"}"); + }); + + try (DaemonClient daemon = newClient()) { + SessionCreationOutcomeUnknownException failure = assertThrows( + SessionCreationOutcomeUnknownException.class, + daemon::createSession); + DaemonHttpException cause = assertInstanceOf(DaemonHttpException.class, + failure.getCause()); + assertEquals(408, cause.getStatusCode()); + } + assertEquals(1, creates.get()); + } + + @Test + void malformedCreatedClientIdIsOutcomeUnknown() { + server.removeContext("/session"); + server.createContext("/session", exchange -> sendJson(exchange, 200, + sessionJson("session-1", "invalid client id"))); + + try (DaemonClient daemon = newClient()) { + SessionCreationOutcomeUnknownException failure = assertThrows( + SessionCreationOutcomeUnknownException.class, + daemon::createSession); + assertInstanceOf(DaemonProtocolException.class, failure.getCause()); + } + } + + @Test + void closeWaitsForInFlightAdmissionBeforeDetaching() throws Exception { + CountDownLatch admissionStarted = new CountDownLatch(1); + CountDownLatch releaseAdmission = new CountDownLatch(1); + AtomicInteger detaches = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + admissionStarted.countDown(); + await(releaseAdmission); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1))); + server.createContext("/session/session-1/detach", exchange -> { + detaches.incrementAndGet(); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + assertTrue(admissionStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture close = CompletableFuture.runAsync(session::close); + Thread.sleep(100); + assertTrue(!close.isDone()); + assertEquals(0, detaches.get()); + releaseAdmission.countDown(); + close.get(1, TimeUnit.SECONDS); + assertEquals("prompt-1", + call.acceptanceFuture().join().getPromptId()); + } + assertEquals(1, detaches.get()); + } + + @Test + void acceptanceContinuationDoesNotHoldSessionLifecycleLock() throws Exception { + CountDownLatch admissionStarted = new CountDownLatch(1); + CountDownLatch releaseAdmission = new CountDownLatch(1); + CountDownLatch continuationEntered = new CountDownLatch(1); + CountDownLatch releaseContinuation = new CountDownLatch(1); + CountDownLatch eventsOpened = new CountDownLatch(1); + CountDownLatch releaseEvents = new CountDownLatch(1); + server.createContext("/session/session-1/prompt", exchange -> { + admissionStarted.countDown(); + await(releaseAdmission); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", "text/event-stream"); + exchange.sendResponseHeaders(200, 0); + exchange.getResponseBody().write( + "retry: 0\n\n".getBytes(StandardCharsets.UTF_8)); + exchange.getResponseBody().flush(); + eventsOpened.countDown(); + await(releaseEvents); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + assertTrue(admissionStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture continuation = call.acceptanceFuture() + .thenRun(() -> { + continuationEntered.countDown(); + await(releaseContinuation); + }); + releaseAdmission.countDown(); + assertTrue(continuationEntered.await(1, TimeUnit.SECONDS)); + assertTrue(eventsOpened.await(1, TimeUnit.SECONDS)); + CompletableFuture close = CompletableFuture.runAsync(session::close); + try { + close.get(1, TimeUnit.SECONDS); + } finally { + releaseContinuation.countDown(); + releaseEvents.countDown(); + } + continuation.get(1, TimeUnit.SECONDS); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + } finally { + releaseAdmission.countDown(); + releaseContinuation.countDown(); + releaseEvents.countDown(); + } + } + + @Test + void acceptanceContinuationWaitingForTerminalCannotBlockObservation() + throws Exception { + CountDownLatch admissionStarted = new CountDownLatch(1); + CountDownLatch releaseAdmission = new CountDownLatch(1); + server.createContext("/session/session-1/prompt", exchange -> { + admissionStarted.countDown(); + await(releaseAdmission); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + assertTrue(admissionStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture continuation = call.acceptanceFuture() + .thenRun(() -> call.completionFuture().join()); + releaseAdmission.countDown(); + assertEquals(PromptTerminal.Kind.COMPLETE, + call.completionFuture().get(1, TimeUnit.SECONDS).getKind()); + continuation.get(1, TimeUnit.SECONDS); + } finally { + releaseAdmission.countDown(); + } + } + + @Test + void failedAdmissionContinuationWaitingForTerminalCannotBlockFailure() + throws Exception { + CountDownLatch admissionStarted = new CountDownLatch(1); + CountDownLatch releaseAdmission = new CountDownLatch(1); + server.createContext("/session/session-1/prompt", exchange -> { + admissionStarted.countDown(); + await(releaseAdmission); + sendJson(exchange, 400, "{\"error\":\"rejected\"}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + assertTrue(admissionStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture continuation = call.acceptanceFuture() + .handle((ignored, failure) -> { + assertTrue(failure != null); + assertThrows( + CompletionException.class, + () -> call.completionFuture().join()); + return null; + }); + releaseAdmission.countDown(); + CompletionException terminalFailure = assertThrows( + CompletionException.class, + () -> call.completionFuture() + .orTimeout(1, TimeUnit.SECONDS).join()); + assertInstanceOf(DaemonHttpException.class, + terminalFailure.getCause()); + continuation.get(1, TimeUnit.SECONDS); + } finally { + releaseAdmission.countDown(); + } + } + + @Test + void terminalContinuationCanStartNextPromptAtClientCapacity() + throws Exception { + AtomicInteger prompts = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + int prompt = prompts.incrementAndGet(); + sendJson(exchange, 202, "{\"promptId\":\"prompt-" + prompt + + "\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEventForPrompt(1, + "prompt-" + prompts.get()))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall first = session.startPrompt(PromptRequest.text("one"), + PromptObserver.NOOP); + CompletableFuture second = first.completionFuture() + .thenCompose(ignored -> session.startPrompt( + PromptRequest.text("two"), PromptObserver.NOOP) + .completionFuture()); + assertEquals(PromptTerminal.Kind.COMPLETE, + second.get(1, TimeUnit.SECONDS).getKind()); + assertEquals(2, prompts.get()); + } + } + + @Test + void blockedTerminalContinuationsApplyBoundedPublicationBackpressure() + throws Exception { + AtomicInteger prompts = new AtomicInteger(); + AtomicInteger sessions = new AtomicInteger(); + AtomicInteger rejectedPromptRequests = new AtomicInteger(); + CountDownLatch releaseContinuations = new CountDownLatch(1); + CountDownLatch finalTerminalObserved = new CountDownLatch(1); + CountDownLatch releaseFinalObserver = new CountDownLatch(1); + List> continuations = new ArrayList<>(); + server.removeContext("/session"); + server.createContext("/session", exchange -> { + int session = sessions.incrementAndGet(); + sendJson(exchange, 200, sessionJson("session-" + session, + "client-" + session)); + }); + server.createContext("/session/session-1/prompt", exchange -> { + int prompt = prompts.incrementAndGet(); + sendJson(exchange, 202, "{\"promptId\":\"prompt-" + prompt + + "\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEventForPrompt(1, + "prompt-" + prompts.get()))); + server.createContext("/session/session-2/prompt", exchange -> { + rejectedPromptRequests.incrementAndGet(); + sendJson(exchange, 202, + "{\"promptId\":\"unexpected\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/detach", noContent()); + server.createContext("/session/session-2/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build(); + DaemonSessionClient session = daemon.createSession(); + DaemonSessionClient secondSession = daemon.createSession()) { + try { + for (int index = 0; index < 2; index++) { + CountDownLatch continuationEntered = new CountDownLatch(1); + PromptCall call = session.startPrompt( + PromptRequest.text("blocking-" + index), + PromptObserver.NOOP); + continuations.add(call.completionFuture().thenRun(() -> { + continuationEntered.countDown(); + await(releaseContinuations); + })); + assertTrue(continuationEntered.await(1, TimeUnit.SECONDS)); + } + PromptCall finalCall = session.startPrompt( + PromptRequest.text("final"), new PromptObserver() { + @Override + public void onEvent(DaemonEvent event) { + if ("turn_complete".equals(event.getType())) { + finalTerminalObserved.countDown(); + await(releaseFinalObserver); + } + } + }); + CompletableFuture finalCompletion = + finalCall.completionFuture(); + assertTrue(finalTerminalObserved.await(1, TimeUnit.SECONDS)); + PromptCall capacityRejected = secondSession.startPrompt( + PromptRequest.text("capacity-rejected"), + PromptObserver.NOOP); + assertThrows(DaemonClientCapacityException.class, + () -> secondSession.startPrompt( + PromptRequest.text("publication-rejected"), + PromptObserver.NOOP)); + assertEquals(0, rejectedPromptRequests.get()); + assertTrue(!finalCompletion.isDone()); + assertTrue(!capacityRejected.completionFuture().isDone()); + releaseFinalObserver.countDown(); + releaseContinuations.countDown(); + assertEquals(PromptTerminal.Kind.COMPLETE, + finalCompletion.get(1, TimeUnit.SECONDS).getKind()); + CompletionException rejection = assertThrows( + CompletionException.class, + () -> capacityRejected.completionFuture().join()); + assertInstanceOf(DaemonClientCapacityException.class, + rejection.getCause()); + } finally { + releaseFinalObserver.countDown(); + releaseContinuations.countDown(); + } + for (CompletableFuture continuation : continuations) { + continuation.get(1, TimeUnit.SECONDS); + } + } finally { + releaseFinalObserver.countDown(); + releaseContinuations.countDown(); + } + assertEquals(3, prompts.get()); + } + + @Test + void completionContinuationCanCloseClientWithoutWaitingOnItself() + throws Exception { + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + DaemonClient daemon = newClient(); + try { + DaemonSessionClient session = daemon.createSession(); + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + call.completionFuture().thenRun(daemon::close) + .get(1, TimeUnit.SECONDS); + } finally { + daemon.close(); + } + } + + @Test + void clientCloseRacingAdmissionKeepsFuturePublicationAsynchronous() + throws Exception { + CountDownLatch admissionStarted = new CountDownLatch(1); + CountDownLatch releaseAdmission = new CountDownLatch(1); + server.createContext("/session/session-1/prompt", exchange -> { + admissionStarted.countDown(); + await(releaseAdmission); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build(); + try { + DaemonSessionClient session = daemon.createSession(); + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + assertTrue(admissionStarted.await(1, TimeUnit.SECONDS)); + CompletableFuture continuation = call.acceptanceFuture() + .handle((ignored, failure) -> { + try { + call.completionFuture().join(); + } catch (CompletionException expected) { + assertTrue(expected.getCause() != null); + } + return null; + }); + CompletableFuture closing = + CompletableFuture.runAsync(daemon::close); + releaseAdmission.countDown(); + closing.get(1, TimeUnit.SECONDS); + continuation.get(1, TimeUnit.SECONDS); + assertTrue(call.completionFuture().isDone()); + } finally { + releaseAdmission.countDown(); + daemon.close(); + } + } + + @Test + void clientCloseRejectsPromptFromSessionNotYetSwept() throws Exception { + AtomicInteger created = new AtomicInteger(); + AtomicInteger promptRequests = new AtomicInteger(); + AtomicInteger mutationRequests = new AtomicInteger(); + AtomicReference detachingSession = new AtomicReference<>(); + CountDownLatch detachStarted = new CountDownLatch(1); + CountDownLatch releaseDetach = new CountDownLatch(1); + server.removeContext("/session"); + server.createContext("/session", exchange -> { + int session = created.incrementAndGet(); + sendJson(exchange, 200, sessionJson("session-" + session, + "client-" + session)); + }); + for (int session = 1; session <= 2; session++) { + String sessionId = "session-" + session; + String clientId = "client-" + session; + server.createContext("/session/" + sessionId + "/prompt", exchange -> { + promptRequests.incrementAndGet(); + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}"); + }); + server.createContext("/session/" + sessionId + "/events", exchange -> + sendSse(exchange, terminalEventForSession(1, sessionId))); + server.createContext("/session/" + sessionId + "/cancel", exchange -> { + mutationRequests.incrementAndGet(); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + server.createContext("/session/" + sessionId + "/heartbeat", exchange -> { + mutationRequests.incrementAndGet(); + sendJson(exchange, 200, "{\"sessionId\":\"" + sessionId + + "\",\"clientId\":\"" + clientId + + "\",\"lastSeenAt\":1}"); + }); + server.createContext("/session/" + sessionId + + "/permission/request-1", exchange -> { + mutationRequests.incrementAndGet(); + sendJson(exchange, 200, "{\"accepted\":true}"); + }); + server.createContext("/session/" + sessionId + "/detach", exchange -> { + detachingSession.compareAndSet(null, sessionId); + detachStarted.countDown(); + await(releaseDetach); + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }); + } + + DaemonClient daemon = newClient(); + try { + DaemonSessionClient first = daemon.createSession(); + DaemonSessionClient second = daemon.createSession(); + CompletableFuture closing = + CompletableFuture.runAsync(daemon::close); + assertTrue(detachStarted.await(1, TimeUnit.SECONDS)); + DaemonSessionClient unswept = "session-1".equals( + detachingSession.get()) ? second : first; + PromptCall rejected = unswept.startPrompt( + PromptRequest.text("too-late"), PromptObserver.NOOP); + assertThrows(CompletionException.class, + () -> rejected.acceptanceFuture().join()); + assertThrows(CompletionException.class, + () -> rejected.completionFuture().join()); + assertEquals(0, promptRequests.get()); + assertThrows(IllegalStateException.class, unswept::cancelActivePrompt); + assertThrows(IllegalStateException.class, unswept::heartbeat); + assertThrows(IllegalStateException.class, + () -> unswept.respondToPermission("request-1", + PermissionResponse.cancelled())); + assertEquals(0, mutationRequests.get()); + releaseDetach.countDown(); + closing.get(1, TimeUnit.SECONDS); + } finally { + releaseDetach.countDown(); + daemon.close(); + } + } + + @Test + void stoppedPromptCompletesOnlyAfterObserverExits() throws Exception { + CountDownLatch observerEntered = new CountDownLatch(1); + CountDownLatch releaseObserver = new CountDownLatch(1); + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, textEvent(1, "partial") + terminalEvent(2))); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient()) { + DaemonSessionClient session = daemon.createSession(); + PromptCall call = session.startPrompt(PromptRequest.text("go"), + new PromptObserver() { + @Override + public void onText(String text, DaemonEvent event) { + observerEntered.countDown(); + awaitUninterruptibly(releaseObserver); + } + }); + assertTrue(observerEntered.await(1, TimeUnit.SECONDS)); + session.close(); + assertTrue(!call.completionFuture().isDone()); + releaseObserver.countDown(); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + } + } + + @Test + void automaticHeartbeatRequiresAdvertisedCapability() throws Exception { + AtomicInteger heartbeats = new AtomicInteger(); + server.removeContext("/capabilities"); + server.createContext("/capabilities", exchange -> sendJson(exchange, 200, + "{\"v\":1,\"mode\":\"http-bridge\",\"features\":[" + + "\"session_scope_override\"]," + + "\"transports\":[\"rest\"]}")); + server.createContext("/session/session-1/heartbeat", exchange -> { + heartbeats.incrementAndGet(); + sendJson(exchange, 200, + "{\"sessionId\":\"session-1\",\"lastSeenAt\":1}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .heartbeatInterval(Duration.ofMillis(20)).build(); + DaemonSessionClient session = daemon.createSession()) { + Thread.sleep(100); + assertEquals(0, heartbeats.get()); + } + } + + @Test + void automaticHeartbeatStopsWithSession() throws Exception { + AtomicInteger heartbeats = new AtomicInteger(); + server.createContext("/session/session-1/heartbeat", exchange -> { + int count = heartbeats.incrementAndGet(); + sendJson(exchange, 200, "{\"sessionId\":\"session-1\"," + + "\"clientId\":\"client-1\",\"lastSeenAt\":" + count + "}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .heartbeatInterval(Duration.ofMillis(30)).build()) { + DaemonSessionClient session = daemon.createSession(); + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(1); + while (heartbeats.get() == 0 && System.nanoTime() < deadline) { + Thread.sleep(10); + } + assertTrue(heartbeats.get() > 0); + HeartbeatResult result = session.heartbeat(); + assertEquals("session-1", result.getSessionId()); + session.close(); + int afterClose = heartbeats.get(); + Thread.sleep(100); + assertEquals(afterClose, heartbeats.get()); + } + } + + @Test + void heartbeatRejectsMismatchedClientIdentity() { + server.createContext("/session/session-1/heartbeat", exchange -> + sendJson(exchange, 200, "{\"sessionId\":\"session-1\"," + + "\"clientId\":\"another-client\",\"lastSeenAt\":1}")); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + MutationOutcomeUnknownException failure = assertThrows( + MutationOutcomeUnknownException.class, session::heartbeat); + assertInstanceOf(DaemonProtocolException.class, failure.getCause()); + } + } + + @Test + void queuedHeartbeatsAreFairAndDoNotDelayClose() throws Exception { + server.removeContext("/session"); + AtomicInteger created = new AtomicInteger(); + server.createContext("/session", exchange -> { + int number = created.incrementAndGet(); + sendJson(exchange, 200, sessionJson("session-" + number, + "client-" + number)); + }); + CountDownLatch fourRunning = new CountDownLatch(4); + CountDownLatch releaseHeartbeats = new CountDownLatch(1); + AtomicInteger heartbeats = new AtomicInteger(); + for (int number = 1; number <= 6; number++) { + String sessionId = "session-" + number; + String clientId = "client-" + number; + server.createContext("/session/" + sessionId + "/heartbeat", + exchange -> { + int count = heartbeats.incrementAndGet(); + if (count <= 4) { + fourRunning.countDown(); + await(releaseHeartbeats); + } + sendJson(exchange, 200, "{\"sessionId\":\"" + + sessionId + "\",\"clientId\":\"" + + clientId + "\",\"lastSeenAt\":1}"); + }); + server.createContext("/session/" + sessionId + "/detach", + noContent()); + } + + try (DaemonClient daemon = clientBuilder() + .heartbeatInterval(Duration.ofMillis(20)).build()) { + List sessions = new ArrayList<>(); + try { + for (int number = 0; number < 6; number++) { + sessions.add(daemon.createSession()); + } + assertTrue(fourRunning.await(1, TimeUnit.SECONDS)); + long started = System.nanoTime(); + sessions.get(4).close(); + assertTrue(Duration.ofNanos(System.nanoTime() - started) + .toMillis() < 500); + releaseHeartbeats.countDown(); + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(1); + while (heartbeats.get() < 5 && System.nanoTime() < deadline) { + Thread.sleep(10); + } + assertTrue(heartbeats.get() >= 5); + } finally { + releaseHeartbeats.countDown(); + for (DaemonSessionClient session : sessions) { + session.close(); + } + } + } + } + + @Test + void blockedHeartbeatDoesNotDelayPromptObservationTimeout() throws Exception { + server.removeContext("/session"); + AtomicInteger created = new AtomicInteger(); + server.createContext("/session", exchange -> { + int number = created.incrementAndGet(); + sendJson(exchange, 200, sessionJson("session-" + number, + "client-" + number)); + }); + CountDownLatch heartbeatEntered = new CountDownLatch(1); + CountDownLatch releaseHeartbeat = new CountDownLatch(1); + CountDownLatch streamOpened = new CountDownLatch(1); + CountDownLatch releaseStream = new CountDownLatch(1); + server.createContext("/session/session-1/heartbeat", exchange -> { + heartbeatEntered.countDown(); + await(releaseHeartbeat); + sendJson(exchange, 200, "{\"sessionId\":\"session-1\"," + + "\"clientId\":\"client-1\",\"lastSeenAt\":1}"); + }); + server.createContext("/session/session-2/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-2/events", exchange -> { + exchange.getResponseHeaders().set("Content-Type", + "text/event-stream"); + exchange.sendResponseHeaders(200, 0); + exchange.getResponseBody().write(": heartbeat\n\n" + .getBytes(StandardCharsets.UTF_8)); + exchange.getResponseBody().flush(); + streamOpened.countDown(); + await(releaseStream); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + server.createContext("/session/session-2/detach", noContent()); + + try (DaemonClient daemon = clientBuilder() + .heartbeatInterval(Duration.ofMillis(50)) + .maximumReconnectAttempts(0) + .build()) { + DaemonSessionClient first = daemon.createSession(); + DaemonSessionClient second = daemon.createSession(); + CompletableFuture manualHeartbeat = CompletableFuture.runAsync( + first::heartbeat); + try { + assertTrue(heartbeatEntered.await(1, TimeUnit.SECONDS)); + Thread.sleep(100); + PromptCall call = second.startPrompt(PromptRequest.builder() + .addText("go") + .observationTimeout(Duration.ofMillis(200)) + .build(), PromptObserver.NOOP); + assertTrue(streamOpened.await(1, TimeUnit.SECONDS)); + CountDownLatch completed = new CountDownLatch(1); + call.completionFuture().whenComplete((outcome, failure) -> + completed.countDown()); + assertTrue(completed.await(1, TimeUnit.SECONDS)); + CompletionException failure = assertThrows( + CompletionException.class, + () -> call.completionFuture().join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + } finally { + releaseHeartbeat.countDown(); + releaseStream.countDown(); + manualHeartbeat.join(); + } + } + } + + @Test + void streamCloseDoesNotBlockScheduler() throws Exception { + CountDownLatch firstCloseEntered = new CountDownLatch(1); + CountDownLatch releaseFirstClose = new CountDownLatch(1); + CountDownLatch timerDispatchedSecondClose = new CountDownLatch(1); + CountDownLatch secondStreamClosed = new CountDownLatch(1); + InputStream first = new ByteArrayInputStream(new byte[0]) { + @Override + public void close() { + firstCloseEntered.countDown(); + awaitUninterruptibly(releaseFirstClose); + } + }; + InputStream second = new ByteArrayInputStream(new byte[0]) { + @Override + public void close() throws IOException { + secondStreamClosed.countDown(); + super.close(); + } + }; + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(2) + .build()) { + try { + daemon.scheduler().execute(() -> daemon.closeStreamAsync(first)); + assertTrue(firstCloseEntered.await(1, TimeUnit.SECONDS)); + daemon.scheduler().execute(() -> { + daemon.closeStreamAsync(second); + timerDispatchedSecondClose.countDown(); + }); + assertTrue(timerDispatchedSecondClose.await(1, TimeUnit.SECONDS)); + assertTrue(secondStreamClosed.await(1, TimeUnit.SECONDS)); + } finally { + releaseFirstClose.countDown(); + } + } + } + + @Test + void streamCloseFailureIsReported() { + InputStream stream = new ByteArrayInputStream(new byte[0]) { + @Override + public void close() throws IOException { + throw new IOException("close failed"); + } + }; + + try (DaemonClient daemon = newClient()) { + CompletionException failure = assertThrows(CompletionException.class, + () -> daemon.closeStreamAsync(stream).join()); + assertInstanceOf(IOException.class, failure.getCause()); + } + } + + @Test + void observationTimeoutSettlesWhileStreamCloseWorkerIsBlocked() + throws Exception { + assertStoppedPromptSettlesWithBlockedClose(200, false); + } + + @Test + void observationTimeoutSettlesWhileErrorBodyCloseWorkerIsBlocked() + throws Exception { + assertStoppedPromptSettlesWithBlockedClose(503, false); + } + + @Test + void sessionCloseSettlesWhileStreamCloseWorkerIsBlocked() + throws Exception { + assertStoppedPromptSettlesWithBlockedClose(200, true); + } + + private void assertStoppedPromptSettlesWithBlockedClose(int status, + boolean closeSession) throws Exception { + CountDownLatch blockerCloseEntered = new CountDownLatch(1); + CountDownLatch releaseBlockerClose = new CountDownLatch(1); + CountDownLatch streamOpened = new CountDownLatch(1); + CountDownLatch releaseStream = new CountDownLatch(1); + InputStream blocker = new ByteArrayInputStream(new byte[0]) { + @Override + public void close() { + blockerCloseEntered.countDown(); + awaitUninterruptibly(releaseBlockerClose); + } + }; + server.createContext("/session/session-1/prompt", exchange -> + sendJson(exchange, 202, + "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> { + String contentType = status == 200 + ? "text/event-stream" : "application/json"; + String partialBody = status == 200 + ? ": keep-alive\n\n" : "{\"error\":\"partial"; + exchange.getResponseHeaders().set("Content-Type", contentType); + exchange.sendResponseHeaders(status, 0); + exchange.getResponseBody().write( + partialBody.getBytes(StandardCharsets.UTF_8)); + exchange.getResponseBody().flush(); + streamOpened.countDown(); + await(releaseStream); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build(); + try { + daemon.closeStreamAsync(blocker); + assertTrue(blockerCloseEntered.await(1, TimeUnit.SECONDS)); + DaemonSessionClient session = daemon.createSession(); + PromptCall call = session.startPrompt(PromptRequest.builder() + .addText("go") + .observationTimeout(closeSession + ? Duration.ofSeconds(30) : Duration.ofMillis(200)) + .build(), PromptObserver.NOOP); + assertTrue(streamOpened.await(1, TimeUnit.SECONDS)); + if (closeSession) { + session.close(); + } + CompletionException failure = assertThrows( + CompletionException.class, + () -> call.completionFuture().orTimeout( + 1, TimeUnit.SECONDS).join()); + assertInstanceOf(PromptOutcomeIndeterminateException.class, + failure.getCause()); + if (!closeSession) { + assertThrows(PromptAlreadyActiveException.class, + () -> session.startPrompt( + PromptRequest.text("unsafe-reuse"), + PromptObserver.NOOP)); + } + } finally { + releaseBlockerClose.countDown(); + releaseStream.countDown(); + daemon.close(); + } + } + + @Test + void stalledStreamCleanupAppliesBackpressureBeforePromptExecution() + throws Exception { + CompletableFuture firstCleanup = new CompletableFuture<>(); + CountDownLatch firstReleased = new CountDownLatch(1); + AtomicInteger rejectedTaskRuns = new AtomicInteger(); + + try (DaemonClient daemon = clientBuilder() + .maximumConcurrentPrompts(1) + .build()) { + daemon.submit(() -> { }, () -> { }, firstReleased::countDown, + () -> firstCleanup); + assertTrue(firstReleased.await(1, TimeUnit.SECONDS)); + + assertThrows(DaemonClientCapacityException.class, + () -> daemon.submit(rejectedTaskRuns::incrementAndGet, + () -> { }, () -> { }, + () -> CompletableFuture.completedFuture(null))); + assertEquals(0, rejectedTaskRuns.get()); + + firstCleanup.complete(null); + CountDownLatch recovered = new CountDownLatch(1); + daemon.submit(() -> { }, () -> { }, recovered::countDown, + () -> CompletableFuture.completedFuture(null)); + assertTrue(recovered.await(1, TimeUnit.SECONDS)); + } finally { + firstCleanup.complete(null); + } + } + + @Test + void doesNotRetryPromptWhenAdmissionResponseIsLost() { + AtomicInteger prompts = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + prompts.incrementAndGet(); + exchange.close(); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.acceptanceFuture().join()); + assertInstanceOf(PromptAdmissionUnknownException.class, + failure.getCause()); + } + assertEquals(1, prompts.get()); + } + + @Test + void retryableHttpPromptFailureIsAdmissionUnknownAndNotRetried() { + AtomicInteger prompts = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + prompts.incrementAndGet(); + sendJson(exchange, 502, "{\"error\":\"bad gateway\"}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.acceptanceFuture().join()); + PromptAdmissionUnknownException admissionFailure = assertInstanceOf( + PromptAdmissionUnknownException.class, failure.getCause()); + DaemonHttpException cause = assertInstanceOf(DaemonHttpException.class, + admissionFailure.getCause()); + assertEquals(502, cause.getStatusCode()); + assertThrows(PromptAlreadyActiveException.class, + () -> session.startPrompt( + PromptRequest.text("unsafe-reuse"), + PromptObserver.NOOP)); + } + assertEquals(1, prompts.get()); + } + + @Test + void definitivePromptRejectionRemainsHttpError() { + AtomicInteger prompts = new AtomicInteger(); + server.createContext("/session/session-1/prompt", exchange -> { + prompts.incrementAndGet(); + sendJson(exchange, 429, "{\"error\":\"queue full\"}"); + }); + server.createContext("/session/session-1/detach", noContent()); + + try (DaemonClient daemon = newClient(); + DaemonSessionClient session = daemon.createSession()) { + PromptCall call = session.startPrompt(PromptRequest.text("go"), + PromptObserver.NOOP); + CompletionException failure = assertThrows(CompletionException.class, + () -> call.acceptanceFuture().join()); + DaemonHttpException cause = assertInstanceOf(DaemonHttpException.class, + failure.getCause()); + assertEquals(429, cause.getStatusCode()); + assertThrows(CompletionException.class, + () -> call.completionFuture().join()); + + PromptCall retry = session.startPrompt(PromptRequest.text("retry"), + PromptObserver.NOOP); + CompletionException retryFailure = assertThrows( + CompletionException.class, + () -> retry.acceptanceFuture().join()); + assertEquals(429, assertInstanceOf(DaemonHttpException.class, + retryFailure.getCause()).getStatusCode()); + } + assertEquals(2, prompts.get()); + } + + @Test + void saturatesOversizedHeartbeatAndIdleDurations() { + server.createContext("/session/session-1/prompt", exchange -> sendJson(exchange, + 202, "{\"promptId\":\"prompt-1\",\"lastEventId\":0}")); + server.createContext("/session/session-1/events", exchange -> + sendSse(exchange, terminalEvent(1))); + server.createContext("/session/session-1/detach", noContent()); + + Duration oversized = Duration.ofSeconds(Long.MAX_VALUE); + try (DaemonClient daemon = clientBuilder() + .heartbeatInterval(oversized) + .sseIdleTimeout(oversized) + .build(); + DaemonSessionClient session = daemon.createSession()) { + assertEquals(PromptTerminal.Kind.COMPLETE, + session.promptText("go").getTerminal().getKind()); + } + } + + private DaemonClient newClient() { + return clientBuilder().build(); + } + + private static void assertAmbiguousHttpMutation(Runnable mutation, + int expectedStatus) { + MutationOutcomeUnknownException failure = assertThrows( + MutationOutcomeUnknownException.class, mutation::run); + DaemonHttpException cause = assertInstanceOf(DaemonHttpException.class, + failure.getCause()); + assertEquals(expectedStatus, cause.getStatusCode()); + } + + private DaemonClient.Builder clientBuilder() { + return DaemonClient.builder() + .baseUri(baseUri) + .connectTimeout(Duration.ofSeconds(2)) + .requestTimeout(Duration.ofSeconds(2)) + .promptObservationTimeout(Duration.ofSeconds(3)) + .sseIdleTimeout(Duration.ofSeconds(1)) + .heartbeatInterval(Duration.ZERO) + .maximumReconnectAttempts(2); + } + + private static HttpHandler noContent() { + return exchange -> { + exchange.sendResponseHeaders(204, -1); + exchange.close(); + }; + } + + private static void sendJson(HttpExchange exchange, int status, String body) + throws IOException { + byte[] bytes = body.getBytes(StandardCharsets.UTF_8); + exchange.getResponseHeaders().set("Content-Type", "application/json"); + exchange.sendResponseHeaders(status, bytes.length); + exchange.getResponseBody().write(bytes); + exchange.close(); + } + + private static void sendSse(HttpExchange exchange, String events) + throws IOException { + byte[] bytes = ("retry: 0\n\n" + events).getBytes(StandardCharsets.UTF_8); + exchange.getResponseHeaders().set("Content-Type", "text/event-stream"); + exchange.sendResponseHeaders(200, bytes.length); + exchange.getResponseBody().write(bytes); + exchange.close(); + } + + private static String sessionJson() { + return sessionJson("session-1", "client-1"); + } + + private static String sessionJson(String sessionId, String clientId) { + return "{\"sessionId\":\"" + sessionId + + "\",\"workspaceCwd\":\"/tmp/work\"," + + "\"attached\":false,\"clientId\":\"" + clientId + "\"}"; + } + + private static String textEvent(long id, String text) { + return "id: " + id + "\nevent: session_update\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"session_update\"," + + "\"promptId\":\"prompt-1\",\"data\":{\"sessionId\":" + + "\"session-1\",\"update\":{\"sessionUpdate\":" + + "\"agent_message_chunk\",\"content\":{\"type\":\"text\"," + + "\"text\":\"" + text + "\"}}}}\n\n"; + } + + private static String terminalEvent(long id) { + return terminalEventForPrompt(id, "prompt-1"); + } + + private static String terminalEventForPrompt(long id, String promptId) { + return terminalEventForPromptAndSession(id, promptId, "session-1"); + } + + private static String terminalEventForSession(long id, String sessionId) { + return terminalEventForPromptAndSession(id, "prompt-1", sessionId); + } + + private static String terminalEventForPromptAndSession(long id, + String promptId, String sessionId) { + return terminalEvent(id, promptId, sessionId, "end_turn"); + } + + private static String terminalEvent(long id, String promptId, + String stopReason) { + return terminalEvent(id, promptId, "session-1", stopReason); + } + + private static String terminalEvent(long id, String promptId, + String sessionId, String stopReason) { + return "id: " + id + "\nevent: turn_complete\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"turn_complete\"," + + "\"promptId\":\"" + promptId + "\",\"data\":{\"promptId\":" + + "\"" + promptId + "\",\"sessionId\":\"" + sessionId + + "\",\"stopReason\":\"" + stopReason + "\"}}\n\n"; + } + + private static String conflictingTerminalEvent(long id) { + return "id: " + id + "\nevent: turn_complete\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"turn_complete\"," + + "\"promptId\":\"prompt-1\",\"data\":{\"promptId\":" + + "\"prompt-2\",\"sessionId\":\"session-1\"," + + "\"stopReason\":\"end_turn\"}}\n\n"; + } + + private static String errorTerminalEvent(long id) { + return errorTerminalEvent(id, "prompt-1", "model_error", + "model failed"); + } + + private static String errorTerminalEvent(long id, String promptId, + String code, String message) { + return "id: " + id + "\nevent: turn_error\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"turn_error\"," + + "\"promptId\":\"" + promptId + "\",\"data\":{\"promptId\":" + + "\"" + promptId + "\",\"sessionId\":\"session-1\"," + + "\"code\":\"" + code + "\"," + + "\"message\":\"" + message + "\"}}\n\n"; + } + + private static String sessionClosedEvent(long id) { + return "id: " + id + "\nevent: session_closed\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"session_closed\"," + + "\"data\":{\"sessionId\":\"session-1\"}}\n\n"; + } + + private static String updateEvent(long id, String kind, String fields) { + return "id: " + id + "\nevent: session_update\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"session_update\"," + + "\"promptId\":\"prompt-1\",\"data\":{\"sessionId\":" + + "\"session-1\",\"update\":{\"sessionUpdate\":\"" + kind + + "\"," + fields + "}}}\n\n"; + } + + private static String permissionEvent(long id) { + return "id: " + id + "\nevent: permission_request\ndata: {\"id\":" + id + + ",\"v\":1,\"type\":\"permission_request\"," + + "\"promptId\":\"prompt-1\",\"data\":{\"requestId\":" + + "\"request-1\",\"sessionId\":\"session-1\"," + + "\"toolCall\":{\"toolCallId\":\"tool-1\"}," + + "\"options\":[{\"optionId\":" + + "\"allow_once\",\"name\":\"Allow once\"," + + "\"kind\":\"allow_once\"}]}}\n\n"; + } + + private static String syntheticEvent(String type) { + return "event: " + type + "\ndata: {\"v\":1,\"type\":\"" + type + + "\",\"data\":{}}\n\n"; + } + + private static void sleep(long millis) { + try { + Thread.sleep(millis); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + + private static void await(CountDownLatch latch) { + try { + latch.await(); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + } + } + + private static void awaitUninterruptibly(CountDownLatch latch) { + boolean interrupted = false; + while (true) { + try { + latch.await(); + break; + } catch (InterruptedException e) { + interrupted = true; + } + } + if (interrupted) { + Thread.currentThread().interrupt(); + } + } +} diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/HttpSupportTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/HttpSupportTest.java new file mode 100644 index 00000000000..83467972e03 --- /dev/null +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/HttpSupportTest.java @@ -0,0 +1,25 @@ +package com.alibaba.qwen.code.daemon; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.io.ByteArrayInputStream; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.Test; + +class HttpSupportTest { + @Test + void errorReaderLeavesStreamClosureToItsOwner() { + AtomicInteger closes = new AtomicInteger(); + ByteArrayInputStream input = new ByteArrayInputStream( + "error".getBytes(StandardCharsets.UTF_8)) { + @Override + public void close() { + closes.incrementAndGet(); + } + }; + + assertEquals("error", HttpSupport.readError(input, "test")); + assertEquals(0, closes.get()); + } +} diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/JsonSupportTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/JsonSupportTest.java new file mode 100644 index 00000000000..dee9dd84d19 --- /dev/null +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/JsonSupportTest.java @@ -0,0 +1,48 @@ +package com.alibaba.qwen.code.daemon; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import java.util.List; +import java.util.Map; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class JsonSupportTest { + @ParameterizedTest + @ValueSource(strings = { + "{'value':'single quotes'}", + "{\"value\":1,}", + "{\"value\":+1}", + "{\"value\":01}", + "{\"value\":1,\"value\":2}" + }) + void rejectsNonStandardOrAmbiguousJson(String json) { + assertThrows(DaemonProtocolException.class, + () -> JsonSupport.parseObject(json, "test response")); + } + + @Test + void parsesStrictJsonWithoutLosingIntegerPrecision() { + Map parsed = JsonSupport.parseObject( + "{\"value\":9223372036854775808}", "test response"); + assertEquals("9223372036854775808", parsed.get("value").toString()); + } + + @Test + void rejectsNonFiniteJsonNumbersRecursively() { + for (Number value : new Number[] { + Double.NaN, + Double.POSITIVE_INFINITY, + Float.NaN, + Float.NEGATIVE_INFINITY + }) { + Map block = Map.of( + "type", "custom", + "nested", List.of(Map.of("value", value))); + assertThrows(IllegalArgumentException.class, + () -> PromptRequest.builder().addContent(block)); + } + } +} diff --git a/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/SseReaderTest.java b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/SseReaderTest.java new file mode 100644 index 00000000000..4a02b169825 --- /dev/null +++ b/packages/sdk-java/qwencode/src/test/java/com/alibaba/qwen/code/daemon/SseReaderTest.java @@ -0,0 +1,58 @@ +package com.alibaba.qwen.code.daemon; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import java.io.ByteArrayInputStream; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.atomic.AtomicInteger; +import org.junit.jupiter.api.Test; + +class SseReaderTest { + + @Test + void parsesCrLfCommentsAndMultiLineData() throws Exception { + String input = ": heartbeat\r\n\r\nid: 7\r\nevent: update\r\n" + + "data: {\"first\":\r\ndata: true}\r\n\r\n"; + AtomicInteger activity = new AtomicInteger(); + SseReader reader = new SseReader(new ByteArrayInputStream( + input.getBytes(StandardCharsets.UTF_8)), 1024, + activity::incrementAndGet); + + SseReader.Frame frame = reader.next(); + assertEquals(7L, frame.getId()); + assertEquals("update", frame.getEvent()); + assertEquals("{\"first\":\ntrue}", frame.getData()); + assertNull(reader.next()); + assertEquals(1, activity.get()); + } + + @Test + void rejectsMalformedUtf8() { + byte[] invalid = new byte[] {'d', 'a', 't', 'a', ':', ' ', (byte) 0xC3, + (byte) 0x28, '\n', '\n'}; + SseReader reader = new SseReader(new ByteArrayInputStream(invalid), + 1024, () -> { }); + assertThrows(DaemonProtocolException.class, reader::next); + } + + @Test + void rejectsOversizedFrame() { + String input = "data: " + "x".repeat(1024) + "\n\n"; + SseReader reader = new SseReader(new ByteArrayInputStream( + input.getBytes(StandardCharsets.UTF_8)), 128, () -> { }); + assertThrows(DaemonProtocolException.class, reader::next); + } + + @Test + void retainsRetryDirectiveAcrossRetryOnlyFrame() throws Exception { + SseReader reader = new SseReader(new ByteArrayInputStream( + "retry: 3000\n\nid: 1\ndata: {}\n\n" + .getBytes(StandardCharsets.UTF_8)), 1024, () -> { + }); + + assertEquals(1L, reader.next().getId()); + assertEquals(3000L, reader.getRetryMillis()); + } +} diff --git a/scripts/run-java-daemon-sdk-e2e.ts b/scripts/run-java-daemon-sdk-e2e.ts new file mode 100644 index 00000000000..6e783016a49 --- /dev/null +++ b/scripts/run-java-daemon-sdk-e2e.ts @@ -0,0 +1,237 @@ +import { spawn } from 'node:child_process'; +import { + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { + fakeToolCall, + startFakeOpenAIServer, +} from '../integration-tests/fake-openai-server.js'; + +// This harness executes the root bundle, which `npm run build` does not refresh. +// Run `npm run build && npm run bundle` from the repository root first. +const root = process.cwd(); +const cliBundle = path.join(root, 'dist', 'cli.js'); +if (!existsSync(cliBundle)) { + throw new Error( + 'Java daemon E2E requires dist/cli.js; run `npm run build && npm run bundle` from the repository root first.', + ); +} +const temporary = mkdtempSync(path.join(tmpdir(), 'java-daemon-e2e-')); +const workspace = path.join(temporary, 'workspace'); +const testHome = path.join(temporary, 'home'); +const expected = 'java daemon e2e complete'; +const deadlinePrompt = 'java daemon e2e deadline sentinel'; +const cancelPrompt = 'java daemon e2e cancel sentinel'; +const teardownPrompt = 'java daemon e2e teardown sentinel'; +const directPrompt = 'java daemon e2e direct response'; +const token = 'java-daemon-e2e-token'; +mkdirSync(workspace, { recursive: true }); +mkdirSync(path.join(testHome, '.qwen'), { recursive: true }); +writeFileSync( + path.join(testHome, '.qwen', 'settings.json'), + JSON.stringify({ ui: { enableFollowupSuggestions: false } }), +); + +const fake = await startFakeOpenAIServer(({ body }) => { + const messageList = Array.isArray(body['messages']) ? body['messages'] : []; + const latestUser = [...messageList] + .reverse() + .find( + (message) => + typeof message === 'object' && + message !== null && + (message as Record)['role'] === 'user', + ); + const latestUserText = JSON.stringify(latestUser ?? {}); + if (latestUserText.includes(directPrompt)) { + return { content: expected }; + } + if (latestUserText.includes(teardownPrompt)) { + return { + toolCalls: [ + fakeToolCall('write_file', { + file_path: path.join(workspace, 'teardown.txt'), + content: 'must not be written', + }), + ], + }; + } + if ( + latestUserText.includes(deadlinePrompt) || + latestUserText.includes(cancelPrompt) + ) { + return new Promise(() => {}); + } + const messages = JSON.stringify(messageList); + if (!messages.includes('"role":"tool"')) { + return { + toolCalls: [ + fakeToolCall('write_file', { + file_path: path.join(workspace, 'created.txt'), + content: 'created by Java daemon E2E', + }), + ], + }; + } + return { content: expected }; +}); + +const cleanEnvironment = Object.fromEntries( + Object.entries(process.env).filter( + ([key]) => + !/^(https?|all)_proxy$/i.test(key) && + !/^(qwen|dashscope|openai|anthropic|google|gemini|azure|aws|vertex)_/i.test( + key, + ) && + !/(api_?key|token|secret|password|credentials?)$/i.test(key), + ), +); +const daemon = spawn( + process.execPath, + [ + cliBundle, + 'serve', + '--port', + '0', + '--hostname', + '127.0.0.1', + '--require-auth', + '--prompt-deadline-ms', + '60000', + '--workspace', + workspace, + ], + { + cwd: root, + env: { + ...cleanEnvironment, + HOME: testHome, + QWEN_HOME: path.join(testHome, '.qwen'), + NO_PROXY: '127.0.0.1,localhost', + no_proxy: '127.0.0.1,localhost', + OPENAI_API_KEY: 'fake-key', + OPENAI_BASE_URL: fake.baseUrl, + OPENAI_MODEL: 'fake-model', + QWEN_MODEL: 'fake-model', + QWEN_SERVER_TOKEN: token, + }, + stdio: ['ignore', 'pipe', 'pipe'], + }, +); +const daemonClosed = new Promise((resolve) => { + daemon.once('close', () => resolve()); +}); + +let stderr = ''; +let succeeded = false; +daemon.stderr?.on('data', (chunk) => { + stderr += chunk.toString(); +}); + +async function stopDaemon(): Promise { + if (daemon.exitCode === null && daemon.signalCode === null) { + daemon.kill('SIGTERM'); + } + const forceTimer = setTimeout(() => daemon.kill('SIGKILL'), 5_000); + try { + await daemonClosed; + } finally { + clearTimeout(forceTimer); + } +} + +try { + const port = await new Promise((resolve, reject) => { + const timer = setTimeout( + () => reject(new Error(`daemon startup timed out\n${stderr}`)), + 15_000, + ); + let output = ''; + daemon.stdout?.on('data', (chunk) => { + output += chunk.toString(); + const match = output.match(/listening on http:\/\/127\.0\.0\.1:(\d+)/); + if (match) { + clearTimeout(timer); + resolve(Number(match[1])); + } + }); + daemon.once('error', (error) => { + clearTimeout(timer); + reject(error); + }); + daemon.once('exit', (code) => { + clearTimeout(timer); + reject(new Error(`daemon exited with ${code}\n${stderr}`)); + }); + }); + + const javaTest = spawn( + 'mvn', + [ + '--batch-mode', + '--no-transfer-progress', + '-Dgpg.skip=true', + '-Dgroups=daemon-integration', + '-Dtest=DaemonServeE2ETest', + 'test', + ], + { + cwd: path.join(root, 'packages', 'sdk-java', 'qwencode'), + env: { + ...cleanEnvironment, + QWEN_DAEMON_E2E_BASE_URL: `http://127.0.0.1:${port}`, + QWEN_DAEMON_E2E_TOKEN: token, + QWEN_DAEMON_E2E_WORKSPACE: workspace, + QWEN_DAEMON_E2E_EXPECTED_TEXT: expected, + QWEN_DAEMON_E2E_DEADLINE_PROMPT: deadlinePrompt, + QWEN_DAEMON_E2E_CANCEL_PROMPT: cancelPrompt, + QWEN_DAEMON_E2E_TEARDOWN_PROMPT: teardownPrompt, + QWEN_DAEMON_E2E_DIRECT_PROMPT: directPrompt, + }, + stdio: 'inherit', + }, + ); + const result = await new Promise((resolve, reject) => { + javaTest.once('error', reject); + javaTest.once('exit', resolve); + }); + if (result !== 0) { + const logPath = path.join( + testHome, + '.qwen', + 'debug', + 'daemon', + 'daemon.log', + ); + let daemonLog = ''; + try { + daemonLog = readFileSync(logPath, 'utf8'); + } catch { + daemonLog = '(daemon log unavailable)'; + } + throw new Error( + `Java E2E failed with ${result}; fake requests=${fake.requests.length}\n${stderr}\n${daemonLog}`, + ); + } + if (fake.requests.length === 0) { + throw new Error( + 'Java E2E completed without exercising the daemon model path; the integration tests may have been skipped', + ); + } + succeeded = true; +} finally { + await stopDaemon(); + await fake.close(); + if (succeeded) { + rmSync(temporary, { recursive: true, force: true }); + } else { + console.error(`Retained Java daemon E2E state at ${temporary}`); + } +}