Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
107 commits
Select commit Hold shift + click to select a range
2162c8b
Keep caller values out of OpenCLI debug logs
loong10k Nov 18, 2026
03c3bc2
Keep process and transport diagnostics free of caller data
loong10k Nov 18, 2026
6fa874a
Add explicit bounded diagnostic exports
loong10k Nov 18, 2026
a9d6906
Backport bounded OpenCLI argv and process lifecycle contracts
loong10k Nov 18, 2026
e0cd1cd
Backport consistent OpenCLI cleanup deadline evidence
loong10k Nov 18, 2026
a17b6a5
Verify native subprocess contracts on macOS and Windows
loong10k Nov 18, 2026
2553de6
ci: record subprocess evidence with valid contract selectors
loong10k Nov 18, 2026
884953f
test: verify bounded OpenCLI network follow outcomes
loong10k Nov 18, 2026
0e834df
fix: backport reverse WebSocket worker safeguards
loong10k Nov 18, 2026
1ed41f9
test: exercise OpenCLI process privacy across platforms
loong10k Nov 18, 2026
2b5fa85
docs: record live OpenCLI network follow verification
loong10k Nov 18, 2026
6985cc3
test: record OpenCLI error parser review evidence
loong10k Nov 18, 2026
6ab6fcc
fix: cap OpenCLI capture buffer allocation
loong10k Nov 18, 2026
60a86e2
test: verify OpenCLI saturated process and capture limits
loong10k Nov 18, 2026
1847740
test: cover cancellation with inherited OpenCLI pipes
loong10k Nov 18, 2026
dd3ce6e
fix: allocate OpenCLI output capture on first write
loong10k Nov 18, 2026
d436d2d
fix: bound blocking OpenCLI process termination
loong10k Nov 18, 2026
08db6f1
test: verify OpenCLI argv snapshot while queued
loong10k Nov 18, 2026
92ec127
docs: link shared OpenCLI argv history from backports
loong10k Nov 18, 2026
20d5d6b
test: use native Windows argv probe for queued calls
loong10k Nov 18, 2026
59f4ad9
fix: retire stopped OpenCLI WebSocket generations
loong10k Nov 18, 2026
ac80a5d
fix: drain OpenCLI reverse worker on restartable stop
loong10k Nov 18, 2026
4270441
fix: bound and gate OpenCLI WebSocket ingress
loong10k Nov 18, 2026
e5bf005
fix: reconnect OpenCLI worker after failed result delivery
loong10k Nov 18, 2026
a5d85af
test: verify OpenCLI worker resources across disconnect and close
loong10k Nov 18, 2026
3fa2d1f
ci: add Intel macOS subprocess coverage
loong10k Nov 18, 2026
daeb1b7
fix: keep private data out of OpenCLI exception diagnostics
loong10k Nov 18, 2026
a0f1655
ci: require exception privacy evidence on hosted platforms
loong10k Nov 18, 2026
2c4ddeb
docs: align OpenCLI consumer examples with the version line
loong10k Nov 18, 2026
f0f880b
Reject malformed legacy collect response envelopes
loong10k Nov 18, 2026
fa7e001
Merge verified Maven coverage and Wrapper maintenance configuration
loong10k Nov 18, 2026
2ca2d31
Reject lossy legacy collect argv before dispatch
loong10k Nov 18, 2026
866c65e
Preserve executor overrides for local passthrough
loong10k Nov 18, 2026
7f17d75
Bound decoded legacy collect response bodies
loong10k Nov 18, 2026
869bef6
Apply a total budget to legacy HTTP collect
loong10k Nov 18, 2026
2555ab9
Retain status and exit provenance for legacy collect
loong10k Nov 18, 2026
1ee75dc
Send explicit collect credentials only over verified HTTPS
loong10k Nov 18, 2026
85de78f
Verify HTTPS collect under an Agent path prefix
loong10k Nov 18, 2026
e769bb6
Capture OpenCLI 1.8.8 structured help contracts
loong10k Nov 18, 2026
7001ed8
Keep raw availability details out of startup diagnostics
loong10k Nov 18, 2026
aed48d9
Merge branch 'feature/REQ-20261118-wandl-opencli-privacy-30' of https…
loong10k Nov 18, 2026
ea3cae1
Require pinned structured help evidence in OpenCLI CI
loong10k Nov 18, 2026
6a50081
Decode versioned OpenCLI structured help with explicit unknown states
loong10k Nov 18, 2026
49726d1
Validate complete OpenCLI structured help output
loong10k Nov 18, 2026
7d85857
Probe trusted local OpenCLI root capabilities with bounded execution
loong10k Nov 18, 2026
c997fb4
Reject malformed structured help catalogs
loong10k Nov 18, 2026
c8a5b17
Retain matching OpenCLI help snapshots on failed refresh
loong10k Nov 18, 2026
e83bc00
Discover pinned OpenCLI help scopes without executing commands
loong10k Nov 18, 2026
3173df5
Reject malformed version output before capability discovery
loong10k Nov 18, 2026
f579865
Bind and validate discovered OpenCLI commands before local execution
loong10k Nov 18, 2026
9f94dba
Verify OpenCLI capability provenance with real local and plugin overr…
loong10k Nov 18, 2026
391f9ef
Verify OpenCLI help metadata does not establish provenance
loong10k Nov 18, 2026
3a930a8
Use a portable file URI for OpenCLI integration test preload
loong10k Nov 18, 2026
25e1c58
Preserve bounded OpenCLI stderr envelopes and observed exit evidence
loong10k Nov 18, 2026
d1b6b1e
Verify OpenCLI error envelope parity across wire formats
loong10k Nov 18, 2026
432dac2
Add strict OpenCLI browser tab and navigation results
loong10k Nov 18, 2026
488ff85
Verify typed browser failures preserve the original subprocess result
loong10k Nov 18, 2026
5242e11
Decode OpenCLI DOM and AX state results by output format
loong10k Nov 18, 2026
cdd9609
Validate OpenCLI snapshot header and line separators
loong10k Nov 18, 2026
7992972
Add strict OpenCLI browser query and capture results
loong10k Nov 18, 2026
aef9942
Preserve the OpenCLI console level field in typed results
loong10k Nov 18, 2026
5a464a3
Bind isolated OpenCLI invocation context to verified option scopes
loong10k Nov 18, 2026
e3f1af0
Snapshot OpenCLI positional arguments before capability probes
loong10k Nov 18, 2026
5c35d33
Report OpenCLI diagnostics without loading runtime or repair commands
loong10k Nov 18, 2026
e16799f
Verify typed OpenCLI results through a real Browser Bridge
loong10k Nov 18, 2026
ee71369
Require nonempty evidence per OpenCLI contract suite
loong10k Nov 18, 2026
c22fe45
Run the installed launcher contract on every Windows maintenance line
loong10k Nov 18, 2026
15126bf
Separate current OpenCLI contract evidence from prior test reports
loong10k Nov 18, 2026
a384a5b
Exercise OpenCLI browser query and capture through the real bridge
loong10k Nov 18, 2026
5955fc1
Enforce shared OpenCLI fixture provenance on every Java line
loong10k Nov 18, 2026
97aee9a
test: verify private diagnostics for malformed OpenCLI YAML errors
loong10k Nov 18, 2026
0bcb405
test: verify OpenCLI typed Browser operations retain bound tabs
loong10k Nov 18, 2026
e5811f1
fix: retain evidence when legacy OpenCLI collect loses its response
loong10k Nov 18, 2026
72c9dd8
test: verify OpenCLI context remains isolated on command failure
loong10k Nov 18, 2026
9446bdb
test: synchronize overlapping OpenCLI context failure calls
loong10k Nov 18, 2026
9b0c385
test: verify bounded OpenCLI follow preserves the shared bridge
loong10k Nov 18, 2026
424834d
Record reproducible upstream OpenCLI manifest provenance
loong10k Nov 18, 2026
ecb3c24
Lock and replay the OpenCLI 1.8.8 upstream samples
loong10k Nov 18, 2026
d39c0b3
Correlate local OpenCLI failure diagnostics without payloads
loong10k Nov 18, 2026
6bdf99a
Wait for inherited-pipe fixture to stop writing before cleanup
loong10k Nov 18, 2026
f2b1bc6
fix: preserve legacy subprocess API and report late reader failures
loong10k Nov 18, 2026
1a326a6
Merge commit '6bdf99aa5ddb58780f81e3d6ae71ef09ac50e8f8' into feature/…
loong10k Nov 18, 2026
36da01e
fix: retain HTTP status when agent response encoding is invalid
loong10k Nov 18, 2026
50777b5
fix: retain bounded writes on legacy subprocess output streams
loong10k Nov 18, 2026
df3b58c
Require HTTP protocol regressions in OpenCLI platform checks
loong10k Nov 18, 2026
68a7bc8
Verify legacy collect against a real loopback OpenCLI Agent
loong10k Nov 18, 2026
5cfa937
Exercise bounded legacy streams across OpenCLI platforms
loong10k Nov 18, 2026
2e4de09
Verify the real OpenCLI Agent behind local TLS authentication
loong10k Nov 18, 2026
d0f0205
Allowlist default OpenCLI configuration diagnostics
loong10k Nov 18, 2026
5bee58b
Hide OpenCLI request data from default diagnostics
loong10k Nov 18, 2026
0b4b0c8
Correlate OpenCLI reverse WebSocket diagnostics safely
loong10k Nov 18, 2026
a0ba264
Sanitize OpenCLI HTTP cleanup exceptions
loong10k Nov 18, 2026
89da70e
Complete OpenCLI provider diagnostic verification
loong10k Nov 18, 2026
3009021
Preserve unchecked OpenCLI subprocess pipe failures
loong10k Nov 18, 2026
4c9eaab
Avoid redirected file handles in OpenCLI process fixture
loong10k Nov 18, 2026
4411a4b
Guard Windows strict argv and negated option aliases
loong10k Nov 18, 2026
e4022f1
Complete OpenCLI argv launcher and migration review
loong10k Nov 18, 2026
5680f84
Require capability test evidence in OpenCLI contract CI
loong10k Nov 18, 2026
24a571a
Exercise the real OpenCLI Browser Bridge on Windows and Linux
loong10k Nov 18, 2026
83a5416
Launch Browser Bridge on hosted Ubuntu and Windows runners
loong10k Nov 18, 2026
75263b1
Prepare the active user tab before the Browser Bridge contract
loong10k Nov 18, 2026
3c871ad
Record the verified Browser Bridge cleanup matrix
loong10k Nov 18, 2026
7c09357
Require each Browser Bridge contract case in live evidence
loong10k Nov 18, 2026
8a6b45c
Allow scheduling slack in the simultaneous-signal fixture
loong10k Nov 18, 2026
cbf3e88
Reject valueless options before legacy OpenCLI collect
loong10k Nov 18, 2026
c1f30c4
ci: require all OpenCLI contract trace suites on each platform
loong10k Nov 19, 2026
8f71a4b
ci: require execution of traced OpenCLI contract methods
loong10k Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,18 @@ jobs:
java-version: '21'
cache: maven

