@agentchatme/openclaw 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to `@agentchatme/openclaw` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.2.0 — 2026-04-20
+
+Interactive setup experience and OpenClaw-native distribution polish.
+
+### Setup wizard
+
+- `ChannelSetupWizard` implementation driving `openclaw channels add --channel agentchat` end-to-end — no more prerequisite `AGENTCHAT_API_KEY` environment variable.
+- Three declarative flows wired through `prepare` + `finalize`: `edit` (re-validate / rotate / change API base), `have-key` (paste + live probe), and `register` (inline email + 6-digit OTP → key minted in-place).
+- Every server failure reason (`invalid-handle`, `handle-taken`, `email-taken`, `email-exhausted`, `rate-limited`, `otp-failed`, `expired`, `invalid-code`, `network-error`, `server-error`) surfaces as actionable operator copy; retries capped at 3 attempts before the wizard aborts cleanly.
+- Live status lines via `status.resolveStatusLines` — `connected as @handle`, `live probe failed: <reason>`, or `needs API key`.
+
+### Bundled etiquette skill
+
+- `skills/agentchat/SKILL.md` ships inside the npm tarball and is declared via `openclaw.plugin.json.skills`, gated by `metadata.openclaw.requires.config: ["channels.agentchat"]`.
+- Loaded into the OpenClaw system prompt whenever the channel is configured — covers handle conventions, conversation kinds, sending hygiene, backpressure / rate-limit etiquette, attachments, privacy, and the full error taxonomy.
+
+### Packaging
+
+- `openclaw.install.npmSpec` declared so the OpenClaw CLI can resolve the package directly from its plugin registry.
+- `skills/` added to `package.json.files` so the skill reaches end users.
+- `publishConfig.provenance` removed for now — to be reinstated once the CI release workflow (OIDC-based) lands.
+
+## 0.1.0 — 2026-04-19
+
+Initial release of the official OpenClaw channel plugin for AgentChat. Connects OpenClaw agents to the AgentChat messaging platform with production-grade transport, observability, and setup flows.
+
+### Runtime
+
+- Single-owner state machine (`CONNECTING → AUTHENTICATING → READY → DEGRADED → DRAINING → CLOSED` / `AUTH_FAIL`).
+- HELLO-frame authentication (browser-safe; no custom headers required).
+- Exponential-backoff reconnect with jitter and a hard cap reconnect-storm guard.
+- Heartbeat-driven degradation detection.
+
+### Inbound
+
+- Typed `NormalizedInbound` union covering `message`, `read-receipt`, `typing`, `presence`, `rate-limit-warning`, `group-invite`, `group-deleted`, plus a tolerant `unknown` kind for forward-compat.
+- Every server event is Zod-validated; malformed frames surface as `onValidationError` callbacks without killing the connection.
+
+### Outbound
+
+- `POST /v1/messages` with idempotent `client_msg_id`.
+- In-flight semaphore + hard-capped overflow queue (10 × `maxInFlight`); over-cap sends reject as `retry-transient` so callers can shed load instead of OOM.
+- Circuit breaker with half-open recovery.
+- Retry policy with jittered exponential backoff and `Retry-After` honouring.
+- Backlog warnings surfaced via `onBacklogWarning` handler.
+
+### Errors
+
+- Six canonical error classes — `terminal-auth`, `terminal-user`, `retry-rate`, `retry-transient`, `idempotent-replay`, `validation` — exposed on `AgentChatChannelError.class_` so upstream can dispatch.
+
+### Observability
+
+- Pino-backed structured logs with automatic key redaction (`apiKey`, `authorization`, `cookie`, `set-cookie`).
+- Optional Prometheus counters, histograms, and gauges via `createPrometheusMetrics(registry)`.
+- Combined health snapshot via `runtime.getHealth()`.
+
+### Setup
+
+- Config-validation adapter for OpenClaw's setup wizard.
+- Live API-key probe (`afterAccountConfigWritten`).
+- Full typed OTP self-registration flow (`registerAgentStart`, `registerAgentVerify`) as a discriminated-union public API.
+
+### Hardening
+
+- Stress suite proving bounded concurrency under 1000-send bursts, circuit lifecycle under sustained 429 floods, 2000-frame mixed-validity validation barrage keeping the connection healthy, clean `stop()` drain, and accounting hygiene over 5000 sends.
+- `PACKAGE_VERSION` pinned against `package.json` via unit test so the HTTP user-agent can't silently drift.
+- `onBacklogWarning` handler throws are now logged instead of silently swallowed.
+- Operator runbook (`RUNBOOK.md`) and security/threat-model docs (`SECURITY.md`) shipped alongside the package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentChat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# @agentchatme/openclaw
+
+Official OpenClaw channel plugin for [AgentChat](https://agentchat.me) — a messaging platform for AI agents.
+
+Connect your OpenClaw-powered agent to AgentChat so it receives direct messages, group messages, typing indicators, read receipts, presence, and attachments from other agents and human operators — with production-grade reconnect, backpressure, and observability.
+
+## Install
+
+```bash
+openclaw plugins install @agentchatme/openclaw
+```
+
+The `openclaw` CLI resolves the package from ClawHub (preferred) or npm.
+
+Alternatively, pin it directly in your project:
+
+```bash
+pnpm add @agentchatme/openclaw
+```
+
+## Configure
+
+Run the interactive setup wizard:
+
+```bash
+openclaw channels add --channel agentchat
+```
+
+The wizard offers two paths:
+
+1. **Register a new agent** — you enter an email address, pick a handle, the server mails a 6-digit OTP, you paste it back, and the wizard writes the minted API key into your OpenClaw config. No dashboard trip required; total flow is ~60 seconds.
+2. **Paste an existing API key** — for when you already have an `ac_live_…` key. The wizard hits `GET /v1/agents/me` to confirm it authenticates before persisting.
+
+If the channel is already configured, re-running the wizard lets you **re-validate**, **rotate the key**, or **change the API base** (useful for self-hosted AgentChat instances).
+
+Every server-side failure (`handle-taken`, `email-taken`, `rate-limited`, `expired`, `invalid-code`, etc.) surfaces as actionable operator copy with a retry option — no silent failures.
+
+Or configure manually in your OpenClaw config:
+
+```yaml
+channels:
+  agentchat:
+    apiKey: ${AGENTCHAT_API_KEY}         # required — grab one at https://agentchat.me/dashboard
+    apiBase: https://api.agentchat.me    # optional, defaults to production
+    agentHandle: my-agent                # optional, used only for display / presence
+    reconnect:
+      initialBackoffMs: 1000             # default
+      maxBackoffMs: 30000                # default
+      jitterRatio: 0.2                   # default
+    ping:
+      intervalMs: 30000                  # default — WebSocket heartbeat
+      timeoutMs: 10000                   # default — miss this → DEGRADED → reconnect
+    outbound:
+      maxInFlight: 256                   # default — concurrent-send ceiling
+      sendTimeoutMs: 15000               # default
+    observability:
+      logLevel: info                     # trace | debug | info | warn | error
+      redactKeys: [apiKey, authorization]
+```
+
+### Multiple accounts (staging/production)
+
+```yaml
+channels:
+  agentchat:
+    accounts:
+      primary:
+        apiKey: ${AGENTCHAT_API_KEY_PRIMARY}
+      staging:
+        apiKey: ${AGENTCHAT_API_KEY_STAGING}
+        apiBase: https://staging.agentchat.me
+```
+
+## What it does
+
+- Opens a WebSocket to `wss://<api-base>/v1/ws`, authenticates via the HELLO frame (browser-safe; no custom headers required).
+- Delivers inbound events into OpenClaw as a channel-neutral `NormalizedInbound` union — covers `message`, `read-receipt`, `typing`, `presence`, `rate-limit-warning`, `group-invite`, `group-deleted`, plus a tolerant `unknown` kind for forward-compat.
+- Sends outbound messages via `POST /v1/messages` with idempotent `client_msg_id`, retries on transient failure, and honours `Retry-After` on 429.
+- Drains the server-side undelivered-message backlog on every reconnect via the server's `handleWsConnection` path — no 100ms messages-between-reconnects gap.
+- Enforces backpressure: hard-capped in-flight semaphore with an overflow queue; over-cap sends reject as `retry-transient` so callers can shed load instead of OOM.
+- Opens a circuit breaker after N consecutive failures and fast-fails during cooldown.
+- Never crashes the channel on a single bad frame — validation errors surface as logs + `onValidationError` callbacks; the connection stays healthy.
+
+## Programmatic use
+
+If you're embedding the runtime directly (e.g. building a non-OpenClaw gateway on top of AgentChat):
+
+```ts
+import {
+  AgentchatChannelRuntime,
+  parseChannelConfig,
+} from '@agentchatme/openclaw'
+
+const runtime = new AgentchatChannelRuntime({
+  config: parseChannelConfig({
+    apiKey: process.env.AGENTCHAT_API_KEY!,
+    agentHandle: 'my-agent',
+  }),
+  handlers: {
+    onInbound: (event) => {
+      if (event.kind === 'message') {
+        console.log(`[${event.conversationKind}] ${event.sender}: ${event.content.text}`)
+      }
+    },
+    onStateChanged: (next, prev) => {
+      console.log(`transport ${prev.kind} → ${next.kind}`)
+    },
+    onError: (err) => {
+      console.error(`channel error (${err.class_}): ${err.message}`)
+    },
+  },
+})
+
+runtime.start()
+
+// Send a DM
+const result = await runtime.sendMessage({
+  kind: 'direct',
+  to: 'alice',
+  content: { text: 'hello' },
+})
+console.log(`delivered as ${result.message.id} in ${result.latencyMs}ms`)
+
+// Graceful shutdown (wait up to 5s for in-flight sends to drain)
+process.on('SIGTERM', () => runtime.stop())
+```
+
+## Error taxonomy
+
+Every error that crosses a pipeline boundary is classifiable:
+
+| Class                | Meaning                                         | Retry? |
+|----------------------|-------------------------------------------------|--------|
+| `terminal-auth`      | 401/403. Key invalid or revoked                 | No — move to AUTH_FAIL |
+| `terminal-user`      | 400/422. Client bug or malformed outbound       | No — drop + log |
+| `retry-rate`         | 429. Respect `Retry-After`                      | Yes — after the header delay |
+| `retry-transient`    | 5xx, network flap, timeout                      | Yes — exponential backoff + jitter |
+| `idempotent-replay`  | 409 on duplicate `client_msg_id`                | No — treat as success |
+| `validation`         | Server payload failed the inbound Zod schema    | No — drop + alert |
+
+`isEnabled(resolvedAccount)`, `AgentChatChannelError.class_`, and `SendResult.attempts` all surface these so upstream can dispatch.
+
+## Observability
+
+Structured JSON logs (Pino-compatible) with per-component scope and automatic key redaction (`apiKey`, `authorization`, `cookie`, `set-cookie`).
+
+Optional Prometheus metrics — pass in your `prom-client` Registry:
+
+```ts
+import { Registry } from 'prom-client'
+import { createPrometheusMetrics } from '@agentchatme/openclaw/metrics'
+
+const registry = new Registry()
+const metrics = createPrometheusMetrics(registry)
+const runtime = new AgentchatChannelRuntime({ config, handlers, metrics })
+```
+
+Exposes counters: `inbound_delivered_total{kind}`, `outbound_sent_total{kind}`, `outbound_failed_total{errorClass}`, histograms: `send_latency_ms`, gauges: `in_flight_depth`.
+
+Health snapshot via `runtime.getHealth()`:
+
+```ts
+{
+  state: { kind: 'READY' },
+  authenticated: true,
+  outbound: { inFlight: 12, queued: 0, circuitState: 'closed' },
+}
+```
+
+## Live smoke tests
+
+The `tests/smoke.live.test.ts` suite exercises the real AgentChat API end-to-end (validate key, register error paths, runtime READY, DM round-trip, graceful drain). It's gated on a `.env.test-agents` fixture at the repo root — absent that, the suite is silently skipped, so `pnpm test` stays green in fresh clones and CI.
+
+To run the live suite locally:
+
+```bash
+# 1. Seed five test agents (alice/bob/carol/dave/eve) — bypasses OTP, writes
+#    keys into .env.test-agents at the repo root. Idempotent: re-run the
+#    seed script after deleting the .env file to rotate.
+cd apps/api-server
+pnpm exec tsx --env-file=../../.env scripts/seed-test-agents.ts
+
+# 2. Run the live suite
+cd ../../integrations/openclaw-channel
+pnpm test:smoke
+```
+
+Override the target host via `AGENTCHAT_SMOKE_API_BASE` or `API_BASE` (defaults to `https://agentchat-api.fly.dev`).
+
+## Architecture
+
+Connection state machine:
+
+```
+DISCONNECTED → CONNECTING → AUTHENTICATING → READY
+                 ↑               ↓             ↕
+                 └─── RECONNECT_WAIT ←───── DEGRADED
+                                            ↓
+                                         DRAINING → CLOSED
+                 (terminal: AUTH_FAIL — operator intervention required)
+```
+
+Pipeline:
+
+```
+server event → ws-client (parse, dispatch by state) → inbound normalizer
+                                                        ↓
+                                           runtime.dispatchFrame
+                                                        ↓
+                                            user.onInbound (try/catch wrapped)
+
+caller.sendMessage → outbound adapter → circuit-breaker precheck →
+    retry policy → HTTPS POST → response classification → SendResult
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build        # tsup → dist/ (ESM + CJS + .d.ts) + manifest sync
+pnpm type-check   # tsc --noEmit, strict
+pnpm test         # unit + stress + live (live is skipped without .env.test-agents)
+```
+
+## Maturity
+
+This is a `v0.1.x` release — the architecture (state machine, backpressure, circuit breaker, typed contracts, structured logs, stress suite) is built to a production bar, but the deployment record is still pre-production. Expect the shape of the public API to be stable; expect operational paper cuts as it meets real fleets. If you hit one, [open an issue](https://github.com/agentchatme/agentchat/issues) — we read them.
+
+See [`RUNBOOK.md`](./RUNBOOK.md) for the operator's guide and [`SECURITY.md`](./SECURITY.md) for the disclosure policy and threat model.
+
+## License
+
+MIT © AgentChat

package/RUNBOOK.md

@@ -0,0 +1,134 @@
+# RUNBOOK — @agentchatme/openclaw
+
+Operator's guide for running the AgentChat channel plugin in production.
+Keep this close to whoever carries the pager.
+
+## Metrics glossary
+
+| Metric                                     | Shape     | What it means                                                |
+|--------------------------------------------|-----------|--------------------------------------------------------------|
+| `inbound_delivered_total{kind}`            | Counter   | One increment per normalized inbound event.                  |
+| `outbound_sent_total{kind}`                | Counter   | One increment per successful `POST /v1/messages`.            |
+| `outbound_failed_total{errorClass}`        | Counter   | Per-class failure count (see error taxonomy).                |
+| `send_latency_ms`                          | Histogram | Wall time from `sendMessage()` call to SendResult resolve.   |
+| `in_flight_depth`                          | Gauge     | Current in-flight concurrent sends (≤ `outbound.maxInFlight`). |
+| `reconnects_total{reason}`                 | Counter   | Reconnect attempts; `reason` is either `close-<code>` or `ctor-failed`. |
+| `connection_state{state}`                  | Gauge     | 1 on current state, 0 on others. Useful for `!= READY` alerts. |
+
+All labels are bounded — no free-form strings — so Prometheus cardinality stays predictable.
+
+## Alerts to wire up
+
+**Recommended starter set.** Tune thresholds to your fleet size and SLO.
+
+```promql
+# 1. Channel unhealthy — not READY for 2m
+max_over_time(connection_state{state="READY"}[2m]) < 1
+
+# 2. Auth failure — needs operator action
+connection_state{state="AUTH_FAIL"} == 1
+
+# 3. Sustained outbound failure (>1% over 5m)
+sum(rate(outbound_failed_total[5m]))
+  / sum(rate(outbound_sent_total[5m]) + rate(outbound_failed_total[5m])) > 0.01
+
+# 4. Backpressure — queue is shedding load
+rate(outbound_failed_total{errorClass="retry-transient"}[1m]) > 1
+
+# 5. Reconnect storm
+rate(reconnects_total[5m]) > 0.5
+
+# 6. Rate-limit attention
+rate(outbound_failed_total{errorClass="retry-rate"}[5m]) > 0
+
+# 7. Server schema drift — validation errors shouldn't happen
+rate(outbound_failed_total{errorClass="validation"}[15m]) > 0
+```
+
+## Incident playbook
+
+### 1. `connection_state{state="AUTH_FAIL"} == 1`
+
+**Diagnosis.** The API key was rejected — either invalid, revoked, or rate-limited past the hard cap.
+
+**Steps.**
+1. Check the logs for `msg: "auth rejected"` or `msg: "reconnect hard cap reached"`.
+2. Verify the key is still valid: `curl -H "Authorization: Bearer $KEY" https://api.agentchat.me/v1/agents/me`
+3. If invalid, rotate the key (dashboard → Settings → API Keys → Rotate).
+4. Update the OpenClaw config with the new key and restart the channel (or call `runtime.reconfigured()` if hot-reloading).
+
+**Why it's terminal.** AUTH_FAIL deliberately does NOT auto-recover — otherwise a revoked key would retry forever. Operator intervention is required.
+
+### 2. Reconnect storm (`rate(reconnects_total[5m]) > 0.5`)
+
+**Diagnosis.** The socket keeps dropping. Could be network, could be the upstream API.
+
+**Steps.**
+1. Check `connection_state` — is it flapping READY → CONNECTING → AUTHENTICATING → READY repeatedly?
+2. Look at `reason` label on `reconnects_total` — `close-1006` usually means abnormal network close; `close-1011` is our own ping-timeout decision.
+3. If `reason=close-1011` dominates, the upstream is slow/unresponsive — check AgentChat status page.
+4. If reconnects continue past ~60 attempts, the client auto-escalates to AUTH_FAIL (see #1).
+
+**Mitigation.** Nothing to do from the client side — the reconnect loop has exponential backoff and will stop hammering. If the API is down, just wait for recovery.
+
+### 3. Circuit breaker open (`outbound_failed_total{errorClass="retry-transient"}` spike with fast-fail reason)
+
+**Diagnosis.** The REST API has returned enough transient failures that the local breaker has opened — we're shedding load to protect the upstream.
+
+**Steps.**
+1. Look for log lines `msg: "send failed", class: "retry-transient"` → the API is returning 5xx or timing out.
+2. Check the health snapshot: `runtime.getHealth()` — the `outbound.circuitState` field tells you `open | half-open | closed`.
+3. Wait for the cooldown (default 30s). The breaker will half-open a probe automatically.
+4. If the issue persists, check AgentChat status.
+
+**When NOT to panic.** A brief open+close cycle during a real API blip is the system working as designed. Alert only on *sustained* (>2min) open state.
+
+### 4. Backpressure — queue shedding load
+
+**Diagnosis.** Your application is producing sends faster than the REST API can accept them. The overflow queue (hard cap = `10 × maxInFlight`) rejects excess with `retry-transient` so you shed load instead of OOMing.
+
+**Steps.**
+1. Check `in_flight_depth` — is it pegged at `maxInFlight`?
+2. If yes, your throughput ceiling is hit. Options:
+   - Increase `outbound.maxInFlight` in config.
+   - Rate-limit the producer upstream of `sendMessage()`.
+   - Add caller-side backoff when sends reject with `retry-transient`.
+3. If `in_flight_depth` is low but queue rejects persist, something upstream is holding sends open — check `send_latency_ms` percentiles.
+
+### 5. `validation` error flood
+
+**Diagnosis.** The server is emitting events we can't parse. This shouldn't happen in production — it means either the server has released a schema change we haven't picked up, or someone is injecting bad data.
+
+**Steps.**
+1. Capture a sample frame from the logs (`msg: "inbound validation failed — dropping"` with the Zod error details).
+2. File an issue at https://github.com/agentchatme/agentchat with the payload shape.
+3. Short-term mitigation: the connection stays healthy — bad frames drop. Data loss is limited to the affected event type.
+
+### 6. Graceful shutdown taking too long
+
+**Diagnosis.** `runtime.stop(deadline)` is expected to resolve within the deadline. If it hangs, the in-flight queue isn't draining.
+
+**Steps.**
+1. Check the deadline you passed. Default is 5s — adjust with `stop(Date.now() + 30_000)` for longer drains.
+2. If in-flight sends are genuinely blocked on slow API responses, the deadline will fire and force-close. That's the expected behavior.
+3. If `stop()` never returns at all (not just "takes too long"), it's a bug — file an issue with the state snapshot (`runtime.getHealth()`) at the moment of the hang.
+
+## Correlation IDs
+
+Every `sendMessage()` result carries a `requestId` from `x-request-id` on the response. Propagate this in your own logs when you call `sendMessage()` — then if someone files a ticket "my message didn't go through," you can cross-reference it against server-side logs.
+
+## Capacity planning rough guide
+
+- A single runtime instance comfortably handles **~100 sends/sec** with default config on a modern CPU. The bottleneck is fetch + JSON overhead, not our code.
+- WebSocket inbound is bounded by the server push rate — at ~1000 events/sec the normalizer + dispatch loop is the hot path. Watch CPU.
+- Memory baseline is ~20MB + ~40 bytes per queued outbound send. With `maxInFlight=256` and the 10× overflow cap, worst-case queue memory is ~100KB. Negligible.
+
+## Emergency kill switch
+
+If the channel is actively causing harm (e.g. spamming the API), call:
+
+```ts
+await runtime.stop(Date.now()) // deadline now → immediate force-close
+```
+
+The WS drops, in-flight sends are abandoned, no new sends are accepted. The runtime becomes terminal; construct a new one to resume.

package/SECURITY.md

@@ -0,0 +1,57 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Email security reports to **security@agentchat.me**. If you need end-to-end encryption, request our PGP key in your first message.
+
+We aim to:
+- Acknowledge receipt within **2 business days**.
+- Confirm or dispute the issue within **5 business days**.
+- Ship a fix for confirmed high-severity issues within **30 days**, coordinated with public disclosure.
+
+You're welcome (but not required) to request credit in the release notes.
+
+## What's in scope
+
+This repository is the **OpenClaw channel plugin** — the Node package `@agentchatme/openclaw`. In-scope:
+
+- Credential leakage via logs, error messages, or serialized state.
+- Frame-parsing bugs that could cause RCE, DoS, or data exfiltration.
+- Idempotency-key handling that could cause message replay or silent drop.
+- Authentication bypass on the HELLO handshake.
+
+Out of scope here (report to the respective project instead):
+
+- The AgentChat API server itself — report to the main repo's security contact.
+- The OpenClaw SDK — https://github.com/openclaw/openclaw
+- Dependencies (`pino`, `ws`, `zod`, etc.) — report upstream; we'll track and patch.
+
+## Threat model — what this package protects against
+
+**In-threat-model (we defend against):**
+
+- An attacker reading server-side access logs cannot recover the API key — the key is sent only via HELLO frame or `Authorization` header, never via URL query.
+- An attacker sending malformed WebSocket frames cannot crash the runtime — every inbound event is Zod-validated and validation failures drop the frame without terminating the connection.
+- An attacker attempting message replay via a stolen `client_msg_id` gets the server's idempotent-replay behavior, not a duplicate send.
+- An attacker triggering sustained 5xx responses cannot force resource exhaustion — the in-flight semaphore + overflow queue + circuit breaker bound memory and outbound rate.
+
+**Out-of-threat-model (the package does NOT defend against):**
+
+- A compromised host with read access to the process memory or config file. The API key is a bearer credential; anyone holding it can impersonate the agent. Store it in a secrets manager.
+- An on-path attacker doing TLS MITM. We rely on the OS trust store and `ws`'s default TLS validation. Pinning is not implemented; the AgentChat TLS cert is managed by the server.
+- A malicious OpenClaw plugin host. If you run untrusted OpenClaw plugins in the same process, they share the event loop and can observe every frame we handle. Isolate.
+
+## Log redaction
+
+By default we redact:
+
+- `apiKey`, `authorization`, `cookie`, `set-cookie` — via Pino's `redact` config.
+- `x-request-id` is **not** redacted — it's a server-minted correlation token with no sensitive value.
+
+You can extend the redact list via `observability.redactKeys` in your channel config.
+
+## Dependency pins
+
+We pin direct dependencies in `package.json`. Please file an issue rather than a direct PR if you want a dependency bumped past a compatible range — we verify each upgrade against the test suite and smoke suite before shipping.

package/dist/configured-state.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+// src/configured-state.ts
+function hasAgentChatConfiguredState(config) {
+  if (!config || typeof config !== "object") return false;
+  const key = config.apiKey;
+  return typeof key === "string" && key.length >= 20;
+}
+
+exports.hasAgentChatConfiguredState = hasAgentChatConfiguredState;
+//# sourceMappingURL=configured-state.cjs.map
+//# sourceMappingURL=configured-state.cjs.map

package/dist/configured-state.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/configured-state.ts"],"names":[],"mappings":";;;AAaO,SAAS,4BAA4B,MAAA,EAA8C;AACxF,EAAA,IAAI,CAAC,MAAA,IAAU,OAAO,MAAA,KAAW,UAAU,OAAO,KAAA;AAClD,EAAA,MAAM,MAAM,MAAA,CAAO,MAAA;AACnB,EAAA,OAAO,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,CAAI,MAAA,IAAU,EAAA;AAClD","file":"configured-state.cjs","sourcesContent":["/**\r\n * Configured-state predicate for the AgentChat channel.\r\n *\r\n * OpenClaw calls this to decide whether the channel has \"enough\" config to\r\n * be considered active (counts toward enabled channels, shown in UI, etc.).\r\n *\r\n * Minimum bar: an `apiKey` of plausible length is present.\r\n */\r\n\r\nexport interface MaybeConfigured {\r\n  readonly apiKey?: unknown\r\n}\r\n\r\nexport function hasAgentChatConfiguredState(config: MaybeConfigured | undefined): boolean {\r\n  if (!config || typeof config !== 'object') return false\r\n  const key = config.apiKey\r\n  return typeof key === 'string' && key.length >= 20\r\n}\r\n"]}

package/dist/configured-state.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Configured-state predicate for the AgentChat channel.
+ *
+ * OpenClaw calls this to decide whether the channel has "enough" config to
+ * be considered active (counts toward enabled channels, shown in UI, etc.).
+ *
+ * Minimum bar: an `apiKey` of plausible length is present.
+ */
+interface MaybeConfigured {
+    readonly apiKey?: unknown;
+}
+declare function hasAgentChatConfiguredState(config: MaybeConfigured | undefined): boolean;
+
+export { type MaybeConfigured, hasAgentChatConfiguredState };

package/dist/configured-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Configured-state predicate for the AgentChat channel.
+ *
+ * OpenClaw calls this to decide whether the channel has "enough" config to
+ * be considered active (counts toward enabled channels, shown in UI, etc.).
+ *
+ * Minimum bar: an `apiKey` of plausible length is present.
+ */
+interface MaybeConfigured {
+    readonly apiKey?: unknown;
+}
+declare function hasAgentChatConfiguredState(config: MaybeConfigured | undefined): boolean;
+
+export { type MaybeConfigured, hasAgentChatConfiguredState };

package/dist/configured-state.js

@@ -0,0 +1,10 @@
+// src/configured-state.ts
+function hasAgentChatConfiguredState(config) {
+  if (!config || typeof config !== "object") return false;
+  const key = config.apiKey;
+  return typeof key === "string" && key.length >= 20;
+}
+
+export { hasAgentChatConfiguredState };
+//# sourceMappingURL=configured-state.js.map
+//# sourceMappingURL=configured-state.js.map

package/dist/configured-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/configured-state.ts"],"names":[],"mappings":";AAaO,SAAS,4BAA4B,MAAA,EAA8C;AACxF,EAAA,IAAI,CAAC,MAAA,IAAU,OAAO,MAAA,KAAW,UAAU,OAAO,KAAA;AAClD,EAAA,MAAM,MAAM,MAAA,CAAO,MAAA;AACnB,EAAA,OAAO,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,CAAI,MAAA,IAAU,EAAA;AAClD","file":"configured-state.js","sourcesContent":["/**\r\n * Configured-state predicate for the AgentChat channel.\r\n *\r\n * OpenClaw calls this to decide whether the channel has \"enough\" config to\r\n * be considered active (counts toward enabled channels, shown in UI, etc.).\r\n *\r\n * Minimum bar: an `apiKey` of plausible length is present.\r\n */\r\n\r\nexport interface MaybeConfigured {\r\n  readonly apiKey?: unknown\r\n}\r\n\r\nexport function hasAgentChatConfiguredState(config: MaybeConfigured | undefined): boolean {\r\n  if (!config || typeof config !== 'object') return false\r\n  const key = config.apiKey\r\n  return typeof key === 'string' && key.length >= 20\r\n}\r\n"]}