Repository navigation
Releases
v0.22.0
Added
- Bounded Python
wait_for_runfor native and bridge clients, with typed results,
local cancellation, and preserved in-flight retrieval ownership. - OpenClaw profile configuration reads and revision-guarded RPC patches for
keyed and legacy agent rosters, preserving shared defaults and other agents.
Fixed
- Reject truncated Claude and Codex streams, release terminal stream readers,
and settle caller cancellation independently of backend cleanup. - Isolate remembered run snapshots and report unknown synchronous runs honestly
when cancellation cannot observe them. Bound gateway snapshot caches and keep
shared reads independent of each caller's cancellation. - Decode fragmented JSON Lines and Content-Length frames with linear copying,
retaining UTF-8 validation and frame limits. Deduplicate normalized provider
self-aliases consistently across gateway and runtime registries. - Update Vite and markdown-it development dependencies to patched releases for
editor command injection and Markdown parsing denial-of-service vulnerabilities. - Include only the selected offline documentation snapshot in npm packages,
excluding archived documentation versions.
v0.21.0
Added
- Native Python lifecycle clients for all seven providers as
cavi-api-client
and an optional TypeScript adapter bridge. Native installation requires no
Node/npm. - Independent PyPI release workflow that publishes validated Python
distributions through Trusted Publishing. - Export the Hermes runtime control factory and options from the provider
subpath for typed dashboard and profile configuration. - OpenCode v2 polling clients:
OpenCodeV2ApiClient,
createOpenCodeV2ProviderModule, and Pythonapi_version=2. Existing v1
clients retain their routes and behavior. V2 streaming is unsupported. - Opt-in observed completion for Managed Agents polling, streaming, and the
interactive driver, with bounded full event history and workflow tracking. - Opt-in canonical OpenClaw TypeScript outcomes and exact response text through
normalizeRunStatus, retaining the nativeprovider_status.
Fixed
- Provision Git documentation snapshots independently of same-version npm
artifacts while retaining commit and digest verification. - Advertise the installed Python package version in OpenClaw connections.
- Release AGY SSE responses after upstream completion or failure without waiting
for the server to close the connection. - Clarify AGY HTTP versus native CLI/SDK interfaces and distinguish OpenCode v1
streaming from the opt-in v2 polling adapter in provider documentation. - Include the required agent selector type when Python creates Managed Agents
sessions, including sessions pinned withmetadata.agent_version. - Link provider and Python references to versioned compatibility options and
document their opt-in defaults consistently across language guides. - Route Hermes dashboard REST and RPC calls to an explicit
dashboardProfile,
authenticate owned dashboard WebSockets withdashboardToken, and use
advertised native API Server session pagination. Native API Servers report
session usage as unavailable rather than calling an absent route. - Normalize native Python OpenClaw completion and failure outcomes while retaining
provider status and exact response text. - Retrieve completed Managed Agents text from paginated session events in Python.
- Abort active OpenCode prompts before closing Python-owned HTTP transport.
- Rebuild unavailable documentation baselines from their pinned source commit.
- Exclude Python bytecode from npm tarballs and documentation artifact pins.
v0.19.0
Added
-
Canonical HTTP integration guide with explicit published/development boundaries
and native HTTP consumer examples checked against the packed candidate. -
RawHttpApiClient.consumeResponsefor consuming a response while retaining
caller cancellation and the HTTP request deadline. -
Optional
RuntimeRunErrorDetailson run statuses, failed stream events, and
facade stream outcomes, carrying observed provider code/type/reason strings.
Codex response/stream and Claude Messages stream mappings preserve available
details alongside existing diagnostic messages and lifecycle behavior. -
waitForRun,RunWaitOptions, andRunWaitResultfrom the root and
contracts: bounded sequential retrieval of an existing run with a local
deadline, poll budget, and caller cancellation. Stopped waits retain the last
observed run; backend work and in-flight HTTP requests are not cancelled. -
Opt-in
requireCompletedRun,requireRunText,requireCompletedStream, and
requireStreamTexthelpers from the root andcore/runtime. They enforce
observed completion and required text with typed run errors, retain original
error causes, preserve explicit empty output, and leave provider behavior
unchanged. Development examples demonstrate answer services and streaming. -
Run outcome error vocabulary:
ApiClientErrorType.Runand
ApiClientErrorCode.RunFailed,RunCancelled,RunIncomplete, and
RunOutputMissing. These additive codes distinguish execution failures,
cancellation, unobserved completion, and absent required output without
changing provider return values.
Removed
- Breaking in 0.19.0: remove the discontinued Gemini provider,
its runtime/files subpath exports, and its capability declarations. Gemini
configuration is not redirected to AGY; migrate explicitly with AGY service
configuration or another supported provider. Historical published declarations
remain in versioned references.
Fixed
-
Generate new-release contract evidence from the inspected npm declarations
without requiring a pre-existing source manifest. Preserve strict validation
for unrelated missing evidence files and release identity mismatches. -
Release dry-run reports reject detached manifests that differ from archive
provenance. Archive inspection and hashing use the same captured bytes. -
Host ingestion checks accept the canonical
docs/api-client/v{VERSION}
release archive layout, preserve root and single-folder layouts, reject
ambiguous documentation roots, and clean up failed extraction attempts.
Documentation releases require this check before asset upload and dispatch. -
Preserve caller-supplied
HttpApiErrorcancellation reasons through JSON and
gateway Fetch helpers instead of converting them intoGatewayHttpError. -
Classify JSON HTTP failures by parse-error identity instead of diagnostic
message text. Paths containingreturned invalid JSONno longer bypass
GatewayHttpErrorstatus and backend-code handling. -
Accept mixed-case JSON content types in gateway JSON and form-data response
parsing instead of rejecting valid JSON responses as protocol mismatches. -
Configure half-duplex for
ReadableStreamHTTP request bodies so native Node
Fetch can send streamed uploads through core and gateway clients. -
Forward Fetch integrity, keepalive, mode, priority, referrer, and referrer-policy
controls through core and gateway HTTP requests instead of silently discarding
them. Add optional matching fields toHttpApiRequestInit. -
Preserve existing query strings and URL fragments in
withQueryinstead of
adding a second?or placing request parameters after the fragment. -
Preserve Fetch's
redirectpolicy through core and gateway HTTP requests,
so explicitmanualanderrorpolicies prevent following redirects. -
Preserve
HEADandOPTIONSwhen converting Fetch requests instead of
silently sendingGET. ExtendHttpApiHttpMethodwith both methods. -
Release unread successful response bodies in Claude Managed Agents environment,
session, resource, memory-store, memory, vault, and credential deletion helpers.
Preserve bodyless acknowledgements and successful results if disposal rejects. -
Release unread successful response bodies in gateway status acknowledgements
and Hermes approval resolution, including its gateway alias. Body cleanup
preserves successful acknowledgements and caller-owned raw streams. -
Keep library JSON response body reads inside the HTTP request lifetime so
caller cancellation and deadlines remain active during consumption. -
Keep gateway JSON, blob, and form-data response body reads inside the HTTP
request lifetime so caller cancellation and deadlines remain active. Raw
gateway responses retain caller-owned stream lifetimes. -
Preserve Fetch
RequestInit.headerswhen converting withtoHttpRequestInit,
including records, tuple lists, andHeadersinstances. An explicit second
argument retains its existing replacement behavior. -
Omit engine-generated response excerpts from HTTP invalid-JSON error messages
so truncated credentials cannot bypass the redacted body preview. Preserve
response status and the original body onHttpApiError. -
Reuse dependency parsing and resolution within ownership guardrail scans to
reduce scan timeouts. Each scan uses fresh caches; boundary assertions and
timeout limits are unchanged. -
Merge HTTP header names case-insensitively. Request overrides replace client
defaults, configured credentials retain precedence, and explicit idempotency
keys and content types no longer become comma-joined duplicates. -
Forward caller headers to the run-start request in
streamHermesChatRun
and itsstreamGatewayChatRunalias, keeping routing and tenant headers
consistent with the subsequent event stream. -
Keep Hermes chat run-start deadlines and caller cancellation active during
response parsing. Remove chat stream abort listeners and dispose subscriptions
when the stream completes, fails, or its consumer throws. -
Publish a fresh tarball from the verified release checkout rather than the
pinned documentation reference artifact. Keep stable docs verification and
npm publication inputs separate. -
Keep HTTP timeouts and caller cancellation active through JSON, blob, file,
and batch-result body reads. Raw responses retain caller-owned stream lifetimes. -
Detach Claude, Codex, and AGY stream abort listeners on completion and failure.
-
Preserve explicitly empty Codex text in run statuses, batch results, and
completed stream snapshots; missing text remains distinct from an empty answer. -
Pin patched development dependencies for Dependabot alerts #40–#42:
source-map-js1.2.2,katex0.18.2, andsmol-toml1.9.0. -
Include the versioned offline documentation tree in the npm package.
-
Codex run statuses, successful batch responses, and completed stream events
now normalize native messageoutput_textcontent when the response has no
stringoutput_textfield. Text is concatenated in wire order without added
separators; explicit text (including an empty string), failure states, and
non-text items retain their existing handling.
Changed
-
Qualify consumer guidance by available exports rather than assuming development
APIs remain unreleased in future documentation assets. -
Pin the published documentation baseline independently of the working package
version. Release preparation retains verified historical docs; release assets
are generated from the exact published npm artifact. -
Add a complete React consumer request workflow with validated handler
responses, pending and failed run IDs, local cancellation, and stale-response
protection. Seven mounted UI tests exercise the installed package and
documented server handler against stable and development artifacts. -
Make the provider-file guide demonstrate reusable clients, persisted upload
IDs, and explicit cleanup with validated deletion receipts. Add seven
runnable file lifecycle tests against the pinned stable package and
development pack, with typed input and protocol errors in the helpers. -
Make the documented text-stream helper reject completed streams without
observed text usingrun_output_missing, while preserving supplied empty
snapshots. Add runnable streaming tests against the pinned stable package
and development pack for snapshots, deltas, partial failures, and gaps. -
Make the documented batch collector distinguish pending work from terminal
batches without results, retain batch context, and reject ambiguous result
IDs with a typed error. Add runnable Claude/Codex collection fixtures checked
against the pinned stable package and development pack. -
Add runnable consumer contract tests for the server handler, checked against
the exact published package and the development pack. The testing guide
covers answer/progress states, input validation, safe failures, and client
cleanup through the public provider and facade entry points. -
Add an executable authorized background-run workflow with separate read and
cancellation permissions, per-poll authorization, retained wait outcomes,
and packed-consumer checks for denied access and explicit cancellation. -
Answer and streaming examples use typed errors with retained run identity;
error guidance shows guards, safe caller messages, and protected diagnostics. -
Replace CLI-style documentation demos with reusable answer services, server
handlers, streaming callbacks, background-run retrieval, and batch collection.
Provider setup now returns usable clients with explicit application ownership. -
Documentation checks now validate runtime-provider HTTP verbs and full route
shapes, including wrapped HTTP lines. Gemini route labels show collection
segments explicitly, and Codex batch routes include the input-file upload. -
Reorganized consumer docume...
v0.18.0
Removed
- Removed the deprecated team-registry forwarding exports from
./providers/hermes(createHermesTeamRegistry,TEAM_REGISTRY_CONFIG,
TeamRegistryConfig) and./providers/openclaw
(createOpenClawTeamRegistry,TEAM_REGISTRY_CONFIG,TeamRegistryConfig).
Import them from./extensions/cavi; see MIGRATION.md.
Added
- Added
isApiClientError, one guard for every error class the package
throws. It is exported from the root and./core/errors.
Changed
- The npm package ships only the brand image the README uses; the other
logo and social-preview files are no longer packed. - Every exported error class now extends
ApiClientErrorand carriestype
andcode:HttpApiError,GatewayHttpError,GatewayRpcError,
GatewayJobTimeoutError,GatewayJobAbortError,PortalConfigPatchError,
GatewayAgentConfigApiError,CapabilityUnavailable,
CapabilityCallRejected,OpenClawWireError, and
WebhookVerificationError. Existing guards (isHttpApiError,
isGatewayHttpError) and classification behavior are unchanged. GatewayHttpError.codeis now always a string. When the gateway sends no
code, it isgateway_error(previouslynull).GatewayJobAbortErrornow satisfiesisAbortError.- Team manifest validation and resolution failures throw
ApiClientErrorwith
typeconfigurationand codeinvalid_configinstead of a plainError.
Messages are unchanged. - No source module throws or rejects with a plain
Errorany more. Messages
are unchanged; each now carries a type and code:- caller input:
validation/validation_failed - client, provider, or registry configuration:
configuration/
invalid_config - responses or frames that break the wire contract:
protocol_mismatch,
orinvalid_jsonfor unparseable bodies - no live gateway connection:
transport/socket_unavailableor
socket_closed - aborted waits and polls:
abort/aborted, with nameAbortError,
so they now satisfyisAbortError
- caller input:
CapabilityClientcalls that fail caller-input validation inside the
package (for example an unsupported media kind) now resolve to a
request-invalidgap instead of rejecting.
v0.17.0
What's Changed
- fix(release): verify npm provenance attestation instead of gitHead by @sasan1200 in #68
- fix(docs): derive version from package metadata by @sasan1200 in #69
- fix(security): harden client boundaries by @sasan1200 in #70
- feat: add policy-aware OpenCode runtime provider by @sasan1200 in #71
- fix: reject premature AGY stream EOF by @sasan1200 in #72
- fix: sanitize Gemini upload errors by @sasan1200 in #73
- fix: harden OpenCode session lifecycle by @sasan1200 in #74
- chore: update vulnerable development dependencies by @sasan1200 in #75
- fix: release composed abort signal listeners by @sasan1200 in #76
- fix: preserve release dry-run artifacts by @sasan1200 in #77
- chore: release 0.17.0 by @sasan1200 in #78
Full Changelog: v0.16.0...v0.17.0
v0.16.0
Added
agyAntigravity runtime provider exposed via./providers/agy- AGY supports
runsandstreamingcapabilities - AGY operations page and navigation entry
- AGY in the capability matrix
docs:host-ingest-checkhost ingest checker- Docs host consumer contract
Changed
API.mdrewritten as an enterprise API index- Exports guide links to the
v0.16.0type reference - Claude Messages, Gemini, and AGY
getRun/cancelRundocumented asSynchronousRunStore src/providers/agy/paths.tsregistered in the operation-endpoint ownership check- README uses
GatewayApiClientandCapabilityClientnaming - GitHub release docs artifact is the canonical ingest channel
- npm docs tree is a convenience mirror
- Navigation splits Operations from Type reference
- Postman guide moved into product docs
- Postman collection and environment regenerated with agnostic placeholders, variable descriptions, and example bodies
- Release orchestration split into
scripts/release/ scripts/docs/covers docs build and check onlyrelease:artifact,release:resolve-npm,release:envelope, andrelease:dry-run-reportreplace thedocs:release-*scripts- Documentation identity derives from
package.jsonversion - Commit, digest, and
sourceDateEpochcome from the versioned source manifest - Runtime-control release evidence stays local under
.artifacts/runtime-control/ - npm
filesallowlist shipsdocs/api-client/v*, brand assets, and team-manifest templates - Committed docs artifact is
docs/api-client/v0.16.0 docs:stablepacks the workspace when the registry lacks thepackage.jsonversion- Versioned
docs/api-client/v*trees are stashed for that pack so the digest stays stable - Pack gzip OS byte is canonicalized to Unix so macOS and Linux digests match
- Publish uploads that exact verified tarball
v0.15.0
Added
manifestTeamToTeamandteamDirectoryFromManifestin./core/teams, also root-exported- the facade builds a
TeamDirectoryfrom the resolved manifest when no explicit teams backend is wired classifyCapabilityFailuremaps statuslessBackendUnavailableerrors to abackend-unavailablegap by code
Fixed
- a manifest with ambiguous lookup keys degrades
teams.*to abackend-unavailablegap instead of throwing
v0.14.0
Added
- OpenClaw
agentConfig.listProfilesover theagents.listRPC (was a gated stub).normalizeOpenClawAgentProfilesmaps{ defaultId, agents:[{ id, name, workspace, agentRuntime }] }toAgentProfileSummary[]. createApiClienthandshake options for non-browser clients:clientOrigin(WSOrigin; auto-derived from base origin for non-cli modes),clientMode("cli"preserves operator scopes over shared-secret auth),requestedScopes. Backed byGatewayRpcClientOptions.origin.streamRunreturnsCapabilityResult<RunStreamOutcome>({ runId, outcome }); a caller abort resolvesok:falsewith arequest-abortedgap and a best-effortcancelRun.
Fixed
- OpenClaw
streamRundelivered no events (stream hung): the bridge decoded control-planeoperation.*frames, but runs emit nativechat/agentframes keyed byrunId. AddedcreateOpenClawRunNativeEventStream(one shared listener fans out byrunId). - Abort landing before the first event orphaned the run: gateway bridges report the run id via
onRunIdonstartRun(forwarded through the dispose tracker), so the best-effortcancelRunfires. GatewayRpcErrornow classifies by gRPC code (UNAVAILABLE→backend-unavailable,INVALID_REQUEST→request-invalid,NOT_FOUND→endpoint-not-found;UNAUTHENTICATED/PERMISSION_DENIEDrethrow), so a control-plane RPC failure degrades to a gap instead of throwing out of a read.- OpenClaw wire parsers are forward-compatible: unknown benign fields are tolerated; unsafe content (non-plain objects, non-finite numbers, cycles) and leaked secrets (a sensitive-named key with a STRING value) are still rejected. A sensitive-named field holding structured metadata (
apiKey: { source, envVar }) is tolerated. FixesauthStatus.listAuthStatusandsessions.listfailures.
v0.13.0
Added
-
Unified capability contract (foundation of the single-client redesign):
CAPABILITY_TAXONOMYin./core/runtime— one provider-agnostic
capability list (the union of the legacy runtime surfaces and
control-plane modules, de-duplicated), withCapabilityKey,
CapabilityMap, andCapabilitySupporttypes.PROVIDER_CAPABILITIES— the single static declaration site per provider
(conservative fallback), with an equivalence test against the legacy
capability matrix.- Runtime capability sourcing in
./contracts:
ResolvedProviderCapabilities,ProviderCapabilityResolver, and
mergeCapabilitySupport(runtime authoritative, static fallback). - Provider transforms + resolvers:
transformHermesCapabilities/
createHermesCapabilityResolver(live API-server capabilities envelope →
unified supports +TeamManifestwith members/actions built from
provider-published paths) andtransformOpenClawHello/
createOpenClawCapabilityResolver(hello-ok handshake → unified supports;
manifest actions from the provider REST manifest + canonical media/wiki
tables).GatewayRpcClientnow retains the raw handshake payload and
exposesgetHelloFrame(). - The single client surface:
createCapabilityClientin./contractsand
thecreateApiClient(provider, options)front door — every capability
accessor exists on every provider (sessions, tasks, events, models, usage,
authStatus, workspace, kanban, teams, media, wiki, agentConfig plus the
universal execution surface); unsupported calls resolve a
CapabilityResultwith a notated gap (ok: false) rather than throwing;
gateway providers auto-wire their resolver and backends from
baseUrl/webSocketUrl. Additive — no existing export changed.
-
Extended
./testinginspectRuntimeProviderConformancewith streaming-path
duality (streamRunor gatewaycreateSseRunEventProvider), required
runLifecycleSemantics(omit|server|sync-store|unsupported-throw)
when getRun/cancelRun are present, and a sync-store foreign-getRunprobe. -
Added a canonical, provider-agnostic
./core/teamscapability:Team/
TeamMembervalue types and a pureTeamDirectoryresolver (resolve teams and
members by id/slug/code/alias), pluscreateTeamDirectoryFromManifestin
./contractsand a./testingconformance kit (validateTeam,
inspectTeamDirectoryConformance). The CAVI team registry now sources its
identifier normalizer from this canonical core. Additive; no runtime behavior
change to existing consumers. -
Added
CapabilityResult,classifyCapabilityFailure,CapabilityCallRejected,
CapabilityGated/CapabilityGatedMethod,StreamRunBody, and
RunStreamOutcomeas root exports — the typed vocabulary of the
CapabilityClientfacade's non-throwing contract.StreamRunBodyis
RuntimeRunStartBodyplus the optional gateway session-selection fields
(sessionKey/session_key/session_id), so
client.streamRun({ input, sessionKey })typechecks at the call site. -
Added gateway
streamRunbridging so the facade's execution surface streams
on every provider: Hermes streams over SSE run events (the run body's
sessionKey— aStreamRunBodyfield — selects the session; without one the
call resolvesok: falsewith arequest-invalidgap and starts no run), and
OpenClaw streams over control-plane WebSocket event frames. The gateway bridge
is wired internally bycreateApiClient; consumers assembling their own facade
supply it through thestreamRunBridgeoption on
CreateCapabilityClientOptions. The reusable control-plane → run-stream
adaptercreateRunEventStreamFromControlPlane(and the underlying
createControlPlaneRunStreamTranslator) is exported from the./core/runtime
subpath.streamRunresolves aCapabilityResult<RunStreamOutcome>with
unified per-provider semantics:okreflects the streaming CALL and the
payload carries the run's own terminal state as data (runIdplus
outcome: "completed" | "failed" | "cancelled" | null), so a run that fails
as arun.failedEVENT still resolvesok: true. A stream torn down by a
transport error (even one swallowed intoonErrorwith no terminal) resolves
ok: falsewith a classified gap; a caller-initiated abort (via
options.signal) or a provider-internal AbortError resolvesok: falsewith
arequest-abortedgap and, when arunIdis known and the runtime exposes
cancelRun, issues a best-effortcancelRun(runId)so no gateway run is
orphaned (the gap note records whether a cancel was requested). -
ContractGapReasongainscapability-unsupported(an undeclared or unwired
capability),request-invalid(a caller mistake the transport can name before
any request is made), andrequest-aborted(a caller-initiated or
provider-internal abort of a streaming call). -
Added
inspectCapabilityClientConformanceunder the./testingsubpath —
probes everyCapabilityClientsurface (execution, control-plane, kanban,
teams, media, wiki, agentConfig, events) and reports which calls fail to
resolve.
Removed
- Breaking (
./providers/hermes): the four pure-config mirror classes —
HermesApiClient,HermesMediaApiClient,HermesWikiApiClient,
HermesWebSocketClient(and theHermesCapabilities/HermesRunStatus
type aliases). They injected only a surface tag and/or endpoint table into
the shared gateway bases; the provider module andcreateApiClientnow pass
that config toGatewayApiClient/GatewayMediaApiClient/
GatewayWikiApiClient/GatewayWebSocketClientdirectly. Runtime behavior
(including thehermes-*surface tags) is unchanged.
Changed
-
RUNTIME_PROVIDER_CAPABILITY_MATRIX(and the per-provider
*_RUNTIME_SUPPORTconsts) now derive fromPROVIDER_CAPABILITIES— the
single declaration site — via runtime-surface / control-plane-module
projections. Two declared values were corrected: OpenClawmedia/wikiare
nowtrue— RPC-backed platform capabilities (media via the core tts/talk
gateway methods; wiki via the first-party memory-wiki plugin'swiki.*
methods), with instance-level presence runtime-resolved from the hello-ok
method advertisement — and Hermes gainscontrolPlane.modules.workspace
(member workspace routes served via the CAVI control plugin, verified live).
The live-diagnose prober now classifies 2xxtext/htmlresponses as
spa-fallbackinstead oflive(the control-UI catch-all had made any GET
look served). -
Documented
RuntimeClientgetRun/cancelRun as three real semantics (omit,
server, sync-store) and namedGatewayApiClientas the gateway implementer
(ReactGatewayClient*remains WS-RPC context only). AlignedCLAUDE.md/
AGENTS.mdwith SynchronousRunStore behavior for Claude Messages and Gemini. -
Hermes and OpenClaw provider modules now expose
createClientalongside the
legacycreateApiClientalias. Providerteam-registry-configre-exports are
marked@deprecatedtoward@cavi-ai/api-client/extensions/cavi. -
Replaced the provider-heavy README with a concise, wiki-first,
provider-neutral entry point and moved exports, provider selection, Claude
integrations, development checks, and consumer verification into focused
linked documents. -
CapabilityClient(the unreleased single-client facade) is now fully
non-throwing: every accessor across every gated surface (sessions,
tasks,events,models,usage,authStatus,workspace,kanban,
teams,media,wiki,agentConfig) and the universal execution surface
(startRun/getRun/cancelRun/streamRun/batch) resolves a
CapabilityResult<T>—ok: falsecarries a structuredContractGapfor
unsupported capabilities and degraded backends, instead of throwing
CapabilityUnavailable. Auth (401/403) and unknown-classified errors still
throw.CapabilityClientno longer extendsRuntimeClient. The execution
surface is always present on every provider, gateways included. -
createApiClient("openclaw")now runs on a single shared WebSocket. The
wiring's socket is injected into the OpenClaw runtime client via its
rpcClientoption, sostartRun/getRun/cancelRunand the resolver,
control plane, kanban, media, andstreamRunevent stream all ride one
connection instead of two. ThestreamRunevent client and provider are
memoized per client, so N concurrent streams share one native socket listener
rather than constructing one event client per call. The wiring'sonDispose
is the SOLE owner of the shared socket's lifecycle (dispose()closes it
exactly once): the injected runtime client never closes it (GatewayApiClient
has nodispose), and the control-plane backend is now wired with
takeRpcOwnership: falseso it tears down only its own raw-gateway resources.
This keeps facadedispose()ordering correct — the control plane is disposed
first without touching the socket, thenonDisposeaborts in-flight
streamRuns cleanly (a clean abort, not an F1 connection-error gap) and closes
the one socket.
Fixed
- OpenClaw reconnect-gap detection is seeded from the socket's live connection
state at (re)attach. An event client subscribing to an already-open socket
missed the initialconnection.open, so its first reconnect was mistaken for
the initial connect and skipped thestream.gapmarker; it now correctly
emitsstream.reconnected(+ a conditionalstream.gap) on the first
post-attach reconnect.
Fixed
- OpenClaw
getTask/cancelTasknow send thetaskIdRPC parameter (not
id) thattasks.get/tasks.cancelrequire — consistent with the
method-specific param naming already used elsewhere (sessions.*→key). - OpenClaw model wire validation now allowlists the optional
api,
available, andinputc...
v0.12.0
Added
-
Added deterministic consumer snapshot tooling for release-candidate evidence.
It captures dirty tracked and intended untracked sources without private or
generated artifacts, emits a verified Git bundle plus path/mode/content
metadata, encodes untracked provenance in the immutable commit, preserves
original worktree status bytes, rejects capture races, and lets the consumer
verifier consume and independently re-derive that durable evidence directly.
Final evidence can pin the expected consumer origin/base, rejects private
workstation paths and agent/debug artifacts, and verifies the captured RC
dependency and lock without rewriting either file. -
Aligned Hermes runtime control with the live aiohttp API Server:
baseUrl
capability-probes/v1/capabilitiesand maps/v1/models,
/api/sessions/list, and/api/sessions/usage. The separate TUI dashboard
remains explicit, API-server-only clients do not claimgateway.raw, and an
existing run may opt into/v1/runs/{run_id}/eventsSSE without creating a
run. Unsupported auth, session mutations, cron-as-task, and workspace remain
typed unavailable. OpenClaw's owned default identity now matches the accepted
openclaw-control-ui; explicit consumer identity still wins.
API Server authentication resolves independently from explicit dashboard
credentials, and runtime disposal aborts all active API Server SSE streams
while suppressing post-dispose delivery. Naturally completed and failed
streams release their captured handlers immediately; later caller or runtime
disposal is harmless. -
Added opt-in, provider-neutral
RuntimeControlClientOptions.gatewayReconnect
with retryable-only bounded backoff for owned OpenClaw gateway lifecycles.
Concurrent connects share only their in-flight promise, later manual connects
invoke the transport again, and disposal cancels pending retries. Hermes
rejects the policy and post-close manual reconnect explicitly because its
fixed dashboard channel cannot be reconstructed safely. -
Added provider-neutral
RuntimeControlClientOptions.gatewayConnection,
composed from the existingGatewayRpcClientOptions, so owned OpenClaw
connections can receive mobile-safe identity, device signing, scopes,
protocol, timeout, request-limit, and redacted RPC-trace settings. Injected
transports retain precedence; Hermes rejects unsupported fields explicitly
instead of silently downgrading security configuration. -
Added the optional provider-neutral
GATEWAY_RAW_EXTENSION(gateway.raw)
contract for arbitrary operation requests, unchanged raw event snapshots,
normalized connection state, cancellation, and exact-once asynchronous
disposal. The descriptor does not claim provider support and remains distinct
from normalized runtime-control events and the CAVI-onlycavi.control
extension. -
Added shared
gateway.rawconformance for OpenClaw and Hermes covering
request and raw-event identity, listener isolation, ordered reconnect state,
abort propagation, typed unsupported operations, and exact-once disposal.
Published testing imports, compatibility evidence, and dependency guardrails
keep the suite provider-neutral; REST-only Hermes remains unsupported. -
Added the CAVI extension's provider-neutral
resolvePluginApiPathdispatcher
for generic/api/plugins/{plugin}/...routes and the
LIBRARY_LEGACY_API_BASE_PATHcompatibility constant for consumers that
normalize released/library/apiinputs. Portal dispatch and existing
library route behavior are unchanged. -
Added a provider-neutral runtime-control scenario catalog through the testing
subpath. It records typed capability unavailability, keeps live mutation
probes behind an explicit disposable mode and typed extension, cleans created
resources in reverse order, redacts failure details, and always reports client
disposal independently. -
Added a provider-neutral typed extension registry to
RuntimeControlClient.
Descriptors normalize IDs, registries reject blank or duplicate IDs and expose
immutable sorted discovery with descriptor-identity lookup, and repeated
withRuntimeControlExtensionscalls compose without shadowing existing or core
client properties while preserving module identity and delegating disposal
exactly once. -
Added the typed
CAVI_CONTROL_EXTENSION(cavi.control) descriptor. The CAVI
registry enhancer now installs independently constructed complete CAVI control
adapters for configured OpenClaw and Hermes providers while preserving their
released core modules, immutable base registries, and canonical alias checks. -
Added the CAVI-only
withCaviRuntimeControlProvidersregistry enhancer. It
immutably installs the resolved Hermes runtime-control factory while
preserving base modules, aliases, capabilities, resolution order, the root
capability matrix, and provider-neutral package-factory options. Canonical
Hermes identity now fails closed for missing, ambiguous, or alias-shadowed
registries; generic module types and defensive-copy registries are preserved,
and mutable extension setup is snapshotted without cloning opaque runtime
resources. -
Documented branch-free
RuntimeControlClientconsumption and the exact
Hermes/OpenClaw transport, REST fallback, event, authentication, lifecycle,
task, workspace, cost, and upstream protocol-ownership boundaries. The
Hermes session module requires both dashboard REST and a channel. An explicit
dashboard token suppresses authentication resolution and wins over the generic
token; otherwise a resolved authorization header wins, with the generic token
supplying bearer authorization when resolved headers contain no authentication.
Hermes session pagination preserves validated upstream totals, CAVI task
snapshots fail closed on malformed nested schemas, and task/workspace metadata
reports the adapter's actual WebSocket or HTTP transport without labeling
local fallback data as wire traffic. Blank resolved authorization values use
the generic bearer token, session cursors stop at the 200-row bound and do not
repeat when REST fallback cannot advance, and partial operator-section
fallbacks retain non-wire provenance. The
immutable generatedv0.11.0documentation remains historically accurate
and intentionally excludes these unreleased APIs. -
Added an OpenAI-style operation reference to the documentation pipeline
(rendered on cavi-ai.xyz): per-operation method signatures, request bodies,
responses, runnable examples, and the HTTP endpoint each operation maps to,
covering the universal runtime contract, every provider (Claude, Codex,
Gemini, Hermes, OpenClaw), Claude Managed Agents, the gateway control-plane and
WebSocket RPC surfaces, and the CAVI extension, plus a companion redundancy
audit that records removal candidates. A newdocs:checkstep
(scripts/docs/check-operation-endpoints.mjs) fails the build when a
documented HTTP path is not owned by apaths.tsfile.
Changed
- Extracted the core gateway session loaders behind an injectable,
provider-neutralGatewaySessionOperationsport. The default OpenClaw adapter
preserves the released pluralsessions.*RPC and REST fallback mappings,
payloads, caches, and one-argument loader calls without adding a CAVI copy.
Optional request options now propagate through every session operation;
already-aborted signals prevent legacy transport dispatch, while in-flight
cancellation remains unsupported by those released transports. - Extended the additive gateway session operation seam with optional typed
cancellation and provider-neutral raw creation/update/state fields. Canonical
session methods now share abortable request option types; providers without
proven cancellation semantics keep the optional operation absent. - Directly renamed the unreleased canonical facade, factories, provider hook,
and conformance kit to theRuntimeControlClientvocabulary. This is a
pre-release rename, not a compatibility removal; the older released
RuntimeControlPlanedeclaration API remains intact. - Reduced
API.mdto an index that points at the pipeline operation reference;
its former control-plane facade and OpenClaw adapter prose moved into the
operation pages, and thedocs-integritycontract now verifies them there.
Renamed the Claude provider reference page toclaude-anthropic.mdto avoid a
CLAUDE.mdcase collision on case-insensitive filesystems.
Fixed
- OpenClaw canonical session summaries now preserve the upstream preferred
title, using an explicit session label before the derived display name for
both list and get operations. - Aligned OpenClaw control-plane validation with current upstream
sessions.listpagination/default metadata,usage.costcost-detail and
cache-status fields, andagents.listruntime/thinking metadata while
retaining fail-closed nested validation, including current session label and
display-name fields. Current OpenClaw session pagination now follows validated
continuation metadata without truncating later pages.
Already-aborted OpenClaw requests no longer dispatch a hidden RPC that rejects
during disposal, Hermes API Server requests preserve caller abort identity
without dispatching fetch, and late caller cancellation no longer masks an
unrelated HTTP transport failure or a timeout that already won the combined
abort race. - Made Hermes runtime-control composition independent per configured surface:
CAVI task/workspace adapters now install without dashboard REST, while absent
dashboard modules remain exact unavailable facades. Construction now unwinds
owned channels and RPC resources in reverse order, including readiness,
synchronous subscription, and post-construction abort failures, without
closing borrowed channels or replacing the primary error. - Added the current
/cavi-control/api/cost/history...