- name: Verify shared contract fixtures and source lock
working-directory: src/test/resources/opencli-contracts/v1
run: sha256sum --strict -c SHA256SUMS

- name: Verify pinned structured help samples
working-directory: src/test/resources/opencli-contracts/v1/structured-help-1.8.8
run: sha256sum --strict -c SHA256SUMS

- name: Verify pinned browser output samples
working-directory: src/test/resources/opencli-contracts/v1/browser-output-1.8.8
run: sha256sum --strict -c SHA256SUMS

- name: Build and verify with JaCoCo coverage
run: ./mvnw -B --no-transfer-progress clean verify

Expand Down
135 changes: 135 additions & 0 deletions .github/workflows/platform-contracts.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
name: Platform subprocess contracts

on:
push:
branches: [feature/REQ-20261118-wandl-opencli-privacy-30]

permissions:
contents: read

jobs:
process-platform:
name: Subprocess contracts (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, macos-15-intel, windows-latest]
runs-on: ${{ matrix.os }}
timeout-minutes: 15
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v5
with:
distribution: temurin
java-version: '21'
cache: maven
- uses: actions/setup-python@v7
with:
python-version: '3.13'
- uses: actions/setup-node@v4
if: runner.os == 'Windows'
with:
node-version: '22'
- name: Exercise real subprocess contracts
run: |
mkdir -p platform-evidence
if [[ "$RUNNER_OS" == Windows ]]; then
OPENCLI_CONTRACT_NODE_EXECUTABLE="$(node -p 'process.execPath')"
export OPENCLI_CONTRACT_NODE_EXECUTABLE
fi
java -version > platform-evidence/java.txt 2>&1
bash ./mvnw -version > platform-evidence/maven.txt 2>&1
result=0
bash ./mvnw -B --no-transfer-progress \
-Dtest=OpenCliCapabilityDiscoveryTest,OpenCliCapabilityCommandTest,OpenCliErrorEnvelopeTest,OpenCliBrowserResultTest,OpenCliBrowserEvidenceResultTest,OpenCliDiagnosticsTest,OpenCliInvocationContextTest,OpenCliArgvContractTest,OpenCliStructuredArgvContractTest,OpenCliProcessContractTest,OpenCliProcessBoundaryTest,SubprocessCleanupFaultTest,SubprocessCompletionRaceTest,SubprocessStreamFailureTest,OpenCliWsReverseAgentSessionTest,OpenCliWsCollectRequestsTest,OpenCliRemoteAgentHttpClientTest,OpenCliProcessPrivacyTest,OpenCliArgSupportTest#shouldKeepConversionExceptionAndNestedCausePrivate,SubprocessExecutionSupportTest#shouldKeepNativePathOutOfDefaultHandlerException+legacyOutputStreamsAllowBoundedWritesWithoutChangingExecutionDetails,OpenCliStructuredHelpFixtureTest,OpenCliHelpParserTest,OpenCliArgvToCollectParserFullTest,OpenCliDiagnosticExportTest \
test > platform-evidence/maven.log 2>&1 || result=$?
tail -100 platform-evidence/maven.log
python scripts/contract_report.py \
--reports target/surefire-reports \
--trace openspec/changes/enforce-opencli-branch-contract-parity/evidence/final-requirement-trace.md \
--head "$(git rev-parse HEAD)" \
--branch "$GITHUB_REF_NAME" \
--java-version-file platform-evidence/java.txt \
--maven-version-file platform-evidence/maven.txt \
--exit-code "$result" \
--suite enumeration=io.github.easy4j.opencli.contract.OpenCliHelpParserTest \
--suite enumeration=io.github.easy4j.opencli.contract.OpenCliStructuredHelpFixtureTest \
--suite enumeration=io.github.easy4j.opencli.capability.OpenCliCapabilityDiscoveryTest \
--suite argv=io.github.easy4j.opencli.capability.OpenCliCapabilityCommandTest \
--suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \
--suite argv=io.github.easy4j.opencli.contract.OpenCliStructuredArgvContractTest \
--suite process=io.github.easy4j.opencli.contract.OpenCliProcessContractTest \
--suite process=io.github.easy4j.opencli.contract.OpenCliProcessBoundaryTest \
--suite process=io.github.easy4j.opencli.core.support.SubprocessCleanupFaultTest \
--suite process=io.github.easy4j.opencli.core.support.SubprocessCompletionRaceTest \
--suite process=io.github.easy4j.opencli.core.support.SubprocessStreamFailureTest \
--suite protocol=io.github.easy4j.opencli.remote.OpenCliArgvToCollectParserFullTest \
--suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsReverseAgentSessionTest \
--suite protocol=io.github.easy4j.opencli.center.ws.OpenCliWsCollectRequestsTest \
--suite protocol=io.github.easy4j.opencli.remote.OpenCliRemoteAgentHttpClientTest \
--suite process=io.github.easy4j.opencli.core.OpenCliProcessPrivacyTest \
--suite argv=io.github.easy4j.opencli.core.OpenCliArgSupportTest \
--suite process=io.github.easy4j.opencli.core.support.SubprocessExecutionSupportTest \
--suite protocol=io.github.easy4j.opencli.contract.OpenCliErrorEnvelopeTest \
--suite typed-result=io.github.easy4j.opencli.core.OpenCliDiagnosticExportTest \
--suite typed-result=io.github.easy4j.opencli.contract.OpenCliBrowserResultTest \
--suite typed-result=io.github.easy4j.opencli.contract.OpenCliBrowserEvidenceResultTest \
--suite typed-result=io.github.easy4j.opencli.capability.OpenCliDiagnosticsTest \
--suite argv=io.github.easy4j.opencli.capability.OpenCliInvocationContextTest \
--output platform-evidence/report.json
exit "$result"
- name: Verify npm-installed OpenCLI on Windows
if: runner.os == 'Windows'
run: bash scripts/run_installed_contracts.sh bash ./mvnw
- name: Upload platform subprocess evidence
if: always()
uses: actions/upload-artifact@v7
with:
name: subprocess-${{ matrix.os }}-${{ github.sha }}
path: |
platform-evidence
target/surefire-reports
if-no-files-found: error


