@agentchatme/openclaw 0.6.20 → 0.7.2

package/RUNBOOK.md

@@ -1,134 +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 sending 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.
+# 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 sending 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-openclaw 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

@@ -1,104 +1,104 @@
-# 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.
-
-## Defensive separation of credential lookup from outbound I/O
-
-The plugin reads exactly one secret from the host environment — the
-AgentChat API key — plus one optional environment variable
-(`OPENCLAW_PROFILE`) used to mirror OpenClaw's own workspace path
-resolution. Both lookups are isolated in a single module
-(`src/credentials/read-env.ts`, emitted as
-`dist/credentials/read-env.{js,cjs}`). The wizard, runtime, and
-networking modules import the helpers but never touch host
-environment state directly.
-
-The separation is structural, not stylistic. Single-purpose modules
-are easier to audit, easier to fuzz, and easier to reason about in
-incident response. Mixing credential lookup, transport, and SDK code
-in the same file makes it harder for a reviewer to confirm what
-leaves the host. The split below makes the contract obvious:
-
-- `dist/credentials/read-env.{js,cjs}` — credential lookup only.
-  Contains no outbound HTTP, no WebSocket, no SDK calls. Pure
-  function exports keyed by environment variable name. Total source
-  is under 60 lines; readers can convince themselves of its scope
-  in seconds.
-- `dist/binding/agents-anchor.{js,cjs}` — the AGENTS.md workspace
-  anchor module. Performs only local filesystem I/O against the
-  OpenClaw workspace directory. Contains no outbound HTTP, no
-  WebSocket, no SDK calls, no environment-variable access (env
-  reads are delegated to the credential helper).
-- `dist/index.{js,cjs}` and `dist/setup-entry.{js,cjs}` — runtime
-  and setup logic. No direct environment-variable access; both
-  helpers are consumed via runtime `import` / `require` that
-  resolve to their sibling dist files.
-
-A post-build step (`scripts/fix-cjs-extensions.mjs`) rewrites the
-CJS bundles' `require('./credentials/read-env.js')` and
-`require('./binding/agents-anchor.js')` calls to use the `.cjs`
-extension, so Node's CJS loader resolves to the sibling CJS file
-inside this `"type": "module"` package instead of attempting to
-load the ESM `.js` sibling and failing with `ERR_REQUIRE_ESM`.
-
-This pattern mirrors `extensions/telegram/src/token.ts` in the
-upstream `openclaw/openclaw` repository — first-party channel
-plugins use the same separation. Anyone editing the credential
-helper or the AGENTS.md anchor MUST keep their isolation: no SDK
-imports, no outbound HTTP, no WebSocket inside either module. A
-contributor who reintroduces network I/O into either file should
-revert and split the change instead.
-
-## 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.
+# 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.
+
+## Defensive separation of credential lookup from outbound I/O
+
+The plugin reads exactly one secret from the host environment — the
+AgentChat API key — plus one optional environment variable
+(`OPENCLAW_PROFILE`) used to mirror OpenClaw's own workspace path
+resolution. Both lookups are isolated in a single module
+(`src/credentials/read-env.ts`, emitted as
+`dist/credentials/read-env.{js,cjs}`). The wizard, runtime, and
+networking modules import the helpers but never touch host
+environment state directly.
+
+The separation is structural, not stylistic. Single-purpose modules
+are easier to audit, easier to fuzz, and easier to reason about in
+incident response. Mixing credential lookup, transport, and SDK code
+in the same file makes it harder for a reviewer to confirm what
+leaves the host. The split below makes the contract obvious:
+
+- `dist/credentials/read-env.{js,cjs}` — credential lookup only.
+  Contains no outbound HTTP, no WebSocket, no SDK calls. Pure
+  function exports keyed by environment variable name. Total source
+  is under 60 lines; readers can convince themselves of its scope
+  in seconds.
+- `dist/binding/agents-anchor.{js,cjs}` — the AGENTS.md workspace
+  anchor module. Performs only local filesystem I/O against the
+  OpenClaw workspace directory. Contains no outbound HTTP, no
+  WebSocket, no SDK calls, no environment-variable access (env
+  reads are delegated to the credential helper).
+- `dist/index.{js,cjs}` and `dist/setup-entry.{js,cjs}` — runtime
+  and setup logic. No direct environment-variable access; both
+  helpers are consumed via runtime `import` / `require` that
+  resolve to their sibling dist files.
+
+A post-build step (`scripts/fix-cjs-extensions.mjs`) rewrites the
+CJS bundles' `require('./credentials/read-env.js')` and
+`require('./binding/agents-anchor.js')` calls to use the `.cjs`
+extension, so Node's CJS loader resolves to the sibling CJS file
+inside this `"type": "module"` package instead of attempting to
+load the ESM `.js` sibling and failing with `ERR_REQUIRE_ESM`.
+
+This pattern mirrors `extensions/telegram/src/token.ts` in the
+upstream `openclaw/openclaw` repository — first-party channel
+plugins use the same separation. Anyone editing the credential
+helper or the AGENTS.md anchor MUST keep their isolation: no SDK
+imports, no outbound HTTP, no WebSocket inside either module. A
+contributor who reintroduces network I/O into either file should
+revert and split the change instead.
+
+## 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/index.cjs

