v0.2.0 — Public Preview

Released 2026-05-14. xtrape-capsule-ce@v0.2.0 is tagged and the Docker image is published on GHCR; @xtrape/capsule-contracts-node@0.2.0 and @xtrape/capsule-agent-node@0.2.0 are on npm latest.

The first stable Public Preview of Xtrape Capsule. Theme: Developer Experience & Runtime Maturity. No new product surfaces — the existing CE + Agent SDK + Contracts trio gets the operational and ergonomic polish needed for small private deployments and friendly public adoption.

Highlights

• Effective status in real time. Services display the correct HEALTHY / UNHEALTHY / STALE / OFFLINE value within seconds of an agent going offline, instead of waiting up to one maintenance sweep (default 60s).
• System endpoints match the contract. /api/system/health now includes a SQLite round-trip probe, uptime, version, and edition; /api/system/version reports build-time version, commit, and build timestamp baked into the Docker image as OCI labels.
• Typed errors in the Node Agent SDK. RegistrationError, AgentAuthError, NetworkError — operator-action-required failures surface immediately instead of being retried into the backoff window, and consumers can instanceof-branch instead of parsing messages.
• Command failure reasons surface on the row. When an agent reports success: false, the command's errorCode and errorMessage are written to the commands row directly, not just the command_results body. List endpoints and the UI now show why a command failed without an extra join.
• durationMs on every completed command. Computed at serialize time; UI can render "succeeded in 1.2s" without a second timestamp parse.
• Heartbeat write volume cut. The heartbeat handler now updates agents.status only on the OFFLINE → ONLINE transition; freshness uses lastHeartbeatAt alone.
• Agent token rotation on re-register. A repeat registration of an existing agent immediately revokes prior ACTIVE tokens (was: left them ACTIVE — operator had to explicitly Revoke Agent first).
• Audit metadata redactor split. A second helper (redactAuditMetadata, value-based) replaces the key-based one inside writeAudit; legitimate field names like revokedTokens no longer get clobbered to "[REDACTED]".

Compatibility

Package	Version	Distribution
xtrape-capsule-ce	0.2.0	GHCR ghcr.io/xtrape-com/xtrape-capsule-ce:0.2.0 (semver) + :0.2 (minor alias)
@xtrape/capsule-agent-node	0.2.0	npm latest
@xtrape/capsule-contracts-node	0.2.0	npm latest
xtrape-capsule-demo	0.2.0	source clone; tracks the same 0.2.x minor

Pin matching minors across the published packages. See Version Compatibility for the live matrix and upgrade guidance. The CE Docker workflow does not publish a latest tag — operators should always pin to a semver tag for reproducible deployments.

Breaking changes vs 0.1.x

The v0.2 cut does not remove any wire-level fields; existing 0.1.x agents will keep working against a 0.2.0 backend. But some surfaces tightened:

• @xtrape/capsule-contracts-node: newId(), idPrefixes, and IdPrefix are removed. Consumers that minted local IDs from this helper must wire their own factory (the wire spec only requires the documented prefix via z.string().startsWith(...)).
• Command.type no longer accepts the legacy bare "ACTION" literal; only "ACTION_PREPARE" and "ACTION_EXECUTE".
• RegisterAgentRequest.agent.runtime is now the same RuntimeKind enum as service.runtime (nodejs | java | python | go | other) rather than a free string.
• @xtrape/capsule-agent-node retry logic changed: 4xx errors (including registration/auth failures) throw immediately instead of burning the retry budget. Existing code that expected the SDK to "eventually give up" still works; existing code that swallowed AgentApiError without distinguishing causes will now see those failures earlier.

What's included

Component	Distribution
Opstage CE backend + UI	ghcr.io/xtrape-com/xtrape-capsule-ce:0.2.0 + :0.2 (semver + minor alias)
Node Embedded Agent SDK	npm latest — @xtrape/capsule-agent-node@0.2.0
Contracts (Zod + TS)	npm latest — @xtrape/capsule-contracts-node@0.2.0; helpers slimmed
Public site + docs	Live on this site; new troubleshooting + version-compatibility pages

Not included in v0.2

The following appear on the v0.2 roadmap bullet list but are deferred to v0.3 rather than shipping in this cut:

• Improved quick-start docs. The getting-started/ pages on this site are unchanged from v0.1.
• Empty-state / error-message / audit-filter UI polish.
• CE issue #13 (route UI apiList through apiFetch).
• latest Docker tag. The CE workflow intentionally does not publish latest. Install docs pin to 0.2.0.

Known limitations

Unchanged from v0.1:

• Single-node only. HA / clustering belongs to a future Enterprise Edition.
• No SSO / SCIM / org-level RBAC.
• Public-internet exposure is not recommended without an additional hardening layer (VPN / reverse proxy with SSO / IP allow-list).

New caveats from v0.2:

• No real product screenshots in docs yet; placeholders only.
• zh-CN translation tracked but not delivered in this cut.

Cross-cutting issues addressed

• xtrape-capsule-ce #11, #12, #14, #15 (#13 deferred to v0.3)
• xtrape-capsule-contracts-node #8
• Agent SDK retry classification + typed errors

Going forward

See the roadmap for v0.3 OpHub Runtime, Capsule Events and Capability Metadata. v0.2 deliberately holds the embedded-agent surface stable so the next milestone can layer OpHub-managed service integration cleanly.