v0.13.0

Liveness RPC wrappers for the chat-liveness redesign:

• agentWait(runId, { timeoutMs? }) — wraps agent.wait, the gateway's authoritative run-liveness oracle (AgentWaitResult).
• sessions.describe(key, { agentId? }) — wraps sessions.describe (SessionDescribeResult).
• sessions.subscribeMessages(key, handler, { agentId? }) — subscribes to a session's live event stream (assistant deltas, transcript snapshots, lifecycle), returns { unsubscribe }. Canonical-key-safe filtering, listener registered before subscribe, best-effort teardown.

Additive, no breaking changes. (#32)

v0.12.1 — reject in-flight requests on disconnect

Fixed

• In-flight requests now reject immediately when the connection drops, instead of stalling until the 30 s request timeout. When the Gateway restarts (e.g. its first-time secrets-bootstrap restart) while a config.get/config.apply (or any RPC) is awaiting its response, the WebSocket closes with the request still pending. Previously it was orphaned and only failed after 30 s; across a storm of config pushes those stalls compounded so a freshly-created agent's config could fail to reach OpenClaw's runtime within the caller's retry budget, leaving chat dispatch stuck on unknown agent id (root cause of heypinchy/pinchy#464). Both close and error handlers now reject every pending request with an error containing Not connected to OpenClaw Gateway, so callers recognize a disconnect and retry the moment the Gateway is back.

v0.12.0 — agents.list() runtime readiness signal

Added

• client.agents.list() wraps the Gateway's agents.list RPC and returns the runtime agent list. The Gateway derives this from the same getRuntimeConfig() view its chat-dispatch handler checks before accepting a message, so it is the authoritative readiness signal: once an agent id appears here, a chat/agent dispatch for that id will not be rejected with unknown agent id. Distinct from config.get(), which reads the config FILE and can lead the applied runtime by seconds-to-minutes.
• New exported types AgentsListResult, AgentSummary, AgentIdentity.

openclaw-node 0.11.0

Expose Gateway-correlated runId on ChatChunk

The Gateway already tags every event payload with runId (and openclaw-node has been filtering on it internally for a while); this release forwards it to consumers as a required field on every ChatChunk variant — text, tool_use, tool_result, done, error, agent_start, agent_end, userMessagePersisted.

The motivating use case is Pinchy's Tier 2 streaming-resume work for heypinchy/pinchy#310: the server needs the OC-correlated runId to route mid-stream events to the right ActiveRun across a Browser ↔ Pinchy WebSocket disconnect+reconnect, where the Pinchy ↔ OC stream lives on but the originating browser session has flipped to a new socket.

For runs that error before the Gateway sends an accepted response, openclaw-node falls back to runId === requestId (the Gateway's own contract for fresh runs), so error chunks always carry a usable id.

Breaking (TypeScript only)

• ChatChunk variants now require runId: string. The change is purely additive at runtime — no chunk shape changed semantics — but any code that constructs ChatChunk literals (mocks, tests, middleware) will need to add the field. Consumers that only read chunks from client.chat() need no code changes other than picking up the new typings.

Compatibility

• Wire protocol unchanged. Compatible with the same Gateway versions as 0.10.0 (OC ≥ 2026.5.12).

openclaw-node 0.10.0

Gateway protocol v4

OC 2026.5.12 raised MIN_CLIENT_PROTOCOL_VERSION from 3 to 4 (upstream PR #80725, "require v4 clients and stream explicit deltaText/replace frames"). Gateways at 2026.5.12+ close v3 clients with code 1002 (protocol mismatch ... min=3 max=3 expected=4 probeMin=4) before the handshake completes.

This release advertises minProtocol: 4 / maxProtocol: 4 in the connect frame so openclaw-node can connect to current Gateway releases.

Breaking

• No longer compatible with OC <= 2026.5.7. Stay on openclaw-node@0.9.0 if you need to talk to older Gateways.

Security

• Bump ws dependency range to ^8.20.1 to pick up GHSA-58qx-3vcg-4xpx.

Compatibility notes

• Wire-level chat streaming is unchanged: OC 2026.5.18 still broadcasts the legacy event: "agent" payload (stream: "assistant", data.delta / data.text) alongside the new event: "chat" v4 payload, so the existing assistant-text chunk handler keeps working.

See PR #28 for full details.

v0.9.0 — ChatOptions provider/model overrides

Added

• `ChatOptions.provider` / `ChatOptions.model` overrides forwarded to the Gateway's `agent` RPC. When set together, the Gateway's vision-capability check resolves against the explicit pair instead of falling back to its default model.

Why

The Gateway resolves the session model with `resolveSessionModelRef(cfg, entry, undefined)` inside its `agent` RPC — `agentId` is hard-coded to `undefined`, so the lookup falls back to the gateway-wide default. That breaks the vision-capability check for image attachments on per-agent vision-capable models: the wrong (often non-vision) default is consulted and the upload is rejected with `UnsupportedAttachmentError: active model does not accept image inputs`.

Callers that know which provider/model their agent runs on should now set both fields so the Gateway sees the real pair.

Compatibility

• Backwards-compatible: omitting both fields preserves the existing behavior.
• Forward-compatible with a future Gateway-side fix that honours `agentId` directly inside `server-methods`.

See PR #25 and the CHANGELOG for details.

v0.8.0

See CHANGELOG.md

v0.7.0 — Remove continueLastTurn (BREAKING)

Removed

• BREAKING: continueLastTurn({ sessionKey }) is gone. The method was designed to send an agent request without a message field so the OpenClaw Gateway would re-run from existing session history, but OpenClaw's AgentParamsSchema requires message: NonEmptyString — so the call was rejected by every recent gateway version ("must have required property 'message'"). The method had no working call site since it was added in 0.5.0.

Migration

The supported retry pattern is to resend the user's last message via chat() — that's what the gateway's protocol was always designed for. Pinchy already does this client-side, so for the primary consumer this removal is a net cleanup with no behavior change.

If you have code calling continueLastTurn, replace it:

// Before
for await (const chunk of client.continueLastTurn({ sessionKey })) { ... }

// After
for await (const chunk of client.chat(lastUserMessageContent, { sessionKey })) { ... }

Compatibility

Breaking for direct consumers of continueLastTurn. No behavior change for chat() callers.

v0.6.0

Added

• New chunk types agent_start and agent_end for per-run lifecycle boundaries (optional, useful for progress indicators)
• JSDoc on ChatChunk union type describing all chunk semantics

Fixed

• Provider errors (401, quota, rate limits) from OpenClaw's lifecycle events now surface as {type: "error"} chunks. Previously silently dropped — see heypinchy/pinchy#152.
• Error chunks are deduplicated when both the lifecycle path and the res.ok: false path fire for the same run (first-wins, lifecycle error carries the more specific provider text)

Removed

• Unused ChatMessage interface (dead code)

Compatibility

Non-breaking at runtime. TypeScript consumers with exhaustive switches on ChatChunk.type should add cases for agent_start and agent_end.

v0.5.0

[0.5.0] - 2026-04-23

Added

• clientMessageId option on chat() — when provided, yields a userMessagePersisted chunk after the Gateway acknowledges receipt of the user message (before the first assistant chunk). Useful for delivery-status tracking.
• continueLastTurn({ sessionKey }) method — re-triggers the assistant response for the last user message in the session without appending a new user message. Useful for retry flows.

Fixed

• All test files now use isolated tmpDir for device identity (previously relied on ~/.openclaw which fails in sandboxed environments)