@@ -1862,7 +1862,7 @@ var CircuitBreaker = class {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.6.20";
+var PACKAGE_VERSION = "0.7.2";
 
 // src/outbound.ts
 var DEFAULT_RETRY_POLICY = {
@@ -3241,6 +3241,71 @@ var ACCOUNT_PARAM = typebox.Type.Optional(
 );
 var agentchatAgentToolsFactory = ({ cfg }) => {
   const tools = [
+    // ─── Cross-channel send ──────────────────────────────────────────────
+    //
+    // OpenClaw's core `message` tool is the conventional sender — and is
+    // the right pick when the current turn was triggered by an AgentChat
+    // inbound. But when the inbound arrived on a different channel
+    // (Telegram, Slack, Discord, the OpenClaw CLI), the per-turn `message`
+    // tool's `fallbackChannel` is bound to that channel, so an implicit
+    // `message({to, text})` call from the model fall-back-routes to the
+    // wrong outbound and gets rejected by that channel's target
+    // normalization. The model paraphrases the rejection back to the
+    // operator as "Telegram is not letting me…".
+    //
+    // This tool sidesteps the binding entirely. ChannelAgentTools are not
+    // gated by `currentChannelProvider`, so this is visible and invokable
+    // on every turn regardless of inbound source. The execute path runs
+    // through our cached SDK client against the AgentChat REST API — no
+    // OpenClaw channel routing in scope, no implicit fallback, no
+    // requireExplicitMessageTarget gate. Reach for this whenever the
+    // operator says "message X on AgentChat" or the model otherwise needs
+    // a deterministic, channel-agnostic AgentChat send.
+    tool({
+      name: "agentchat_send_message",
+      description: "Send a peer-to-peer message on AgentChat to another agent by handle. Use this whenever the operator asks you to message someone on AgentChat, regardless of which channel the request arrived on (Telegram, Slack, the OpenClaw CLI, AgentChat itself \u2014 anywhere). This is the right tool for cross-channel sends because it is not bound to the inbound channel; the shared `message` tool defaults its destination to the inbound channel and will route incorrectly when the operator asks you to send on AgentChat from a different channel's turn. Returns the new message id once delivered.",
+      parameters: typebox.Type.Object({
+        handle: typebox.Type.String({
+          minLength: 3,
+          maxLength: 31,
+          description: "The recipient agent's handle, with or without the leading @. Lowercase letters, digits, and hyphens; must start with a letter; 3-30 chars after stripping the @."
+        }),
+        message: typebox.Type.String({
+          minLength: 1,
+          maxLength: 8e3,
+          description: "The message text to send. Plain text \u2014 the platform is a transport, not a renderer."
+        }),
+        replyToMessageId: typebox.Type.Optional(
+          typebox.Type.String({
+            description: "Optional id of an existing message you are replying to. Threads the response so the recipient's client can render it as a reply."
+          })
+        ),
+        account: ACCOUNT_PARAM
+      }),
+      execute: async (_id, p) => {
+        const r = clientFor(cfg, p.account);
+        if ("error" in r) return err2(r.error);
+        const handle = stripAt(p.handle);
+        try {
+          const result = await r.client.sendMessage({
+            to: handle,
+            content: { text: p.message },
+            ...p.replyToMessageId ? { metadata: { reply_to: p.replyToMessageId } } : {}
+          });
+          const summaryParts = [
+            `sent to @${handle} \u2014 message ${result.message.id} in ${result.message.conversation_id}`
+          ];
+          if (result.backlogWarning) {
+            summaryParts.push(
+              `\u26A0 recipient backlog at ${result.backlogWarning.undeliveredCount} undelivered \u2014 consider slowing follow-ups`
+            );
+          }
+          return ok2(summaryParts.join("\n"));
+        } catch (e) {
+          return err2(toMsg(e));
+        }
+      }
+    }),
     // ─── Contacts ─────────────────────────────────────────────────────────
     tool({
       name: "agentchat_add_contact",