browser-bridge:
name: Real Browser Bridge (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
timeout-minutes: 15
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v7
- uses: actions/setup-java@v5
with:
distribution: temurin
java-version: '21'
cache: maven
- uses: actions/setup-python@v7
with:
python-version: '3.13'
- uses: actions/setup-node@v4
with:
node-version: '24.18.0'
- name: Install the published OpenCLI in the runner's temporary directory
run: npm install --prefix "$RUNNER_TEMP/opencli-browser-cli" --ignore-scripts --no-audit --no-fund @jackwener/opencli@1.8.8
- name: Exercise the real Chrome extension against the loopback daemon
run: |
python scripts/run_browser_bridge_contracts.py \
--cli-entry "$RUNNER_TEMP/opencli-browser-cli/node_modules/@jackwener/opencli/dist/src/main.js" \
--evidence browser-bridge-evidence -- "$(command -v bash)" ./mvnw
- name: Upload real Bridge evidence
if: always()
uses: actions/upload-artifact@v7
with:
name: browser-bridge-${{ matrix.os }}-${{ github.sha }}
path: browser-bridge-evidence
if-no-files-found: error
43 changes: 38 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Multi-adapter CLI integration SDK for OpenCLI: browser / desktop / public-API ad

### 1.1 What it is

**opencli-java-sdk** integrates Java applications with the [OpenCLI](https://github.com/partme-ai/opencli) multi-adapter CLI ecosystem. It executes `opencli <adapter> ...` subprocesses via Commons Exec, exposes typed results (`OpenCliResult` / `OpenCliTypedResult`), unified exception semantics, remote HTTP agent support (Unirest) and a center WebSocket reverse-agent client (Java-WebSocket). It compiles and runs on JDK 8.
**opencli-java-sdk** integrates Java applications with the [OpenCLI](https://github.com/partme-ai/opencli) multi-adapter CLI ecosystem. It executes `opencli <adapter> ...` subprocesses via Commons Exec, exposes typed results (`OpenCliResult` / `OpenCliTypedResult`), unified exception semantics, remote HTTP agent support (Apache HttpClient) and a center WebSocket reverse-agent client (Java-WebSocket). It compiles and runs on JDK 8.

### 1.2 What it is not

Expand Down Expand Up @@ -73,7 +73,7 @@ Multi-adapter CLI integration SDK for OpenCLI: browser / desktop / public-API ad
| JDK | 21+ | 3.0.x line baseline |
| Maven | 4.0.0-rc-5 | Repository Maven Wrapper version |
| commons-exec | 1.6.0 | Local subprocess execution |
| Unirest Java | 3.14.5 | Remote agent HTTP |
| Apache HttpClient | Provided by Unirest Java 3.14.5 | Remote agent HTTP |
| Java-WebSocket | 1.6.0 | Center WebSocket |
| `tools.jackson.core:jackson-databind` | 3.2.1 | JSON parsing |
| SLF4J | 2.0.18 | Logging facade |
Expand Down Expand Up @@ -102,7 +102,7 @@ Version-line matrix:
| typed wrappers (codex, npm...) |
| meta list / validate / plugin / ... |
| browser session API (wait, extract...) |
| remote POST {base}/collect (Unirest) |
| remote POST {base}/collect (Apache HttpClient) |
| center WebSocket reverse agent |
+------------------------------------------+
|
Expand Down Expand Up @@ -177,24 +177,39 @@ Configuration is object-based via `OpenCliProperties`:
| `executionTarget` | `LOCAL_PROCESS` | `LOCAL_PROCESS` or `REMOTE_AGENT_HTTP` |
| `executable` | `opencli` | Executable name or absolute path |
| `workingDirectory` | — | Subprocess working directory |
| `commandTimeoutMillis` | `300000` | Command timeout (ms; reused as HTTP timeout in remote mode) |
| `commandTimeoutMillis` | `300000` | Command timeout in milliseconds. Remote pool acquisition, connection and response reading share the invocation budget. |
| `maxConcurrentExecutions` | `0` | Max concurrent subprocesses (0 = unlimited) |
| `startupProbeTimeoutMillis` | `30000` | Availability-probe timeout |
| `environment` | `{}` | Extra environment variables (e.g. `OPENCLI_CDP_ENDPOINT`) |
| `remoteAgentBaseUrl` | — | Remote agent base URL |
| `remoteAgentBaseUrl` | — | Remote Agent HTTP(S) base URL. Keep any deployment path prefix and omit user info, queries and fragments. |
| `remoteCollectMode` | `cdp` | `bridge` or `cdp` (must match the agent side) |
| `remoteOutputFormat` | `json` | Output format requested from the agent |
| `remoteCdpEndpoint` | — | Optional CDP endpoint overriding the agent default |
| `remoteCaptureRawHttpResponse` | `false` | Keep the raw HTTP body in `OpenCliResult#getRemoteRawHttpBody()` (large responses — use with care) |
| `maxRemoteResponseBytes` | `10485760` | Positive byte limit after HTTP decompression. An oversized response raises `OpenCliRemoteResponseLimitException` with its HTTP status and limit. Raw capture only applies to accepted bodies. |

Notes:

- In remote mode the `stdout` is the JSON `items` the agent returned (parsed into line items per `format`), which may differ from local raw subprocess text; `leadingArguments` are local-only and are not injected on the remote path.
- A legacy HTTP `/collect` reply must contain a JSON boolean `success`. Invalid envelopes raise `OpenCliRemoteProtocolException`, which extends `OpenCliExecutableFailureException`. A valid reply with `success: true` and omitted or null `items` still returns `[]`.
- Legacy HTTP argv dispatch accepts SDK-listed adapters and one subcommand. Root metadata, Browser sessions, external passthrough, repeated options, `--`, and tokens whose spacing or leading dash cannot be preserved are rejected before HTTP. Place positionals before options and supply an explicit value for each option. The legacy server appends a value to every option, so bare flags require local execution. Use local execution for commands that need the original argv. A deployment with its own adapter contract can use the explicit `OpenCliCollectRequest` API.
- A collect timeout raises `OpenCliRemoteTimeoutException`. After dispatch to the HTTP transport, `isRemoteOutcomeUnknown()` is true. Collect does not automatically retry or follow redirects.
- Inspect `getRemoteExecutionDetails()` on the result or on an exception’s `getPartialResult()` to distinguish HTTP status, Agent business status and the source of `items`. The legacy 0/1 returned by `getExitCode()` is synthetic. HTTP and protocol failure snapshots have no exit code. Accepted response text is available in those snapshots only when raw capture is enabled.
- If a collect connection breaks before a complete response, the failure snapshot reports `TRANSPORT_FAILURE` and `isRemoteOutcomeUnknown()`. `getObservedHttpStatus()` is empty when no headers arrived. The snapshot has no CLI exit code or incomplete response body. Server-specific extensions require a verified Agent contract.
- If your Agent accepts a credential header, configure `setRemoteAuthentication(new OpenCliRemoteAuthentication("Authorization", System.getenv("OPENCLI_AGENT_AUTHORIZATION")))`. Supply the complete header value. The Agent base URL must use HTTPS for credentials and contain no user info, query or fragment. The SDK sends the configured header on `/collect`. OAuth discovery and request signing are unsupported.
- Parse previously captured CLI help with `OpenCliHelpParser.parse(stdout)`. The result retains the original text and reports whether the schema is available. Structured commands preserve placeholders and separate command, namespace, global and common options.
- `execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable).

<a id="8-core-usage"></a>
## 8. Core Usage

### Local argv migration

- Local invocation preserves empty strings, padding, Unicode, line breaks, and literal option terminators. If your application relied on trimming or dropping values, normalize its inputs explicitly before calling the SDK.
- Use the adapter's no-argument invocation or an empty list for a root command. A null varargs array or null token is invalid. An empty string token remains a valid value.
- In the legacy options map, Boolean `false` still omits the option. Use `OpenCliOption.value` for a schema-supported literal `false`, or `OpenCliOption.negated` for a schema-supported negative flag. A negatable option reserves both its positive and negative names, so duplicate definitions across ordered and legacy options are rejected.
- On Windows, use the full path to a native executable such as `node.exe`, with the installed OpenCLI JavaScript entry point in `leadingArguments`. The SDK rejects batch launchers. If the JVM is running in strict process mode, a literal double quote in an argument to a native EXE or an extensionless launcher (the shell `cmd.exe` follows its own command contract) is rejected before spawn with its index and an explanation.

### 8.1 meta() and browser()

```java
Expand Down Expand Up @@ -225,6 +240,24 @@ agent.close();

Protocol: edge sends `register`; center replies `registered`; center sends `collect` (request_id, site, command, args, positional_args, format, mode); the SDK executes `opencli` locally (via `copyForLocalCliExecution()` to avoid loops) and replies `result`; plus `ping` / `pong`.

The reverse agent accepts up to four concurrent collect tasks and 32 queued tasks by default. Set `maxConcurrentCollects` and `maxPendingCollects` on the connection properties before constructing the agent to change the limits. A queue capacity of zero disables waiting. When full, the agent replies with a failed `result` and the error `worker is busy`.

The reverse agent accepts collect only after the current connection acknowledges registration. Incoming WebSocket messages are capped at 1 MiB by default, including the assembled size of fragments. Set `maxInboundMessageBytes` before constructing the agent to configure the finite byte limit. Oversized messages close the affected connection before any command is queued.

Collect request IDs must be nonblank strings of at most 128 UTF-8 bytes. The agent suppresses identical in-flight requests and rejects a reused ID with a different payload. An explicit retry may return a result marked `cached: true`. The in-memory cache keeps up to 1,024 completed results for at most ten minutes. Replay across reconnects requires the same TLS-verified endpoint. Plain WebSocket connections keep session-local deduplication. A new agent instance starts with an empty cache.

`stop()` stops admission, discards queued tasks and allows in-flight work up to five seconds to finish before requesting cancellation. After the runner has stopped, `start()` can reconnect the same instance. `close()` immediately requests cancellation and closes the instance permanently.

### Diagnostic export

Call `OpenCliDiagnosticExport.export(result, 512)` explicitly with an `OpenCliResult` or an exception's partial result. The byte budget applies to UTF-8 text. Output contains only status and field lengths, with a `truncated=true` marker when fields do not fit. Field lengths can disclose how much data was present.

The SDK returns the text in memory. Your application controls the destination and retention. SDK diagnostics omit argv values, raw content, URLs and filesystem paths. Applications that use or log raw results should protect that data. `remoteCaptureRawHttpResponse` is still opt-in.

`OpenCliAvailabilityReport.toDiagnosticMessage()` is suitable for startup logs and reports readiness and status. Read the executable paths or probe message through their dedicated getters when needed.

At the low-level process boundary, `RunSession.getHandler().getException()` returns a safe I/O summary. `RunSession.getIoFailure()` is the explicit raw diagnostic accessor. Handle that exception as sensitive data because it can include local paths.

<a id="9-testing--build"></a>
## 9. Testing & Build

Expand Down
Loading
Loading