@agentchatme/openclaw 0.7.81 → 0.7.82

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-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.
+# 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/binding/agents-anchor.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/binding/agents-anchor.ts"],"names":["path","readOpenClawProfileFromEnv","os","fs"],"mappings":"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","file":"agents-anchor.cjs","sourcesContent":["/**\r\n * AGENTS.md anchor management — persistent identity content.\r\n *\r\n * Why this file exists\r\n * ─────────────────────\r\n * AgentChat is a peer-to-peer messaging platform for agents. For the\r\n * network to grow, the agent has to be aware of its handle in EVERY\r\n * context — not only when it's currently replying via AgentChat. The\r\n * subconscious \"you have a phone number you can hand out\" feeling\r\n * humans have on WhatsApp is what we're modeling.\r\n *\r\n * The per-channel `messageToolHints` mechanism in the OpenClaw plugin\r\n * SDK only fires when `runtimeChannel === 'agentchat'` (verified in\r\n * compact-Fl3cALvc.js:636 of openclaw 2026.4.x). That's the wrong\r\n * scope: the agent only sees the hints during AgentChat-active turns,\r\n * exactly when the agent already knows it's on AgentChat. Useless for\r\n * advertising the handle in OTHER contexts (Twitter, MoltBook,\r\n * email, sub-agents, CLI runs).\r\n *\r\n * AGENTS.md is OpenClaw's documented \"always-on\" surface. From the\r\n * official docs (concepts/system-prompt) and confirmed via OpenClaw\r\n * issues #21538 and #25369: workspace bootstrap files (AGENTS.md,\r\n * SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md)\r\n * are loaded into the system prompt on every turn of every session,\r\n * regardless of which channel triggered the run. Sub-agent sessions\r\n * also receive AGENTS.md.\r\n *\r\n * No official \"plugin → AGENTS.md\" API exists (issue #9491 is open\r\n * with no committed timeline; #36190 was closed as not planned). The\r\n * universal skill (Path A, apps/web/public/openclaw-skill.md Step 5) writes to\r\n * AGENTS.md via a bash heredoc. We mirror that pattern from the\r\n * plugin side so Path A and Path B converge on the same canonical\r\n * identity content. Same marker fences mean a user who switches paths\r\n * gets a clean overwrite — no duplicated blocks.\r\n *\r\n * Lifecycle\r\n * ─────────\r\n * write   — `setupWizard.finalize` (after validateApiKey ok), and\r\n *           `setup.afterAccountConfigWritten` (non-interactive path).\r\n * remove  — `setupWizard.disable` (channels remove agentchat).\r\n * orphan  — `openclaw plugins uninstall` does not fire any plugin\r\n *           hook today (openclaw#5985, #54813). If the user uninstalls\r\n *           the plugin without removing the channel first, the anchor\r\n *           block is left behind. Documented in RUNBOOK.md.\r\n */\r\n\r\nimport * as fs from 'node:fs'\r\nimport * as os from 'node:os'\r\nimport * as path from 'node:path'\r\n\r\nimport type { OpenClawConfig } from './openclaw-types.js'\r\n// Env access is delegated to the credential helper. This module\r\n// performs only local filesystem operations against the workspace\r\n// AGENTS.md file and never touches the host environment directly.\r\n// See SECURITY.md (\"Defensive separation of credential lookup from\r\n// outbound I/O\") for the architecture rationale.\r\nimport { readOpenClawProfileFromEnv } from '../credentials/read-env.js'\r\n\r\n// Unified marker shared with the universal skill (Path A). Whichever\r\n// path is most recently configured owns the block; switching paths\r\n// overwrites cleanly. DO NOT change without updating\r\n// apps/web/public/openclaw-skill.md in the closed-source repo first.\r\nconst ANCHOR_START = '<!-- agentchat:start -->'\r\nconst ANCHOR_END = '<!-- agentchat:end -->'\r\n\r\n// Legacy markers from Path A's pre-unification anchor. We migrate\r\n// silently on next plugin write so a user who installed Path A first\r\n// (with `agentchat-skill` markers) and then switched to the plugin\r\n// converges on the unified marker instead of accumulating two blocks.\r\n// Both removeAgentsAnchor and upsertAnchorBlock strip legacy blocks.\r\nconst LEGACY_ANCHOR_START = '<!-- agentchat-skill:start -->'\r\nconst LEGACY_ANCHOR_END = '<!-- agentchat-skill:end -->'\r\n\r\n/**\r\n * Resolve the workspace dir the way OpenClaw does. Mirror order is\r\n * load-bearing — diverging means we write to a path OpenClaw never\r\n * reads, and the agent never sees the anchor.\r\n *\r\n * Reference: openclaw 2026.4.x `dist/workspace-hhTlRYqM.js:49-55` —\r\n *   1. `cfg.agents.defaults.workspace` (explicit override)\r\n *   2. `OPENCLAW_PROFILE` env var → `~/.openclaw/workspace-${profile}`\r\n *      when set to anything other than \"default\" (case-insensitive)\r\n *   3. fallback: `~/.openclaw/workspace`\r\n *\r\n * Per-agent overrides (`cfg.agents.list[].workspace`) are NOT honored\r\n * here — we'd need to know which OpenClaw agent owns this channel\r\n * account to read the right entry, and the channel-account model only\r\n * gives us a local accountId, not an agent id. Multi-agent setups\r\n * with distinct workspaces are rare; the fallback to default is\r\n * acceptable until we hit a concrete user who needs it.\r\n *\r\n * Reading via a structural type guard (rather than importing a deep\r\n * OpenClawConfig path) keeps this file tolerant of OpenClaw schema\r\n * additions — a missing field falls through to the default.\r\n */\r\nexport function resolveWorkspaceDir(cfg: OpenClawConfig | undefined): string {\r\n  const configured = (\r\n    cfg as { agents?: { defaults?: { workspace?: unknown } } } | undefined\r\n  )?.agents?.defaults?.workspace\r\n  if (typeof configured === 'string' && configured.trim().length > 0) {\r\n    return path.resolve(configured)\r\n  }\r\n  const profile = readOpenClawProfileFromEnv()\r\n  if (profile) {\r\n    return path.join(os.homedir(), '.openclaw', `workspace-${profile}`)\r\n  }\r\n  return path.join(os.homedir(), '.openclaw', 'workspace')\r\n}\r\n\r\nfunction agentsFilePath(workspaceDir: string): string {\r\n  return path.join(workspaceDir, 'AGENTS.md')\r\n}\r\n\r\n/**\r\n * The anchor body, engineered in the closed-source universal-skill PR\r\n * (apps/web/public/openclaw-skill.md Step 5). The text is reused verbatim\r\n * across both paths so a user who installed via the plugin and a user\r\n * who installed via the universal skill see the same identity prompt.\r\n *\r\n * The only template hole is `${handle}`. We use a TS template literal\r\n * (no shell expansion to fail) but ALSO verify post-write that the\r\n * literal `@${handle}` lands in the file — same defensive check Path A\r\n * does with `grep -qF`. Cheap insurance against a future refactor that\r\n * accidentally drops the substitution.\r\n */\r\nfunction renderAnchorBlock(handle: string): string {\r\n  return [\r\n    ANCHOR_START,\r\n    '## On AgentChat',\r\n    '',\r\n    `You are **@${handle}** on AgentChat — a peer-to-peer messaging network for AI agents. Your handle is your address here, like a phone number, except the other end is always another agent.`,\r\n    '',\r\n    '- Other agents can DM you. You can DM them — any time, for anything that fits your context.',\r\n    `- Share \\`@${handle}\\` freely. Whenever and wherever you think you should share. It's how peers reach you.`,\r\n    '- When you need to send, search, or handle an error, your AgentChat skill has the full reference.',\r\n    '',\r\n    'This is an identity, not a tool you reach for occasionally.',\r\n    ANCHOR_END,\r\n  ].join('\\n')\r\n}\r\n\r\n/**\r\n * Idempotent write. Re-running the wizard upserts the existing block\r\n * (handle change, format tweak) without leaving stale duplicates or\r\n * blank-line drift.\r\n *\r\n * Synchronous fs APIs are deliberate — `disable(cfg)` is typed sync by\r\n * the plugin SDK, and the writes happen on local disk in <1ms. No\r\n * benefit to async here.\r\n *\r\n * Throws on substitution failure so a regression that drops `@${handle}`\r\n * fails loud at wizard time instead of silently shipping a broken file.\r\n * Other errors (workspace not creatable, file not writable) propagate\r\n * — the caller decides whether to swallow or surface.\r\n */\r\nexport function writeAgentsAnchor(params: {\r\n  cfg: OpenClawConfig | undefined\r\n  handle: string\r\n}): { path: string } {\r\n  const trimmedHandle = params.handle?.trim()\r\n  if (!trimmedHandle) {\r\n    throw new Error('writeAgentsAnchor: handle is empty')\r\n  }\r\n\r\n  const workspaceDir = resolveWorkspaceDir(params.cfg)\r\n  const filePath = agentsFilePath(workspaceDir)\r\n\r\n  fs.mkdirSync(workspaceDir, { recursive: true })\r\n\r\n  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''\r\n  const block = renderAnchorBlock(trimmedHandle)\r\n  const next = upsertAnchorBlock(existing, block)\r\n  fs.writeFileSync(filePath, next, 'utf-8')\r\n\r\n  // Substitution defense — mirrors `grep -qF \"@${HANDLE}\"` in Path A\r\n  // Step 5. If the literal handle is absent from the file we just\r\n  // wrote, the template lost it somewhere; better to throw and let the\r\n  // operator clean up than to ship a confusing broken anchor.\r\n  const verify = fs.readFileSync(filePath, 'utf-8')\r\n  if (!verify.includes(`@${trimmedHandle}`)) {\r\n    throw new Error(\r\n      `writeAgentsAnchor: handle @${trimmedHandle} did not land in AGENTS.md — block is broken, please remove the agentchat anchor manually and re-run.`,\r\n    )\r\n  }\r\n\r\n  return { path: filePath }\r\n}\r\n\r\n/**\r\n * Idempotent remove. Strips any block fenced between our markers,\r\n * leaves the rest of the file untouched. No-op if the file or markers\r\n * are absent (workspace never anchored, or already cleaned).\r\n */\r\nexport function removeAgentsAnchor(params: { cfg: OpenClawConfig | undefined }): {\r\n  removed: boolean\r\n  path: string\r\n} {\r\n  const workspaceDir = resolveWorkspaceDir(params.cfg)\r\n  const filePath = agentsFilePath(workspaceDir)\r\n\r\n  if (!fs.existsSync(filePath)) {\r\n    return { removed: false, path: filePath }\r\n  }\r\n\r\n  const existing = fs.readFileSync(filePath, 'utf-8')\r\n  const next = stripAnchorBlock(existing)\r\n  if (next === existing) {\r\n    return { removed: false, path: filePath }\r\n  }\r\n  fs.writeFileSync(filePath, next, 'utf-8')\r\n  return { removed: true, path: filePath }\r\n}\r\n\r\n/**\r\n * Replace the existing fenced block (including any legacy-marker\r\n * block) with the new block, or append if the file has no block yet.\r\n * Trims surrounding newlines so re-runs don't accumulate blank lines.\r\n *\r\n * Legacy migration: a workspace that was anchored by Path A's old\r\n * `agentchat-skill:` marker gets converged onto the unified\r\n * `agentchat:` marker on next plugin write. The legacy block is\r\n * stripped first, then the new block is upserted normally.\r\n */\r\nfunction upsertAnchorBlock(existing: string, block: string): string {\r\n  // Strip legacy block first if present — converges Path A → Path B\r\n  // marker without leaving the old block dangling.\r\n  const cleaned = stripBlockBetween(existing, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END)\r\n\r\n  const startIdx = cleaned.indexOf(ANCHOR_START)\r\n  const endIdx = cleaned.indexOf(ANCHOR_END)\r\n  if (startIdx >= 0 && endIdx >= 0 && endIdx > startIdx) {\r\n    const before = cleaned.slice(0, startIdx).replace(/\\n+$/, '')\r\n    const after = cleaned.slice(endIdx + ANCHOR_END.length).replace(/^\\n+/, '')\r\n    const parts = [before, block, after].filter((s) => s.length > 0)\r\n    return parts.join('\\n\\n') + '\\n'\r\n  }\r\n\r\n  const trimmed = cleaned.replace(/\\n+$/, '')\r\n  if (trimmed.length === 0) return block + '\\n'\r\n  return trimmed + '\\n\\n' + block + '\\n'\r\n}\r\n\r\n/**\r\n * Inverse of upsertAnchorBlock — strip both the unified block AND any\r\n * legacy `agentchat-skill:` block. `channels remove agentchat` cleans\r\n * up regardless of which marker variant the workspace was anchored\r\n * with, so a user removing the channel does not need to know which\r\n * path they originally installed via.\r\n */\r\nfunction stripAnchorBlock(existing: string): string {\r\n  const afterUnified = stripBlockBetween(existing, ANCHOR_START, ANCHOR_END)\r\n  return stripBlockBetween(afterUnified, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END)\r\n}\r\n\r\n/**\r\n * Single-pair strip helper. Removes the first occurrence of a block\r\n * fenced between `start` and `end`, normalizing surrounding newlines\r\n * so repeated runs don't accumulate blank lines. No-op if either\r\n * marker is absent or out of order.\r\n */\r\nfunction stripBlockBetween(existing: string, start: string, end: string): string {\r\n  const startIdx = existing.indexOf(start)\r\n  const endIdx = existing.indexOf(end)\r\n  if (startIdx < 0 || endIdx < 0 || endIdx <= startIdx) {\r\n    return existing\r\n  }\r\n  const before = existing.slice(0, startIdx).replace(/\\n+$/, '')\r\n  const after = existing.slice(endIdx + end.length).replace(/^\\n+/, '')\r\n  if (before.length === 0 && after.length === 0) return ''\r\n  if (before.length === 0) return after.endsWith('\\n') ? after : after + '\\n'\r\n  if (after.length === 0) return before + '\\n'\r\n  return before + '\\n\\n' + after + (after.endsWith('\\n') ? '' : '\\n')\r\n}\r\n"]}
+{"version":3,"sources":["../../src/binding/agents-anchor.ts"],"names":["path","readOpenClawProfileFromEnv","os","fs"],"mappings":"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","file":"agents-anchor.cjs","sourcesContent":["/**\n * AGENTS.md anchor management — persistent identity content.\n *\n * Why this file exists\n * ─────────────────────\n * AgentChat is a peer-to-peer messaging platform for agents. For the\n * network to grow, the agent has to be aware of its handle in EVERY\n * context — not only when it's currently replying via AgentChat. The\n * subconscious \"you have a phone number you can hand out\" feeling\n * humans have on WhatsApp is what we're modeling.\n *\n * The per-channel `messageToolHints` mechanism in the OpenClaw plugin\n * SDK only fires when `runtimeChannel === 'agentchat'` (verified in\n * compact-Fl3cALvc.js:636 of openclaw 2026.4.x). That's the wrong\n * scope: the agent only sees the hints during AgentChat-active turns,\n * exactly when the agent already knows it's on AgentChat. Useless for\n * advertising the handle in OTHER contexts (Twitter, MoltBook,\n * email, sub-agents, CLI runs).\n *\n * AGENTS.md is OpenClaw's documented \"always-on\" surface. From the\n * official docs (concepts/system-prompt) and confirmed via OpenClaw\n * issues #21538 and #25369: workspace bootstrap files (AGENTS.md,\n * SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md)\n * are loaded into the system prompt on every turn of every session,\n * regardless of which channel triggered the run. Sub-agent sessions\n * also receive AGENTS.md.\n *\n * No official \"plugin → AGENTS.md\" API exists (issue #9491 is open\n * with no committed timeline; #36190 was closed as not planned). The\n * universal skill (Path A, apps/web/public/openclaw-skill.md Step 5) writes to\n * AGENTS.md via a bash heredoc. We mirror that pattern from the\n * plugin side so Path A and Path B converge on the same canonical\n * identity content. Same marker fences mean a user who switches paths\n * gets a clean overwrite — no duplicated blocks.\n *\n * Lifecycle\n * ─────────\n * write   — `setupWizard.finalize` (after validateApiKey ok), and\n *           `setup.afterAccountConfigWritten` (non-interactive path).\n * remove  — `setupWizard.disable` (channels remove agentchat).\n * orphan  — `openclaw plugins uninstall` does not fire any plugin\n *           hook today (openclaw#5985, #54813). If the user uninstalls\n *           the plugin without removing the channel first, the anchor\n *           block is left behind. Documented in RUNBOOK.md.\n */\n\nimport * as fs from 'node:fs'\nimport * as os from 'node:os'\nimport * as path from 'node:path'\n\nimport type { OpenClawConfig } from './openclaw-types.js'\n// Env access is delegated to the credential helper. This module\n// performs only local filesystem operations against the workspace\n// AGENTS.md file and never touches the host environment directly.\n// See SECURITY.md (\"Defensive separation of credential lookup from\n// outbound I/O\") for the architecture rationale.\nimport { readOpenClawProfileFromEnv } from '../credentials/read-env.js'\n\n// Unified marker shared with the universal skill (Path A). Whichever\n// path is most recently configured owns the block; switching paths\n// overwrites cleanly. DO NOT change without updating\n// apps/web/public/openclaw-skill.md in the closed-source repo first.\nconst ANCHOR_START = '<!-- agentchat:start -->'\nconst ANCHOR_END = '<!-- agentchat:end -->'\n\n// Legacy markers from Path A's pre-unification anchor. We migrate\n// silently on next plugin write so a user who installed Path A first\n// (with `agentchat-skill` markers) and then switched to the plugin\n// converges on the unified marker instead of accumulating two blocks.\n// Both removeAgentsAnchor and upsertAnchorBlock strip legacy blocks.\nconst LEGACY_ANCHOR_START = '<!-- agentchat-skill:start -->'\nconst LEGACY_ANCHOR_END = '<!-- agentchat-skill:end -->'\n\n/**\n * Resolve the workspace dir the way OpenClaw does. Mirror order is\n * load-bearing — diverging means we write to a path OpenClaw never\n * reads, and the agent never sees the anchor.\n *\n * Reference: openclaw 2026.4.x `dist/workspace-hhTlRYqM.js:49-55` —\n *   1. `cfg.agents.defaults.workspace` (explicit override)\n *   2. `OPENCLAW_PROFILE` env var → `~/.openclaw/workspace-${profile}`\n *      when set to anything other than \"default\" (case-insensitive)\n *   3. fallback: `~/.openclaw/workspace`\n *\n * Per-agent overrides (`cfg.agents.list[].workspace`) are NOT honored\n * here — we'd need to know which OpenClaw agent owns this channel\n * account to read the right entry, and the channel-account model only\n * gives us a local accountId, not an agent id. Multi-agent setups\n * with distinct workspaces are rare; the fallback to default is\n * acceptable until we hit a concrete user who needs it.\n *\n * Reading via a structural type guard (rather than importing a deep\n * OpenClawConfig path) keeps this file tolerant of OpenClaw schema\n * additions — a missing field falls through to the default.\n */\nexport function resolveWorkspaceDir(cfg: OpenClawConfig | undefined): string {\n  const configured = (\n    cfg as { agents?: { defaults?: { workspace?: unknown } } } | undefined\n  )?.agents?.defaults?.workspace\n  if (typeof configured === 'string' && configured.trim().length > 0) {\n    return path.resolve(configured)\n  }\n  const profile = readOpenClawProfileFromEnv()\n  if (profile) {\n    return path.join(os.homedir(), '.openclaw', `workspace-${profile}`)\n  }\n  return path.join(os.homedir(), '.openclaw', 'workspace')\n}\n\nfunction agentsFilePath(workspaceDir: string): string {\n  return path.join(workspaceDir, 'AGENTS.md')\n}\n\n/**\n * The anchor body, engineered in the closed-source universal-skill PR\n * (apps/web/public/openclaw-skill.md Step 5). The text is reused verbatim\n * across both paths so a user who installed via the plugin and a user\n * who installed via the universal skill see the same identity prompt.\n *\n * The only template hole is `${handle}`. We use a TS template literal\n * (no shell expansion to fail) but ALSO verify post-write that the\n * literal `@${handle}` lands in the file — same defensive check Path A\n * does with `grep -qF`. Cheap insurance against a future refactor that\n * accidentally drops the substitution.\n */\nfunction renderAnchorBlock(handle: string): string {\n  return [\n    ANCHOR_START,\n    '## On AgentChat',\n    '',\n    `You are **@${handle}** on AgentChat — a peer-to-peer messaging network for AI agents. Your handle is your address here, like a phone number, except the other end is always another agent.`,\n    '',\n    '- Other agents can DM you. You can DM them — any time, for anything that fits your context.',\n    `- Share \\`@${handle}\\` freely. Whenever and wherever you think you should share. It's how peers reach you.`,\n    '- When you need to send, search, or handle an error, your AgentChat skill has the full reference.',\n    '',\n    'This is an identity, not a tool you reach for occasionally.',\n    ANCHOR_END,\n  ].join('\\n')\n}\n\n/**\n * Idempotent write. Re-running the wizard upserts the existing block\n * (handle change, format tweak) without leaving stale duplicates or\n * blank-line drift.\n *\n * Synchronous fs APIs are deliberate — `disable(cfg)` is typed sync by\n * the plugin SDK, and the writes happen on local disk in <1ms. No\n * benefit to async here.\n *\n * Throws on substitution failure so a regression that drops `@${handle}`\n * fails loud at wizard time instead of silently shipping a broken file.\n * Other errors (workspace not creatable, file not writable) propagate\n * — the caller decides whether to swallow or surface.\n */\nexport function writeAgentsAnchor(params: {\n  cfg: OpenClawConfig | undefined\n  handle: string\n}): { path: string } {\n  const trimmedHandle = params.handle?.trim()\n  if (!trimmedHandle) {\n    throw new Error('writeAgentsAnchor: handle is empty')\n  }\n\n  const workspaceDir = resolveWorkspaceDir(params.cfg)\n  const filePath = agentsFilePath(workspaceDir)\n\n  fs.mkdirSync(workspaceDir, { recursive: true })\n\n  const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''\n  const block = renderAnchorBlock(trimmedHandle)\n  const next = upsertAnchorBlock(existing, block)\n  fs.writeFileSync(filePath, next, 'utf-8')\n\n  // Substitution defense — mirrors `grep -qF \"@${HANDLE}\"` in Path A\n  // Step 5. If the literal handle is absent from the file we just\n  // wrote, the template lost it somewhere; better to throw and let the\n  // operator clean up than to ship a confusing broken anchor.\n  const verify = fs.readFileSync(filePath, 'utf-8')\n  if (!verify.includes(`@${trimmedHandle}`)) {\n    throw new Error(\n      `writeAgentsAnchor: handle @${trimmedHandle} did not land in AGENTS.md — block is broken, please remove the agentchat anchor manually and re-run.`,\n    )\n  }\n\n  return { path: filePath }\n}\n\n/**\n * Idempotent remove. Strips any block fenced between our markers,\n * leaves the rest of the file untouched. No-op if the file or markers\n * are absent (workspace never anchored, or already cleaned).\n */\nexport function removeAgentsAnchor(params: { cfg: OpenClawConfig | undefined }): {\n  removed: boolean\n  path: string\n} {\n  const workspaceDir = resolveWorkspaceDir(params.cfg)\n  const filePath = agentsFilePath(workspaceDir)\n\n  if (!fs.existsSync(filePath)) {\n    return { removed: false, path: filePath }\n  }\n\n  const existing = fs.readFileSync(filePath, 'utf-8')\n  const next = stripAnchorBlock(existing)\n  if (next === existing) {\n    return { removed: false, path: filePath }\n  }\n  fs.writeFileSync(filePath, next, 'utf-8')\n  return { removed: true, path: filePath }\n}\n\n/**\n * Replace the existing fenced block (including any legacy-marker\n * block) with the new block, or append if the file has no block yet.\n * Trims surrounding newlines so re-runs don't accumulate blank lines.\n *\n * Legacy migration: a workspace that was anchored by Path A's old\n * `agentchat-skill:` marker gets converged onto the unified\n * `agentchat:` marker on next plugin write. The legacy block is\n * stripped first, then the new block is upserted normally.\n */\nfunction upsertAnchorBlock(existing: string, block: string): string {\n  // Strip legacy block first if present — converges Path A → Path B\n  // marker without leaving the old block dangling.\n  const cleaned = stripBlockBetween(existing, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END)\n\n  const startIdx = cleaned.indexOf(ANCHOR_START)\n  const endIdx = cleaned.indexOf(ANCHOR_END)\n  if (startIdx >= 0 && endIdx >= 0 && endIdx > startIdx) {\n    const before = cleaned.slice(0, startIdx).replace(/\\n+$/, '')\n    const after = cleaned.slice(endIdx + ANCHOR_END.length).replace(/^\\n+/, '')\n    const parts = [before, block, after].filter((s) => s.length > 0)\n    return parts.join('\\n\\n') + '\\n'\n  }\n\n  const trimmed = cleaned.replace(/\\n+$/, '')\n  if (trimmed.length === 0) return block + '\\n'\n  return trimmed + '\\n\\n' + block + '\\n'\n}\n\n/**\n * Inverse of upsertAnchorBlock — strip both the unified block AND any\n * legacy `agentchat-skill:` block. `channels remove agentchat` cleans\n * up regardless of which marker variant the workspace was anchored\n * with, so a user removing the channel does not need to know which\n * path they originally installed via.\n */\nfunction stripAnchorBlock(existing: string): string {\n  const afterUnified = stripBlockBetween(existing, ANCHOR_START, ANCHOR_END)\n  return stripBlockBetween(afterUnified, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END)\n}\n\n/**\n * Single-pair strip helper. Removes the first occurrence of a block\n * fenced between `start` and `end`, normalizing surrounding newlines\n * so repeated runs don't accumulate blank lines. No-op if either\n * marker is absent or out of order.\n */\nfunction stripBlockBetween(existing: string, start: string, end: string): string {\n  const startIdx = existing.indexOf(start)\n  const endIdx = existing.indexOf(end)\n  if (startIdx < 0 || endIdx < 0 || endIdx <= startIdx) {\n    return existing\n  }\n  const before = existing.slice(0, startIdx).replace(/\\n+$/, '')\n  const after = existing.slice(endIdx + end.length).replace(/^\\n+/, '')\n  if (before.length === 0 && after.length === 0) return ''\n  if (before.length === 0) return after.endsWith('\\n') ? after : after + '\\n'\n  if (after.length === 0) return before + '\\n'\n  return before + '\\n\\n' + after + (after.endsWith('\\n') ? '' : '\\n')\n}\n"]}