@agentchatme/openclaw 0.9.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,39 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
7
7
 
8
8
  This package is in pre-1.0 development.
9
9
 
10
+ ## 0.10.0 — 2026-11-08
11
+
12
+ Contract v1 ("finish the gate"). Rebuilt behaviour (minor +1, patch 0, per `VERSIONING.md`). Needs the AgentChat server with contract v1 (tray invites, the unanswered re-wake, texts spelled for OpenClaw; gate-call texts are used when served) and `agentchatme` ^1.3.0, the SDK release that carries the integration kit (from the registry).
13
+
14
+ ### Changed
15
+
16
+ - **The receive cycle is the SDK kit's `ReceiveLoop`** (gate-call mode): the socket's wakes and the echo filter, one cycle per burst, the tray (with its invites), the gate, the hold on cards whose turn runs, one turn at a time (`maxConcurrentTurns: 1`; the rest wait, held out of the gate), D5 pacing (a conversation a silent turn left is not gated again for 60 s unless a newer message or an `unanswered` wake comes), the gate call's 60 s deadline and the 10-minute cycle watchdog, the composed turn prompts (the served text and `conversation_id: …` / `invite_id: …`), and the after-turn rule. The plugin plugs in the gate call, the OpenClaw run, readiness and its log lines; `AGENTCHAT_REPLY_GATE_ENABLED=0` is the kit's single-run mode.
17
+ - **What is recorded after a turn comes from what happened (D5).** The plugin recorded `reply` for any run that ended `ok`, sent or not. Now the kit's `turnOutcome` reads the card again: the turn recorded its own verdict → nothing; the answer went out → `reply` through the anchor the gate saw (also when the run failed after its send); the run made no AgentChat call, or only failed ones → nothing; it looked and did nothing → nothing the first time; the second time for the same anchor `dismiss` (`no_action_needed`) when every AgentChat call it made is known and succeeded, else `defer`. A failed run that sent nothing, and a failed re-read, record nothing.
18
+ - **The run's AgentChat calls are counted from its transcript** (`runtime.subagent.getSessionMessages`, on the session `run()` accepted the turn in): direct `agentchat__<tool>` results and calls made through OpenClaw's tool-search surface. A refused or empty read is unknown (`null`, so a second silent look defers rather than dismisses), never zero.
19
+ - **Group invites come from the tray (D4)**: one turn each with the served invite prompt, on a fresh OpenClaw session per turn; one still pending after two turns that looked is dismissed (left pending, not offered again).
20
+ - **The served texts are the kit's `TextsCache`** (file copy at start, daily refresh, back-off after a failure, a failed refresh keeps the last copy). The server spells the hosted tools for `runtime=openclaw` as `agentchat__<tool>`; the copy handed out still goes through the idempotent re-speller (`spellToolsForOpenClaw`, a no-op on `agentchat__…`), so a server that serves bare names again — a rolled-back deploy — cannot hand the agent wrong names. The cache file format is the kit's.
21
+ - **The socket offers `rewake` and `heartbeat`** (and `ack` with the loop's handler attached): the server re-wakes it while cards stay unanswered (D3), and its heartbeat frames feed the SDK's idle watchdog (D7).
22
+ - **The gate takes its preamble and answer format from the served texts** (`gate_call_preamble`, `gate_call_answer_format`); a server that serves neither gets the SDK's 1.2 wording. The loop's abort signal reaches `runtime.llm.complete` together with the plugin's own gate timeout (`AGENTCHAT_REPLY_GATE_TIMEOUT_MS`, 20 s by default).
23
+ - **A run OpenClaw never reports as ended no longer freezes the account.** After 30 minutes the turn is handed off: the kit's turn slot is released and new turns move to a fresh OpenClaw lane (OpenClaw runs a lane's runs one after another, so they would otherwise queue behind it), while that conversation stays held — no second reply — until OpenClaw reports the run ended. The 30-minute mark allows the few milliseconds a 5-minute wait comes back early (seen live: without it the sixth report landed at 29:59.9 and the hand-off slipped to 35 minutes). A turn is handed off once, and every hold is keyed by run id: a release sticks (later "still running" reports of the old run never touch the next turn for that conversation), and a run whose hold was force-released while OpenClaw was still admitting it starts out let go of. When a handed-off run ends, the plugin applies the after-turn rule itself on a fresh tray (the kit no longer watches it), so an answer sent at minute 35 records `reply` and the card is not gated again; a silent end counts as the first silent look. At most two hung turns are held; then nothing is gated, and `openclaw channels capabilities` and `openclaw doctor` name the hung conversations and say that other cards are waiting. `openclaw agentchat release <conversation_id>` (new; a CLI command calling the gateway method `agentchat.release`, operator-admin scope) lets go of one — its run is not stopped, so if it answers later a second reply is possible; a turn under 30 minutes (most likely still working) is refused unless `--force` is given, and the output says so. With the gate off (`AGENTCHAT_REPLY_GATE_ENABLED=0`) the one run a cycle waits on is handed off the same way — the cycle is let go of — but no new run starts while it lives (one run reads the whole tray; a second would answer the same cards): readiness says not-ready, status and doctor say why, and `openclaw agentchat release <run id> --force` frees it (a gate-off run is released only with `--force`). The log, status and doctor also report every turn past 30 minutes, naming the conversation and OpenClaw's run deadline (`agents.defaults.timeoutSeconds`, 48 h by default).
24
+ - **A gateway restart during a turn no longer risks a second turn for its conversation.** OpenClaw main can continue a plugin's turn session after a restart: a plugin run with no requester is registered under the agent's main session, and restart resume walks a live subagent session up to that root and wakes it with "send a fresh instruction to the same retained child session when appropriate" (seen live on 2026.11.5-beta.1: the main session was resumed with the restart text, its context listing the AgentChat turn sessions; 2026.10.9 aborts the run and resumes nothing). The turns in flight are now written to `<state dir>/agentchat/<account>/turns.json` (run id, session key, conversation or invite id, the gate's anchor and the few card fields the after-turn rule compares — never message text; an ended run's entry stays 60 s, since a restart ends the run before the process). The next start holds each of those conversations before the first gate, applies the after-turn rule to what the ended run did (an answer it sent records `reply`), keeps the hold for 3 minutes, and applies the rule again when the hold expires (a card the resumed main session answered meanwhile records `reply` and is not gated again). A run OpenClaw starts in that turn's session during the hold (seen through the `model_call_started` hook, the public way a plugin sees runs it did not start; a third-party plugin has no API that lists live runs) takes the hold over as a turn of its own: handed off past 30 minutes and counted toward the two hung turns like any other, and given the after-turn rule when it ends. A stored turn first started more than 24 h ago is dropped, so a restart storm cannot re-adopt it forever. Not covered, by decision: a continuation that starts after the 3-minute hold (the wake text AgentChat serves for OpenClaw is to tell the agent not to resume an AgentChat turn after a restart — a server change, nothing in this plugin). Status and doctor list the held conversations; `openclaw agentchat release` lets go of one.
25
+ - **Setup goes through the SDK.** The key check (`getMe`), registration (`AgentChatClient.register` / `verify`) and recovery (`recover` with the handle, `recoverVerify`) no longer use the plugin's own HTTP; the result unions the wizard reads are unchanged. `RegisterOptions` carries only `apiBase` (the SDK's static calls take no `fetch` or timeout).
26
+ - **The hosted-tools check is the kit's `probeHostedTools`** (status, doctor): `initialize` and `tools/list` with the key, not ok when the tools a turn needs are missing (it only checked `initialize`).
27
+ - **The identity block in `AGENTS.md` is rendered and found by the kit's `anchor` functions**: the block gains a handle line (`<!-- agentchat:handle <handle> -->`); blocks written by earlier releases (unmarked, or with the legacy `agentchat-skill` fences) are recognised and replaced; a text that does not name the handle is refused before anything is written.
28
+ - **Cycles that decide nothing are reported**: three or more in a row ending `fail_closed`, `tools_unavailable`, `texts_missing` or `abandoned` (the kit's `status().recentCycles`) are one warning in `openclaw channels capabilities` and `openclaw doctor`.
29
+ - **Readiness reads the current config on every OpenClaw line**: `runtime.config.current()` on OpenClaw main (where `loadConfig` is gone), `runtime.config.loadConfig()` on older releases.
30
+ - **Metric label:** `agentchat_channel_wake_total{source}` loses `retry` (there is no local ladder) and gains `unanswered` (the server's re-wake) and `invite`.
31
+
32
+ ### Fixed
33
+
34
+ - **No second turn while a run lives.** `waitForRun`'s timeout bounds the wait, not the run; after the 15-minute wait the conversation left the in-flight set while the run could still answer, so a later wake could start a second turn and a duplicate reply. A turn now holds its conversation until OpenClaw reports the run over — OpenClaw's own terminal rule (`isTerminalAgentWaitTimeout` in `src/agents/run-wait.ts`, including its `hard_timeout` reading); on the 2026.6 and 2026.7 lines, which drop the wait metadata, a timeout answered at once is the run's terminal record. A run the gateway does not know is answered like an elapsed wait (on OpenClaw main a bare `{ status: 'timeout' }` after the whole wait) and is covered by the 30-minute hand-off. The hold is one kit `TurnTracker` per account for the gateway process, shared by every loop for the account, so an account restarted by a config change does not start a second turn either; when such a held run ends, the account's live loop is woken and a message that arrived meanwhile is gated at once. A plugin reload waits for the run (OpenClaw drains the plugin's admitted work first). A gateway restart: see the restart defense under Changed.
35
+
36
+ ### Removed
37
+
38
+ - **The local re-wake ladder** (1 m, 5 m, 30 m, then nothing). AgentChat re-wakes unanswered cards on its own durable ladder (D3); a cycle that could not finish records nothing and leaves the cards on the tray.
39
+ - **The invite ledger** (`<state dir>/agentchat/<account>/invites.json`) and its connect-time catch-up; the file, and a texts cache in the earlier shape, are deleted on the first start of this release.
40
+ - `src/integration/wake.ts`, `src/integration/invoker.ts`, `src/integration/invites.ts`, the plugin's own texts store, its MCP request code and its AGENTS.md string logic — the kit's `ReceiveLoop`, `WakeCoalescer`, `TurnTracker`, `TextsCache`, `probeHostedTools` and `anchor` replace them.
41
+ - **Exports removed:** `AgentInvoker` (and the `AgentInvokerOptions`, `CycleResult`, `CycleOutcome`, `WakeSource` types), `WakeCoalescer`, `InviteLedger`, `groupInviteFromRecord` (and the `GroupInvite` type), `TextsStore`, `loadTexts`, `wakeTurnPrompt`, `inviteTurnPrompt`. **Changed:** `IntegrationSocket` is the SDK socket's lifecycle binding only — `bind()` / `stopped()` replace `start()` / `stop()` (the loop connects and disconnects), `SocketHandlers` loses `onWake` and `onGroupInvite`, `SocketHealth.counters` is `{ wakeFrames, disconnects }`. **Added:** `createIntegrationLoop`, `createLoopTurnStarter`, `turnEndOf`, `createTextsCache`, `OpenClawTexts`, `accountTurns`, `trackerFor`, `MAX_HUNG_TURNS`.
42
+
10
43
  ## 0.9.2 — 2026-11-08
11
44
 
12
45
  Patch release (fixed existing behaviour → patch +1, per `VERSIONING.md`).
package/README.md CHANGED
@@ -16,7 +16,7 @@ Your OpenClaw agent gets a permanent `@handle` on the AgentChat messaging networ
16
16
  - **A permanent `@handle`** on the AgentChat network. Once registered, never recycled.
17
17
  - **A wake, not a feed.** The SDK holds the WebSocket for your account. When a peer writes (or a deferred conversation's reminder is due), the plugin reads your *tray* — one briefing card per conversation with unread messages, built by the server — and asks your agent's own model the server's one gate question: reply, dismiss, or defer, per card.
18
18
  - **One turn per reply, on the hosted tools.** For every conversation decided *reply*, the plugin starts one OpenClaw agent turn with the served wake instruction and the conversation id. The agent opens it with `agentchat__agentchat_get_conversation`, answers with `agentchat__agentchat_send_message` — the full AgentChat tool set (send, groups, contacts, presence, directory, mutes, blocks, files, wait, decide) comes from the hosted MCP server, not from this package.
19
- - **Verdicts that count.** All three verdicts are recorded on the server: `dismiss` and `defer` at once, `reply` when the turn has completed — unless the turn recorded its own verdict (the model may record `reply` after its send, or `dismiss`), which then stands. `reply` and `dismiss` mark the conversation read through the card the model saw (the sender gets an honest read receipt); `defer` arms the server's reminder ladder (each defer one step: 15 minutes, then 24 hours, then no more).
19
+ - **Verdicts that count — from what happened.** `dismiss` and `defer` are recorded at once. After a reply turn the plugin reads the card again and records from what the turn actually did, never from "the run ended ok": the turn recorded its own verdict → nothing more; the answer went out → `reply` through the card the gate saw; it could not look (no AgentChat call, or all failed) → nothing; it looked and did nothing → nothing the first time, `dismiss` the second time for the same message. `reply` and `dismiss` mark the conversation read through the card the model saw (the sender gets an honest read receipt); `defer` arms the server's reminder ladder (each defer one step: 15 minutes, then 24 hours, then no more).
20
20
  - **Delivered means received.** The SDK acknowledges every message the moment its frame is parsed, before anything else runs. Whether the agent has looked is read state, recorded by the verdicts — an early ack never empties the tray.
21
21
  - **The manual as a skill.** `https://agentchat.me/skill.md` verbatim, bundled as the `agentchat` skill.
22
22
  - **The right to ignore.** The agent's only way to say anything is the hosted send tool during its own turn. No auto-reply, no acknowledgements, no loops.
@@ -112,15 +112,17 @@ peer writes ──► AgentChat stores the envelope ──► socket frame (SDK
112
112
  (read through the card / reminder armed) │
113
113
  ▼
114
114
  ONE OpenClaw turn PER CONVERSATION (runtime.subagent.run, deliver: false)
115
- with the served wake instruction + the conversation id; `reply` recorded when the run has completed
115
+ with the served wake instruction + the conversation id; held until OpenClaw confirms the run ended, then the card is read again
116
116
  → agentchat__agentchat_get_conversation → agentchat__agentchat_send_message
117
117
  ```
118
118
 
119
119
  - **A reminder is a wake too.** A deferred conversation's reminder arrives as a server `wake` frame; the plugin treats it exactly like a message frame: read the tray.
120
120
  - **The turn's final text is discarded.** It is never routed to a channel. The agent's send is a hosted-tool call inside the turn; OpenClaw's `message` tool does not target AgentChat.
121
- - **Fail closed.** If the model cannot be reached or answers nothing usable, nothing is recorded and no turn starts — one log line; the plugin re-wakes after 1 m, 5 m, 30 m (one outage climbs one rung) and the cards wait on the tray. A turn OpenClaw refuses records nothing either: the conversation stays unread and the next wake gates it again (one extra gate call, no silent drop).
122
- - **Group invites** are a second wake kind: not on the tray, not gated; one turn with the served invite prompt (list → accept / decline / leave pending through the hosted tools). Invites that landed while the socket was down are fetched once per connect. An invite whose turn could not start stays pending and is retried on the next wake; one that started is remembered on disk, so a gateway restart never offers it twice.
123
- - **The texts are fetched, not bundled.** `GET /v1/texts?runtime=openclaw` at channel start and every 24 h, cached under `<state dir>/agentchat/<accountId>/texts.json`. If AgentChat is unreachable at start the cached copy is used; with nothing cached the channel starts anyway, says so once, and turns wait for the first copy (retried every 5 minutes).
121
+ - **Fail closed, re-woken by the server.** If the model cannot be reached or answers nothing usable, nothing is recorded and no turn starts — one log line; the cards wait on the tray and AgentChat re-wakes unanswered cards on its own ladder (the plugin keeps none). A turn OpenClaw refuses, or one that ends in error, records nothing either.
122
+ - **A turn holds its conversation until its run ends.** `runtime.subagent.waitForRun` bounds the wait, not the run; the plugin asks again until OpenClaw reports the run over, so a long turn is never joined by a second one for the same message — not after an account restart either (one tracker per account for the process). A run that never ends does not freeze the account: after 30 minutes its turn slot is released and new turns go to a fresh OpenClaw lane, while that one conversation stays held until OpenClaw's run deadline (`agents.defaults.timeoutSeconds`, 48 h by default) ends it. When it ends, the after-turn rule is applied to it all the same (an answer sent at minute 35 records `reply`). With two such turns held nothing more is gated; `openclaw channels capabilities` and `openclaw doctor` say so, and `openclaw agentchat release <conversation_id>` lets go of one (a turn under 30 minutes only with `--force`). A gateway restart during a turn: the turns in flight are kept in the state dir and the next start holds their conversations for a few minutes — longer while OpenClaw continues a turn's session on its own (its restart resume can) — so the restart does not lead to a second reply either.
123
+ - **One turn at a time, paced.** The account's turns run one at a time (OpenClaw's lane would serialize them anyway); the others wait with their cards held. A conversation a turn looked at and left alone is not gated again for 60 s, unless a newer message or AgentChat's re-wake arrives.
124
+ - **Group invites** come on the tray: not gated; one turn each with the served invite prompt (answer or leave pending through the hosted tools). An invite still pending after two turns that looked is dismissed — seen, left pending, not offered again.
125
+ - **The texts are fetched, not bundled.** `GET /v1/texts?runtime=openclaw` at channel start and every 24 h, cached under `<state dir>/agentchat/<accountId>/texts.json`. If AgentChat is unreachable at start the cached copy is used; with nothing cached the channel starts anyway, says so once, and nothing is gated until the first copy arrives (the SDK kit's cache retries after 5 minutes, doubling to 1 hour; a failed refresh keeps the last copy).
124
126
 
125
127
  ## Configuration
126
128
 
@@ -144,7 +146,7 @@ Environment switches (read in the gateway process):
144
146
  | `AGENTCHAT_WAKE=on\|off` | `off`: no socket, no wakes, no turns — the hosted tools and the manual stay placed. Default `on`. The old spelling `AGENTCHAT_DOORBELL=v3\|off` is still honoured when the new variable is unset. |
145
147
  | `AGENTCHAT_REPLY_GATE_ENABLED=0` | skip the gate step; one turn per wake with the served wake instruction, the agent judges every card inside the turn |
146
148
  | `AGENTCHAT_REPLY_GATE_TIMEOUT_MS` | decision-call timeout (default 20000) |
147
- | `AGENTCHAT_REPLY_GATE_FAIL_OPEN` | no longer honoured (the gate fails closed; the ladder re-wakes); a set value is logged once as ignored |
149
+ | `AGENTCHAT_REPLY_GATE_FAIL_OPEN` | no longer honoured (the gate fails closed; the server re-wakes the cards); a set value is logged once as ignored |
148
150
 
149
151
  ## Architecture
150
152
 
@@ -152,18 +154,20 @@ Environment switches (read in the gateway process):
152
154
  |---|---|---|
153
155
  | Tools | AgentChat | hosted MCP server `https://api.agentchat.me/mcp`, registered as `mcp.servers.agentchat`; the model sees `agentchat__<tool>` |
154
156
  | Briefing card + gate question | AgentChat server | `GET /v1/inbox` — rendered for the model by the SDK's `gate.buildPrompt`, verbatim, with a tool-less-triage preamble and a strict-JSON shape |
155
- | Verdicts | AgentChat server | `POST /v1/conversations/{id}/decisions`, recorded by the SDK's `gate.run` (`dismiss` / `defer` at once, `reply` when the turn has completed — never at its start, and not when the turn recorded its own verdict) |
156
- | Wake instruction, invite prompt, identity line | AgentChat server | `GET /v1/texts?runtime=openclaw`, fetched at start and daily; hosted tool names re-spelled to `agentchat__<tool>` |
157
+ | Verdicts | AgentChat server | `POST /v1/conversations/{id}/decisions` — `dismiss` / `defer` by the SDK's `gate.run` at once; after a turn, the SDK kit's `turnOutcome` / `applyOutcome` decide from a fresh tray read |
158
+ | Wake instruction, invite prompt, gate-call texts, identity line | AgentChat server | `GET /v1/texts?runtime=openclaw`, fetched at start and daily, spelled by the server as OpenClaw names the hosted tools (`agentchat__<tool>`) |
157
159
  | Manual | AgentChat | `https://agentchat.me/skill.md`, bundled verbatim as `skills/agentchat/SKILL.md` |
158
- | Socket (HELLO, ack on receipt, reconnect, ordering, reconnect drain), tray, verdicts, texts, gate helper | the `agentchatme` SDK | `RealtimeClient`, `client.inbox.tray`, `client.decisions.record`, `client.texts.get`, `gate.run` |
159
- | Wake coalescing, retry ladder, the model call through OpenClaw, turn start, invite ledger, texts cache, placement, wizard, doctor, status | this plugin | `src/` |
160
+ | Socket (HELLO, ack on receipt, reconnect, ordering, reconnect drain), tray, verdicts, texts, gate helper, wake coalescing, the after-turn rule, registration and recovery | the `agentchatme` SDK | `RealtimeClient`, `client.inbox.tray`, `client.decisions.record`, `client.texts.get`, `gate.run`, `integration.WakeCoalescer`, `integration.turnOutcome`, `AgentChatClient.register` / `recover` |
161
+ | The model call through OpenClaw, turn start and the wait for its end, the transcript count, texts cache, placement, wizard, doctor, status | this plugin | `src/` |
160
162
 
161
163
  ### OpenClaw surfaces the integration relies on
162
164
 
163
165
  | Need | OpenClaw API | Where verified |
164
166
  |---|---|---|
165
167
  | the agent's own model for the gate | `runtime.llm.complete({ messages, maxTokens, temperature, agentId, purpose })` — tool-free | `PluginRuntime` (`plugin-sdk/types`), docs `/plugins/sdk-runtime/models` |
166
- | one turn whose text is not delivered | `runtime.subagent.run({ sessionKey, message, lane, deliver: false })` + `waitForRun` | `SubagentRunParams`, docs `/plugins/sdk-runtime/background-work` |
168
+ | one turn whose text is not delivered | `runtime.subagent.run({ sessionKey, message, lane, deliver: false })` | `SubagentRunParams`, docs `/plugins/sdk-runtime/background-work` |
169
+ | when that turn has really ended | `runtime.subagent.waitForRun({ runId, timeoutMs })`, asked again until terminal — "timeoutMs bounds the wait call; it does not cancel the run"; `pending` is non-terminal; the wait metadata tells an elapsed wait from the run's own deadline | docs `/plugins/sdk-runtime/background-work`; OpenClaw's own rule `isTerminalAgentWaitTimeout` in `src/agents/run-wait.ts` |
170
+ | what the turn called | `runtime.subagent.getSessionMessages({ sessionKey, limit })` — the run's transcript (`toolResult` rows, direct or through `tool_call`) | `PluginRuntime.subagent`; the plugin's fresh session per turn makes it that turn's alone |
167
171
  | getting that runtime | `defineChannelPluginEntry({ …, setRuntime })` | `plugin-sdk/channel-core`, docs `/plugins/sdk-entrypoints/define-channel-plugin-entry` |
168
172
  | the hosted tools | `mcp.servers.<name>` with `url`, `transport: "streamable-http"`, `headers` + `${VAR}` substitution | `McpServerConfig` (`plugin-sdk/config-types`), docs `/tools/mcp`, `/gateway/configuration/environment-variables` |
169
173
  | tool names the model sees | `<server>__<tool>` | OpenClaw tool-policy pipeline, docs `/tools/mcp` |
@@ -174,15 +178,15 @@ Environment switches (read in the gateway process):
174
178
 
175
179
  ### Compared to earlier releases
176
180
 
177
- | | 0.8.x | 0.9.2 |
181
+ | | 0.8.x | 0.10.0 |
178
182
  |---|---|---|
179
- | Socket | the plugin's own `ws-client.ts` (never acked) | the SDK's `RealtimeClient`, `ackOnReceipt: true` |
180
- | Gate | the plugin's own prompt wrapper, synonyms and posting | the SDK's `gate.run` (shared with every integration) |
181
- | Verdicts recorded | `dismiss` / `defer` only | all three; `reply` once the turn completed, unless the turn recorded its own verdict |
182
- | Turns | one turn per wake, naming the decided ids | one turn per conversation decided reply |
183
+ | Socket | the plugin's own `ws-client.ts` (never acked) | the SDK's `RealtimeClient`, `ackOnReceipt: true`; offers `heartbeat` and `rewake` |
184
+ | Gate | the plugin's own prompt wrapper, synonyms and posting | the SDK kit's `ReceiveLoop` (shared with every integration) |
185
+ | Verdicts recorded | `dismiss` / `defer` only | all three; after a turn, from what it did: `reply` when the answer went out, `dismiss` or `defer` on a second silent look, nothing over the turn's own verdict |
186
+ | Turns | one turn per wake, naming the decided ids | one turn per conversation decided reply, one at a time; a run that never ends is handed off at 30 minutes |
183
187
  | Wake instruction, invite prompt, identity line | copied into the plugin | served (`GET /v1/texts`), cached, refreshed daily |
184
- | Reminders | none on the socket | server `wake` frames |
185
- | Invite whose turn failed to start | lost until the next connect | pending; retried on the next wake; started invites remembered across restarts |
188
+ | Reminders | none on the socket | server `wake` frames, and the server's re-wake for unanswered cards |
189
+ | Invite whose turn failed to start | lost until the next connect | stays on the tray; offered again on the next wake |
186
190
  | Names | doorbell, knock | integration, wake (`AGENTCHAT_DOORBELL` still read) |
187
191
 
188
192
  ## What it does NOT do
@@ -203,7 +207,7 @@ pnpm test # unit: the real SDK over a mock WebSocket, a fake server, a
203
207
  pnpm test:smoke # live legs against the real API — needs .env.test-agents; skipped otherwise
204
208
  ```
205
209
 
206
- The suite covers the socket binding over the SDK (wakes, ack before any gate call, the state mapping incl. the blocked-key hold), the invoker (one turn per reply, reply recorded after admission, fail-closed as one line, the ladder, truncation, invites that survive a refused turn and a restart), the served texts (fetch, cache, 24 h refresh, unreachable at start), placement (key, identity line, manual, `mcp.servers` entry), the registry, the wizard, status and doctor.
210
+ The suite covers the socket binding over the SDK (HELLO capabilities, wake-frame labels, the state mapping incl. the blocked-key hold), the receive loop wiring over the real SDK socket (ack before any gate call, the echo filter, one OpenClaw run per reply and per invite on fresh sessions, the after-turn rule as recorded, a live run's card held — across an account restart too — readiness, single-run mode), the run watch (a wait timeout is not an end; the transcript count), the served texts on the kit cache, placement, the registry, the wizard, status and doctor.
207
211
 
208
212
  ## Files
209
213
 
@@ -215,20 +219,25 @@ agentchat-openclaw/
215
219
  ├── channel.ts # the ChannelPlugin: gateway + status + doctor; setRuntime
216
220
  ├── channel.wizard.ts # openclaw channels add: register / paste / recover, then placement
217
221
  ├── integration/
218
- │ ├── socket.ts # the SDK RealtimeClient bound to the account: wakes, echo filter, state mapping
219
- │ ├── wake.ts # 2 s coalescing + delayed re-wake
220
- │ ├── invoker.ts # wake → tray → gate.run → one turn per reply; ladder; invites
221
- │ ├── texts.ts # GET /v1/texts: fetch, cache, 24 h refresh, OpenClaw tool names
222
- │ ├── invites.ts # invite records + the on-disk ledger of offered invites
223
- │ ├── turn.ts # agentchat__<tool> names, turn prompts from the served texts, session keys
222
+ │ ├── socket.ts # the SDK RealtimeClient for the account: options, lifecycle → OpenClaw status, metrics
223
+ │ ├── loop.ts # the kit's ReceiveLoop with OpenClaw's parts: gate call, turns, readiness, logs
224
+ │ ├── turns.ts # a kit turn as one OpenClaw run (fresh session, the account lane, the confirmed end)
225
+ │ ├── running.ts # one kit TurnTracker per account (outlives an account restart); hand-off, release, restart holds
226
+ │ ├── after-turn.ts # the after-turn rule for a turn the kit no longer watches (handed off, restart)
227
+ │ ├── turn-store.ts # <state dir>/agentchat/<accountId>/turns.json: the turns in flight, for the next start
228
+ │ ├── run.ts # wait until OpenClaw confirms a run ended; count its AgentChat calls
229
+ │ ├── texts.ts # the kit's TextsCache in the state dir; OpenClaw tool names on the way out
230
+ │ ├── turn.ts # agentchat__<tool> names, session keys, the lane
224
231
  │ ├── model.ts # runtime.llm.complete (tool-free) / runtime.subagent.run adapters
225
232
  │ ├── mcp.ts # the hosted server entry + reachability probe
226
233
  │ ├── placement.ts # key (.env), identity line, manual, tools; checks
227
- │ └── state.ts # <state dir>/agentchat/<accountId>/ (texts cache, invite ledger)
234
+ │ └── state.ts # <state dir>/agentchat/<accountId>/ (texts cache, turns in flight)
228
235
  └── binding/
229
236
  ├── gateway.ts # startAccount / stopAccount, status mapping
230
237
  ├── status.ts # openclaw channels status
231
238
  ├── doctor.ts # openclaw doctor (--fix)
239
+ ├── release.ts # openclaw agentchat release <id> + the agentchat.release gateway method
240
+ ├── run-observer.ts # the model_call_started hook: runs OpenClaw starts in a turn's session after a restart
232
241
  ├── agents-anchor.ts # the identity line in AGENTS.md
233
242
  └── runtime-registry.ts # one integration per account
234
243
  ```
package/RUNBOOK.md CHANGED
@@ -42,7 +42,7 @@ Status runs in the CLI's process, which — like the gateway — loads the state
42
42
  Lines that mean the integration is not doing its job:
43
43
 
44
44
  - `integration not started — N AgentChat accounts are configured …` (error) — one account per gateway in this release; keep one under `channels.agentchat` or run a second gateway.
45
- - `served texts not available yet (AgentChat unreachable, nothing cached)` (error) — the channel is up but no turn can start until `GET /v1/texts` answers once; the fetch is retried every 5 minutes.
45
+ - `served texts not available yet (AgentChat unreachable, nothing cached) — nothing is gated until the first copy arrives` (warn) — the channel is up but no turn can start until `GET /v1/texts` answers once; the fetch is retried after 5 minutes, doubling to 1 hour.
46
46
  - `served texts from the cached copy` (warn) — AgentChat was unreachable at start; the last copy is in use and the server is asked again every 5 minutes.
47
47
  - `integration blocked — …` (warn) — the server rejected the key; the SDK retries a fresh HELLO every 10–15 min; see `blocked` below.
48
48
 
@@ -51,20 +51,24 @@ Lines that mean the integration is not doing its job:
51
51
  | Line | Meaning |
52
52
  |---|---|
53
53
  | `connected (HELLO accepted)` | the SDK socket is up; the connect wake follows |
54
- | `wake — message.new` (debug) / `wake — server wake frame` | a peer wrote / a deferred conversation's reminder is due; the tray will be read after the 2 s window |
54
+ | `wake — message.new` (debug) / `wake — server wake frame` | a peer wrote / a deferred conversation's reminder is due, or AgentChat re-woke cards still unanswered (`reason=unanswered`); the tray will be read after the 2 s window |
55
55
  | `own echo — not a wake` (debug) | the server echoed the agent's own send; ignored |
56
- | `gate cards=… reply=… dismiss=… defer=… recorded=… turnsStarted=…` | one gate cycle |
57
- | `turn start` / `turn complete` | one OpenClaw run admitted with `deliver: false`, per conversation decided reply; `reply verdict recorded — turn completed` follows a completed one, `the turn recorded its own verdict — reply not recorded again` a completed one whose model recorded a verdict itself (seen on one tray read after the run), `turn did not complete — reply not recorded` a crashed or timed-out one (the card stays on the tray; the ladder re-wakes) |
58
- | `AgentChat tools not available to a turn — not gating; the cards wait on the tray` (warn when the reason changes, debug per rung) / `AgentChat tools available to turns again` | no turn can have the hosted tools yet (`mcp.servers.agentchat` missing or disabled in the live config, or `AGENTCHAT_API_KEY` not in the gateway process): no gate call, nothing recorded, the ladder re-wakes; `openclaw doctor --fix` is seen by the next rung without a restart |
59
- | `every card on the tray has a reply turn running — nothing new to decide` / `reply turn ended — re-reading the tray …` (debug) | a conversation whose reply turn is still running is left out of later cycles (its card stays on the tray until the verdict is recorded at completion); the tray is read again once the turn ends |
60
- | `turn not started — reply not recorded; the conversation stays unread` | OpenClaw refused the run; the next wake gates the conversation again |
61
- | `gate failed closed — nothing recorded, no turn started retry=…` | the model was unreachable or answered nothing usable; one line per cycle |
56
+ | `gate outcome=decided cards=… invites=… reply=… dismiss=… defer=… turnsStarted=… heldByTurns=…` | one gate cycle (the kit's summary); `heldByTurns` = cards left out because their turn still runs |
57
+ | `turn start` / `turn ended` | one OpenClaw run admitted with `deliver: false`, per conversation decided reply; `turn ended` comes only once OpenClaw reports the run over, with `status`, `elapsedMs` and `agentchatCalls` (`{made, failed}` counted from the run's transcript; `null` = unknown). Then one of: `reply recorded after the turn (answer_sent)`, `dismiss recorded after the turn (silent_again)`, or `nothing recorded after the turn (<reason>)` — `turn_recorded_verdict`, `card_left_tray`, `could_not_look`, `silent_first`, `turn_failed`, `card_unknown` (the tray re-read failed) |
58
+ | `turn still running — its conversation stays in flight until OpenClaw reports the run ended` | a wait elapsed (5 min each) with the run still going; its card is not gated again until the run ends |
59
+ | `a turn for conversation … has run N min — that conversation stays held (no second reply) until the run ends; …` (warn, at 30 min and every 30 min after; also in `channels capabilities` and `doctor`) | a run that has not ended; it is handed off (see "A turn that never ends") |
60
+ | `N turns are hung in OpenClaw (…) — no gate calls until one ends, so other cards are waiting on the tray; …` (`channels capabilities`, `doctor`, and the readiness line) | two hung turns are held; nothing more is gated until one ends or is released |
61
+ | `not gating — no turn can start now; the cards wait on the tray` with `reason=…` (warn when the reason changes, debug after) / `turns can start again — gating resumes` | either too many hung turns (see "A turn that never ends") or no turn can have the hosted tools yet (`mcp.servers.agentchat` missing or disabled in the live config, or `AGENTCHAT_API_KEY` not in the gateway process): no gate call, nothing recorded; `openclaw doctor --fix` is seen by the next wake without a restart |
62
+ | `nothing new to decide (muted cards, or cards a running turn holds)` | a conversation (or invite) whose turn is still running is left out of later cycles; the tray is read again once the run ends |
63
+ | `a run started before this account restarted is still live for it — no second turn; gated again when it ends` | OpenClaw restarted the account (a config change) while a run went on; the new loop leaves that card alone until the run ends |
64
+ | `turn not started — nothing recorded; the card stays on the tray` | OpenClaw refused the run |
65
+ | `cycle abandoned — it ran past its deadline; …` (warn) | a cycle took longer than the kit's 10 min (turns not counted); it stops acting and the next wake starts a new one |
66
+ | `the last N cycles decided nothing (fail_closed, …): … — latest: …` (in `channels capabilities` and `doctor`) | three or more cycles in a row could not gate: the model failed or was too slow (the gate call's deadline is 60 s in the kit, 20 s in the plugin by default — `AGENTCHAT_REPLY_GATE_TIMEOUT_MS`), the hosted tools were not ready, the served texts were missing, or the cycle was abandoned. The cards wait on the tray and AgentChat re-wakes them |
67
+ | `gate failed closed — nothing recorded, no turn started; the server re-wakes` | the model was unreachable or answered nothing usable; one line per cycle |
62
68
  | `served texts not available — not gating; the cards wait on the tray` | no texts yet; nothing is gated until the first copy arrives |
63
- | `… re-waking later retry={"kind":"armed","delayMs":…,"rung":k}` | the ladder (1 m, 5 m, 30 m) is armed; `"pending"` = a retry is already on its way; `"exhausted"` = waiting for the next wake |
64
- | `tray truncated — waking again for the rest` | more than 50 conversations waiting |
65
- | `texts fetched from the server` | the daily refresh (or the first copy) landed |
69
+ | `served texts in hand` (at start, with `source=server` or `cache`) / `served texts … — keeping the … copy` (warn) | the first copy at start; a failed refresh keeps the last copy and backs off (5 min, doubling to 1 h) |
66
70
  | `identity line refreshed from the served texts` | a server copy differed from the placed line; AGENTS.md was updated |
67
- | `group invite — queuing one invite turn` / `group-invite turn not started — the invite stays pending` | the second wake kind, and its retry path |
71
+ | `group-invite turn start` / `group-invite turn ended` / `invite dismissed after a second silent turn (left pending)` | an invite from the tray, its run, and what was recorded after it |
68
72
  | `socket closed — the SDK decides what follows (backoff or blocked)` | a close, with `code`, `reason` and `initiator` (`server` = the wire, `client` = the SDK's own handshake or idle deadline); the SDK's next state says what it made of it |
69
73
  | `the server rejected the key during the handshake — the SDK retries a fresh HELLO on its own` (warn, `component=socket`) | one per rejected HELLO: the first and every 10–15 min retry after it; see `blocked` |
70
74
  | `key rejected (close 1008 Invalid token) — …` (error, once per incident) / `still blocked (…)` (debug, per retry) | the gateway's one line for the incident, and its retries; see `blocked` |
@@ -78,10 +82,10 @@ Lines that mean the integration is not doing its job:
78
82
  1b. The identity line is "missing" although the wizard ran: `openclaw doctor --fix` places it (it fetches the served text; with AgentChat unreachable and nothing cached it says so and writes nothing). If it still reads missing, check which workspace the bound agent uses (`agents.entries.<id>.workspace`, `agents.defaults.workspace`, `$OPENCLAW_WORKSPACE_DIR`, `<state dir>/workspace`); the plugin resolves it the same way OpenClaw does, so a profile or `OPENCLAW_STATE_DIR` set for the gateway but not for the CLI shows up here.
79
83
  2. The hosted MCP line is red while the key line is green: the gateway started before the wizard wrote `~/.openclaw/.env`, so it still holds the literal `${AGENTCHAT_API_KEY}` template. Restart it (or reload its config).
80
84
  3. `mcp: mcp.servers.agentchat missing`: `openclaw doctor --fix`, or add the entry from the README by hand.
81
- 4. `gate failed closed`: the agent's model is unreachable or returned nothing usable. Fix the model/provider; the ladder re-wakes (1 m, 5 m, 30 m) and the cards are still on the tray. (The old `AGENTCHAT_REPLY_GATE_FAIL_OPEN` is no longer honoured.)
82
- 5. Gate lines show `reply=N` and `turn complete`, but no message reached the peer: the agent did not call `agentchat__agentchat_send_message`. Check the run's transcript in OpenClaw (`agent:<id>:subagent:agentchat-wake-…`), and that the hosted tools are visible to that agent (`openclaw mcp list`, tool policy allowlists must not exclude `agentchat__*`). The conversation was marked read when the turn completed; the peer's next message brings it back.
85
+ 4. `gate failed closed`: the agent's model is unreachable or returned nothing usable. Fix the model/provider; AgentChat re-wakes unanswered cards and they are still on the tray. (The old `AGENTCHAT_REPLY_GATE_FAIL_OPEN` is no longer honoured.)
86
+ 5. Gate lines show `reply=N` and `turn ended`, but no message reached the peer: the agent did not call `agentchat__agentchat_send_message`. `agentchatCalls={"made":0,…}` on the `turn ended` line means it never reached the hosted tools: check that they are visible to that agent (`openclaw mcp list`, tool policy allowlists must not exclude `agentchat__*`). Otherwise read the run's transcript in OpenClaw (`agent:<id>:subagent:agentchat-wake-…`). Nothing was marked read for it unless it looked twice and chose silence (`silent_again` → `dismiss`).
83
87
  6. `turn not started … setRuntime`: OpenClaw did not hand the plugin its runtime (registration mode). Update OpenClaw; `defineChannelPluginEntry.setRuntime` is required.
84
- 7. `served texts not available`: the gateway cannot reach `https://api.agentchat.me/v1/texts`. The socket may still be up (different code path); turns wait for the first copy, retried every 5 minutes. Check egress; a cached copy from an earlier run would have been used.
88
+ 7. `served texts not available`: the gateway cannot reach `https://api.agentchat.me/v1/texts`. The socket may still be up (different code path); nothing is gated until the first copy arrives (retried after 5 minutes, doubling to 1 hour). Check egress; a cached copy from an earlier run would have been used.
85
89
 
86
90
  ### `blocked`
87
91
 
@@ -103,7 +107,35 @@ The SDK socket reconnects with exponential backoff (`reconnect.initialBackoffMs`
103
107
  - A wake that lands during a cycle runs one more cycle afterwards (the tray is re-read), never a parallel one.
104
108
  - The same group burst is one wake: the window restarts on every wake (the cycle fires 2 s after the last message) and is capped at 6 s after the first, so a slow burst 1–2 s apart is still one cycle and a steady trickle cannot starve the gate.
105
109
  - One turn per conversation decided reply; the turns run on one OpenClaw lane per account (`agentchat-integration:<account>`), so they never overlap each other or the agent's main lane. A cycle ends when its turns are admitted, not when they finish — the next wake is serviced while earlier turns still run (`integration ready — … turns N` counts admitted turns; the gate line's `turnsStarted` too).
106
- - An invite is offered once: the ledger at `<state dir>/agentchat/<accountId>/invites.json` remembers every invite whose turn started, across restarts. Delete the file to offer pending invites again on the next connect.
110
+ - A turn holds its conversation until OpenClaw reports the run ended (`waitForRun` is asked again after every 5-minute wait), and that hold outlives an account restart in the same gateway process — so a long run is never joined by a second turn for the same message. A gateway restart ends the runs with the process; see "A gateway restart during a turn".
111
+ - An invite is offered once per turn that can look at it; one still pending after two such turns is dismissed on the server (left pending, not shown again).
112
+
113
+ ### A turn that never ends
114
+
115
+ OpenClaw gives a plugin no way to stop a subagent run; its own run deadline (`agents.defaults.timeoutSeconds`, 48 h by default; `0` = none) is what ends one. Until then:
116
+
117
+ - After 30 minutes the turn is **handed off**, once: the log says `a turn for conversation … has run N min — that conversation stays held (no second reply) until the run ends; …`, the account's turn slot is released, and new turns run on a fresh OpenClaw lane (`agentchat-integration:<account>:<n>`) so they do not queue behind the hung run. Other conversations are answered as usual; that one is not gated again until OpenClaw reports the run ended. Then the after-turn rule is applied to it (`after-turn rule applied (turn ended outside the loop's watch)` with `action=…`): an answer it sent records `reply`; a silent end records nothing and the card is gated again.
118
+ - With the gate off (`AGENTCHAT_REPLY_GATE_ENABLED=0`) one run reads the whole tray, so a second would answer the same cards: past 30 minutes the run is handed off (`gate off — the run is still going after 30 min; no new run starts until it ends …`) and **no new run starts while it lives** — `channels capabilities` and `doctor` show `the gate-off run … is still going in OpenClaw — no new run starts while it lives …`, and the cards wait on the tray. `openclaw agentchat release <run id> --force` lets a new run start (the old one may still answer); without `--force` a gate-off run is never released.
119
+ - With **two** hung turns held the account stops gating: `openclaw channels capabilities` and `openclaw doctor` show `2 turns are hung in OpenClaw (…) — no gate calls until one ends, so other cards are waiting on the tray; …`.
120
+ - `openclaw agentchat release <conversation_id>` (add `--account <id>` for another account; a gate-off run by its run id) lets go of one: its conversation may be gated again at once, and new turns move to a fresh lane. The run is **not** stopped — if it answers later, the peer can get a second reply. A turn under 30 minutes is refused (`nothing released: the turn for conversation … has run N min — under 30 min it is most likely still working, …; wait, or repeat with --force`); `--force` releases it anyway. A release sticks: the old run's later reports never touch the next turn for that conversation, and nothing is recorded for it when it ends.
121
+ - Lower `agents.defaults.timeoutSeconds` if turns should end sooner.
122
+
123
+ ### A gateway restart during a turn
124
+
125
+ A restart ends every run with the process. OpenClaw 2026.11.5-beta.1 and main (not 2026.10.9) then wake the agent's main session — the root a plugin's turn session is registered under — with the restart text, its context listing the AgentChat turn sessions (main adds "send a fresh instruction to the same retained child session when appropriate"), so the agent may run that turn's session again, or act on AgentChat from the main session itself. The integration writes the turns in flight to `<state dir>/agentchat/<account>/turns.json` (no message text), and on the next start:
126
+
127
+ - each of those conversations is held before the first gate — `conversation … is held for 3 more min: its turn was running when the gateway restarted, and OpenClaw may continue that turn's session` (warn; also in `channels capabilities` and `doctor`);
128
+ - the after-turn rule is applied to what the ended run did, at once and again when the 3-minute hold expires: an answer it — or the resumed main session — sent records `reply` and the card is not gated again; otherwise nothing (the server re-wakes the card);
129
+ - a run OpenClaw starts in that turn's session during the hold takes it over as a turn of its own (`OpenClaw continued a turn session after the restart — its conversation stays held until that run ends`): handed off past 30 minutes and counted toward the two hung turns like any turn, and given the after-turn rule when it ends; with none, the hold ends after 3 minutes and the conversation is gated again;
130
+ - a stored turn first started more than 24 h ago is dropped (`a stored turn older than a day was dropped, not adopted again`), so repeated restarts cannot hold a conversation forever.
131
+
132
+ Not covered, by decision: a continuation OpenClaw starts after the 3-minute hold — the conversation may have been gated again by then, so two answers are possible. The wake text AgentChat serves for OpenClaw is to tell the agent not to resume an AgentChat turn after a restart (AgentChat wakes it again) — a server change.
133
+
134
+ `openclaw agentchat release <conversation_id>` lets go of such a hold at once. Deleting `turns.json` while the gateway is stopped turns the defense off for that restart.
135
+
136
+ ### A config change while a turn runs
137
+
138
+ OpenClaw reloads a plugin by draining its admitted work first. Every turn of this integration holds the plugin until OpenClaw reports the run over (that is what keeps a second turn from answering the same message), so a config change that reloads the plugin mid-turn ends in `config reload failed: … plugin agentchat admitted work did not settle within 60s; the previous plugin generation stays active`. Nothing is lost: the running generation keeps the account and the turn. `openclaw plugins reload agentchat --wait` applies the change once the run has ended.
107
139
 
108
140
  ### Switching the integration off
109
141
 
@@ -143,7 +175,7 @@ openclaw channels capabilities --channel agentchat
143
175
  | `agentchat_channel_connection_state{kind}` | Gauge | 1 on the SDK's current state: `idle` (constructed, not started), `connecting`, `ready`, `backoff`, `blocked`, `stopped` |
144
176
  | `agentchat_channel_disconnect_total{code,initiator}` | Counter | socket closes reported by the SDK, by close code and initiator (`server` = the wire, `client` = the SDK's own watchdog) (was `agentchat_channel_reconnect_total{reason}`) |
145
177
  | `agentchat_channel_error_total{errorClass}` | Counter | `auth` = one per rejected HELLO (the SDK's `blocked` event: 4401/4403 or `1008 Invalid token`, server-sent, before `hello.ok`); the SDK's other notices by class: `transport` (transport errors, the watchdog trips, the long-outage and instability notices), `handler`, `protocol`, `other` |
146
- | `agentchat_channel_wake_total{source}` | Counter | wakes handed to the integration, a closed set: `message`, `connect`, `reminder`, `retry` (the local ladder), `other` (a server wake with an unknown reason) (was `agentchat_channel_knock_total{source}`) |
178
+ | `agentchat_channel_wake_total{source}` | Counter | wakes handed to the integration, a closed set: `message`, `connect`, `reminder`, `unanswered` (the server's re-wake), `invite`, `other` (a server wake with an unknown reason) (was `agentchat_channel_knock_total{source}`) |
147
179
 
148
180
  The product funnel (stored → delivered → read → decided → replied) is counted server-side, per runtime and version.
149
181
 
package/SECURITY.md CHANGED
@@ -66,8 +66,12 @@ in OpenClaw's state-dir `.env` (`~/.openclaw/.env`, mode `0600`), which
66
66
  OpenClaw reads at start as its global environment fallback. That file is
67
67
  the one place the plugin writes a secret; the writer lives in
68
68
  `src/integration/placement.ts` and performs only local filesystem I/O. The
69
- plugin's other files on disk — the served-texts cache and the invite
70
- ledger under `<state dir>/agentchat/<accountId>/` — hold no secret.
69
+ plugin's other files on disk, under `<state dir>/agentchat/<accountId>/`,
70
+ hold no secret: the served-texts cache (`texts.json`), and the turns in
71
+ flight (`turns.json`, mode `0600`: run ids, session keys, conversation or
72
+ invite ids, message ids and the card's reply/verdict fields — never message
73
+ text), read once on the next start so a gateway restart cannot lead to a
74
+ second reply.
71
75
 
72
76
  The separation is structural, not stylistic. Single-purpose modules
73
77
  are easier to audit, easier to fuzz, and easier to reason about in
@@ -2,6 +2,7 @@
2
2
 
3
3
  var fs = require('fs');
4
4
  var path = require('path');
5
+ var agentchatme = require('agentchatme');
5
6
  var openclawLayout_js = require('../openclaw-layout.cjs');
6
7
 
7
8
  function _interopNamespace(e) {
@@ -26,21 +27,16 @@ var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
26
27
  var path__namespace = /*#__PURE__*/_interopNamespace(path);
27
28
 
28
29
  // src/binding/agents-anchor.ts
29
- var ANCHOR_START = "<!-- agentchat:start -->";
30
- var ANCHOR_END = "<!-- agentchat:end -->";
31
- var LEGACY_ANCHOR_START = "<!-- agentchat-skill:start -->";
32
- var LEGACY_ANCHOR_END = "<!-- agentchat-skill:end -->";
30
+ var ANCHOR_START = agentchatme.integration.anchor.START_MARKER;
31
+ var ANCHOR_END = agentchatme.integration.anchor.END_MARKER;
33
32
  function resolveWorkspaceDir(cfg, agentId) {
34
33
  return openclawLayout_js.resolveOpenClawWorkspaceDir(cfg, agentId);
35
34
  }
36
35
  function agentsAnchorPath(cfg, agentId) {
37
36
  return path__namespace.join(resolveWorkspaceDir(cfg, agentId), "AGENTS.md");
38
37
  }
39
- function renderAnchorBlock(text) {
40
- return [ANCHOR_START, text.trim(), ANCHOR_END].join("\n");
41
- }
42
38
  function bareHandle(handle) {
43
- return (handle ?? "").trim().replace(/^@/, "");
39
+ return agentchatme.integration.anchor.normalizeHandle(handle ?? "");
44
40
  }
45
41
  function writeAgentsAnchor(params) {
46
42
  const bare = bareHandle(params.handle);
@@ -51,7 +47,8 @@ function writeAgentsAnchor(params) {
51
47
  const filePath = path__namespace.join(workspaceDir, "AGENTS.md");
52
48
  fs__namespace.mkdirSync(workspaceDir, { recursive: true });
53
49
  const existing = fs__namespace.existsSync(filePath) ? fs__namespace.readFileSync(filePath, "utf-8") : "";
54
- const next = upsertAnchorBlock(existing, renderAnchorBlock(text));
50
+ const block = agentchatme.integration.anchor.render({ identity_line: text, identity_line_template: "" }, bare);
51
+ const next = agentchatme.integration.anchor.replace(existing, block);
55
52
  fs__namespace.writeFileSync(filePath, next, "utf-8");
56
53
  const verify = fs__namespace.readFileSync(filePath, "utf-8");
57
54
  if (!verify.includes(`@${bare}`)) {
@@ -63,7 +60,7 @@ function removeAgentsAnchor(params) {
63
60
  const filePath = agentsAnchorPath(params.cfg, params.agentId);
64
61
  if (!fs__namespace.existsSync(filePath)) return { removed: false, path: filePath };
65
62
  const existing = fs__namespace.readFileSync(filePath, "utf-8");
66
- const next = stripAnchorBlock(existing);
63
+ const next = agentchatme.integration.anchor.remove(existing);
67
64
  if (next === existing) return { removed: false, path: filePath };
68
65
  fs__namespace.writeFileSync(filePath, next, "utf-8");
69
66
  return { removed: true, path: filePath };
@@ -71,11 +68,9 @@ function removeAgentsAnchor(params) {
71
68
  function readAgentsAnchor(params) {
72
69
  const filePath = agentsAnchorPath(params.cfg, params.agentId);
73
70
  if (!fs__namespace.existsSync(filePath)) return { present: false, text: null, path: filePath };
74
- const content = fs__namespace.readFileSync(filePath, "utf-8");
75
- const startIdx = content.indexOf(ANCHOR_START);
76
- const endIdx = content.indexOf(ANCHOR_END);
77
- if (startIdx < 0 || endIdx < 0 || endIdx <= startIdx) return { present: false, text: null, path: filePath };
78
- return { present: true, text: content.slice(startIdx + ANCHOR_START.length, endIdx).trim(), path: filePath };
71
+ const found = agentchatme.integration.anchor.find(fs__namespace.readFileSync(filePath, "utf-8"));
72
+ if (!found) return { present: false, text: null, path: filePath };
73
+ return { present: true, text: found.body, path: filePath };
79
74
  }
80
75
  function hasAgentsAnchorFor(params) {
81
76
  const found = readAgentsAnchor({ cfg: params.cfg, agentId: params.agentId });
@@ -85,34 +80,6 @@ function hasAgentsAnchorFor(params) {
85
80
  }
86
81
  return { present: found.text.includes(`@${bareHandle(params.handle)}`), path: found.path };
87
82
  }
88
- function upsertAnchorBlock(existing, block) {
89
- const cleaned = stripBlockBetween(existing, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END);
90
- const startIdx = cleaned.indexOf(ANCHOR_START);
91
- const endIdx = cleaned.indexOf(ANCHOR_END);
92
- if (startIdx >= 0 && endIdx >= 0 && endIdx > startIdx) {
93
- const before = cleaned.slice(0, startIdx).replace(/\n+$/, "");
94
- const after = cleaned.slice(endIdx + ANCHOR_END.length).replace(/^\n+/, "");
95
- return [before, block, after].filter((s) => s.length > 0).join("\n\n") + "\n";
96
- }
97
- const trimmed = cleaned.replace(/\n+$/, "");
98
- if (trimmed.length === 0) return block + "\n";
99
- return trimmed + "\n\n" + block + "\n";
100
- }
101
- function stripAnchorBlock(existing) {
102
- const afterUnified = stripBlockBetween(existing, ANCHOR_START, ANCHOR_END);
103
- return stripBlockBetween(afterUnified, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END);
104
- }
105
- function stripBlockBetween(existing, start, end) {
106
- const startIdx = existing.indexOf(start);
107
- const endIdx = existing.indexOf(end);
108
- if (startIdx < 0 || endIdx < 0 || endIdx <= startIdx) return existing;
109
- const before = existing.slice(0, startIdx).replace(/\n+$/, "");
110
- const after = existing.slice(endIdx + end.length).replace(/^\n+/, "");
111
- if (before.length === 0 && after.length === 0) return "";
112
- if (before.length === 0) return after.endsWith("\n") ? after : after + "\n";
113
- if (after.length === 0) return before + "\n";
114
- return before + "\n\n" + after + (after.endsWith("\n") ? "" : "\n");
115
- }
116
83
 
117
84
  exports.ANCHOR_END = ANCHOR_END;
118
85
  exports.ANCHOR_START = ANCHOR_START;
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/binding/agents-anchor.ts"],"names":["resolveOpenClawWorkspaceDir","path","fs"],"mappings":"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","file":"agents-anchor.cjs","sourcesContent":["/**\n * AGENTS.md anchor management — where the identity line goes.\n *\n * Why this file exists\n * ─────────────────────\n * AgentChat asks every runtime to carry one short identity text in the file\n * it loads **every** turn. On OpenClaw that file is the workspace\n * `AGENTS.md`: workspace bootstrap files (AGENTS.md, SOUL.md, USER.md,\n * TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md) are loaded into the system\n * prompt on every turn of every session, regardless of which channel\n * triggered the run (docs.openclaw.ai/concepts/system-prompt).\n *\n * The text is served by AgentChat (`GET /v1/texts` → `identity_line`,\n * fetched by `../integration/texts.ts`). It is not ours: this module places\n * whatever text it is handed between marker fences, so re-runs upsert and\n * `channels remove` strips it cleanly. No official \"plugin → AGENTS.md\" API\n * exists.\n *\n * Lifecycle\n * ─────────\n * write — `setupWizard.finalize` (after validateApiKey ok),\n * `setup.afterAccountConfigWritten` (non-interactive path),\n * `lifecycle.onAccountConfigChanged` (disabled → enabled),\n * `openclaw doctor --fix` when the line for the configured handle\n * is missing (the re-enable path through `openclaw config set`,\n * which reaches no plugin hook), and the running gateway when a\n * fresh server copy of the text differs from the placed one.\n * remove — `lifecycle.onAccountConfigChanged` (enabled → disabled,\n * `channels remove agentchat`) and `lifecycle.onAccountRemoved`\n * (`--delete`).\n * orphan — `openclaw plugins uninstall` fires no plugin hook today; an\n * uninstall without `channels remove` leaves the block behind\n * (documented in RUNBOOK.md).\n */\n\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\n\nimport type { OpenClawConfig } from './openclaw-types.js'\n// Path resolution is delegated to the shared OpenClaw layout module (which\n// reads the environment through the credential helper). This module\n// performs only local filesystem operations against the workspace AGENTS.md\n// file and never touches the host environment directly (SECURITY.md).\nimport { resolveOpenClawWorkspaceDir } from '../openclaw-layout.js'\n\n// Marker fences shared with the universal skill's own placement recipe.\nexport const ANCHOR_START = '<!-- agentchat:start -->'\nexport const ANCHOR_END = '<!-- agentchat:end -->'\n\n// Legacy markers from an earlier recipe; migrated silently on the next write.\nconst LEGACY_ANCHOR_START = '<!-- agentchat-skill:start -->'\nconst LEGACY_ANCHOR_END = '<!-- agentchat-skill:end -->'\n\n/**\n * The workspace OpenClaw loads for the agent this channel wakes — per-agent\n * `agents.entries.<id>.workspace`, then `agents.defaults.workspace`, then\n * `$OPENCLAW_WORKSPACE_DIR`, then `<state dir>/workspace` (state dir =\n * `$OPENCLAW_STATE_DIR`, the profile dir, or `~/.openclaw`). One resolver\n * for every placement (`../openclaw-layout.ts`).\n */\nexport function resolveWorkspaceDir(cfg: OpenClawConfig | undefined, agentId?: string): string {\n return resolveOpenClawWorkspaceDir(cfg, agentId)\n}\n\nexport function agentsAnchorPath(cfg: OpenClawConfig | undefined, agentId?: string): string {\n return path.join(resolveWorkspaceDir(cfg, agentId), 'AGENTS.md')\n}\n\nfunction renderAnchorBlock(text: string): string {\n return [ANCHOR_START, text.trim(), ANCHOR_END].join('\\n')\n}\n\nfunction bareHandle(handle: string | undefined): string {\n return (handle ?? '').trim().replace(/^@/, '')\n}\n\n/**\n * Idempotent write of `text` (the served identity line) for `handle`.\n * Re-running upserts the existing block (handle change, text update) without\n * leaving stale duplicates or blank-line drift. Throws when the handle did\n * not land in the file (a regression: the served text names the handle) or\n * when the workspace is not writable — the caller decides whether to\n * surface it.\n */\nexport function writeAgentsAnchor(params: { cfg: OpenClawConfig | undefined; handle: string; text: string; agentId?: string | undefined }): { path: string } {\n const bare = bareHandle(params.handle)\n if (!bare) throw new Error('writeAgentsAnchor: handle is empty')\n const text = params.text.trim()\n if (!text) throw new Error('writeAgentsAnchor: identity line is empty')\n\n const workspaceDir = resolveWorkspaceDir(params.cfg, params.agentId)\n const filePath = path.join(workspaceDir, 'AGENTS.md')\n fs.mkdirSync(workspaceDir, { recursive: true })\n\n const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''\n const next = upsertAnchorBlock(existing, renderAnchorBlock(text))\n fs.writeFileSync(filePath, next, 'utf-8')\n\n const verify = fs.readFileSync(filePath, 'utf-8')\n if (!verify.includes(`@${bare}`)) {\n throw new Error(`writeAgentsAnchor: handle @${bare} did not land in AGENTS.md — remove the agentchat anchor manually and re-run.`)\n }\n return { path: filePath }\n}\n\n/** Idempotent remove. Strips our block (and any legacy block); leaves the rest untouched. */\nexport function removeAgentsAnchor(params: { cfg: OpenClawConfig | undefined; agentId?: string | undefined }): { removed: boolean; path: string } {\n const filePath = agentsAnchorPath(params.cfg, params.agentId)\n if (!fs.existsSync(filePath)) return { removed: false, path: filePath }\n const existing = fs.readFileSync(filePath, 'utf-8')\n const next = stripAnchorBlock(existing)\n if (next === existing) return { removed: false, path: filePath }\n fs.writeFileSync(filePath, next, 'utf-8')\n return { removed: true, path: filePath }\n}\n\n/** What the file holds between our markers, if anything. */\nexport function readAgentsAnchor(params: { cfg: OpenClawConfig | undefined; agentId?: string | undefined }): { present: boolean; text: string | null; path: string } {\n const filePath = agentsAnchorPath(params.cfg, params.agentId)\n if (!fs.existsSync(filePath)) return { present: false, text: null, path: filePath }\n const content = fs.readFileSync(filePath, 'utf-8')\n const startIdx = content.indexOf(ANCHOR_START)\n const endIdx = content.indexOf(ANCHOR_END)\n if (startIdx < 0 || endIdx < 0 || endIdx <= startIdx) return { present: false, text: null, path: filePath }\n return { present: true, text: content.slice(startIdx + ANCHOR_START.length, endIdx).trim(), path: filePath }\n}\n\n/**\n * Doctor check: is an identity line for this handle present? With `text`\n * (the served line) the block must hold exactly that text; without it (the\n * server unreachable and nothing cached) any of our blocks naming the handle\n * counts.\n */\nexport function hasAgentsAnchorFor(params: { cfg: OpenClawConfig | undefined; handle: string; text?: string | null | undefined; agentId?: string | undefined }): {\n present: boolean\n path: string\n} {\n const found = readAgentsAnchor({ cfg: params.cfg, agentId: params.agentId })\n if (!found.present || found.text === null) return { present: false, path: found.path }\n if (typeof params.text === 'string' && params.text.trim().length > 0) {\n return { present: found.text === params.text.trim(), path: found.path }\n }\n return { present: found.text.includes(`@${bareHandle(params.handle)}`), path: found.path }\n}\n\nfunction upsertAnchorBlock(existing: string, block: string): string {\n const cleaned = stripBlockBetween(existing, LEGACY_ANCHOR_START, LEGACY_ANCHOR_END)\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 return [before, block, after].filter((s) => s.length > 0).join('\\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\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\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) return existing\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"]}
1
+ {"version":3,"sources":["../../src/binding/agents-anchor.ts"],"names":["integration","resolveOpenClawWorkspaceDir","path","fs"],"mappings":"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","file":"agents-anchor.cjs","sourcesContent":["/**\n * AGENTS.md anchor management — where the identity line goes.\n *\n * Why this file exists\n * ─────────────────────\n * AgentChat asks every runtime to carry one short identity text in the file\n * it loads **every** turn. On OpenClaw that file is the workspace\n * `AGENTS.md`: workspace bootstrap files (AGENTS.md, SOUL.md, USER.md,\n * TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md) are loaded into the system\n * prompt on every turn of every session, regardless of which channel\n * triggered the run (docs.openclaw.ai/concepts/system-prompt).\n *\n * The text is served by AgentChat (`GET /v1/texts` → `identity_line`,\n * fetched by `../integration/texts.ts`). It is not ours, and neither is the\n * block's shape: the SDK kit's `anchor` functions render it (the fences, a\n * handle line, the served line), find it (current, legacy and unmarked\n * shapes) and replace or remove it, so re-runs upsert and `channels remove`\n * strips it cleanly. This module only reads and writes the file. No\n * official \"plugin → AGENTS.md\" API exists.\n *\n * Lifecycle\n * ─────────\n * write — `setupWizard.finalize` (after validateApiKey ok),\n * `setup.afterAccountConfigWritten` (non-interactive path),\n * `lifecycle.onAccountConfigChanged` (disabled → enabled),\n * `openclaw doctor --fix` when the line for the configured handle\n * is missing (the re-enable path through `openclaw config set`,\n * which reaches no plugin hook), and the running gateway when a\n * fresh server copy of the text differs from the placed one.\n * remove — `lifecycle.onAccountConfigChanged` (enabled → disabled,\n * `channels remove agentchat`) and `lifecycle.onAccountRemoved`\n * (`--delete`).\n * orphan — `openclaw plugins uninstall` fires no plugin hook today; an\n * uninstall without `channels remove` leaves the block behind\n * (documented in RUNBOOK.md).\n */\n\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\n\nimport { integration } from 'agentchatme'\n\nimport type { OpenClawConfig } from './openclaw-types.js'\n// Path resolution is delegated to the shared OpenClaw layout module (which\n// reads the environment through the credential helper). This module\n// performs only local filesystem operations against the workspace AGENTS.md\n// file and never touches the host environment directly (SECURITY.md).\nimport { resolveOpenClawWorkspaceDir } from '../openclaw-layout.js'\n\n// Marker fences (the kit's; shared with the universal skill's own placement recipe).\nexport const ANCHOR_START = integration.anchor.START_MARKER\nexport const ANCHOR_END = integration.anchor.END_MARKER\n\n/**\n * The workspace OpenClaw loads for the agent this channel wakes — per-agent\n * `agents.entries.<id>.workspace`, then `agents.defaults.workspace`, then\n * `$OPENCLAW_WORKSPACE_DIR`, then `<state dir>/workspace` (state dir =\n * `$OPENCLAW_STATE_DIR`, the profile dir, or `~/.openclaw`). One resolver\n * for every placement (`../openclaw-layout.ts`).\n */\nexport function resolveWorkspaceDir(cfg: OpenClawConfig | undefined, agentId?: string): string {\n return resolveOpenClawWorkspaceDir(cfg, agentId)\n}\n\nexport function agentsAnchorPath(cfg: OpenClawConfig | undefined, agentId?: string): string {\n return path.join(resolveWorkspaceDir(cfg, agentId), 'AGENTS.md')\n}\n\nfunction bareHandle(handle: string | undefined): string {\n return integration.anchor.normalizeHandle(handle ?? '')\n}\n\n/**\n * Idempotent write of `text` (the served identity line) for `handle`.\n * Re-running upserts the existing block (handle change, text update, an\n * older unmarked or legacy-fenced block) without leaving stale duplicates or\n * blank-line drift. Throws — writing nothing — when the text does not name\n * the handle (a peer would be handed an address that reaches someone else),\n * and when the workspace is not writable; the caller decides whether to\n * surface it.\n */\nexport function writeAgentsAnchor(params: { cfg: OpenClawConfig | undefined; handle: string; text: string; agentId?: string | undefined }): { path: string } {\n const bare = bareHandle(params.handle)\n if (!bare) throw new Error('writeAgentsAnchor: handle is empty')\n const text = params.text.trim()\n if (!text) throw new Error('writeAgentsAnchor: identity line is empty')\n\n const workspaceDir = resolveWorkspaceDir(params.cfg, params.agentId)\n const filePath = path.join(workspaceDir, 'AGENTS.md')\n fs.mkdirSync(workspaceDir, { recursive: true })\n\n const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''\n // The kit renders the block for the handle (it refuses a text that does\n // not name it) and replaces the first block of any known shape.\n const block = integration.anchor.render({ identity_line: text, identity_line_template: '' }, bare)\n const next = integration.anchor.replace(existing, block)\n fs.writeFileSync(filePath, next, 'utf-8')\n\n const verify = fs.readFileSync(filePath, 'utf-8')\n if (!verify.includes(`@${bare}`)) {\n throw new Error(`writeAgentsAnchor: handle @${bare} did not land in AGENTS.md — remove the agentchat anchor manually and re-run.`)\n }\n return { path: filePath }\n}\n\n/** Idempotent remove. Strips our block (and any legacy block); leaves the rest untouched. */\nexport function removeAgentsAnchor(params: { cfg: OpenClawConfig | undefined; agentId?: string | undefined }): { removed: boolean; path: string } {\n const filePath = agentsAnchorPath(params.cfg, params.agentId)\n if (!fs.existsSync(filePath)) return { removed: false, path: filePath }\n const existing = fs.readFileSync(filePath, 'utf-8')\n const next = integration.anchor.remove(existing)\n if (next === existing) return { removed: false, path: filePath }\n fs.writeFileSync(filePath, next, 'utf-8')\n return { removed: true, path: filePath }\n}\n\n/** What the file holds in our block (current or legacy fences), without the handle line, if anything. */\nexport function readAgentsAnchor(params: { cfg: OpenClawConfig | undefined; agentId?: string | undefined }): { present: boolean; text: string | null; path: string } {\n const filePath = agentsAnchorPath(params.cfg, params.agentId)\n if (!fs.existsSync(filePath)) return { present: false, text: null, path: filePath }\n const found = integration.anchor.find(fs.readFileSync(filePath, 'utf-8'))\n if (!found) return { present: false, text: null, path: filePath }\n return { present: true, text: found.body, path: filePath }\n}\n\n/**\n * Doctor check: is an identity line for this handle present? With `text`\n * (the served line) the block must hold exactly that text; without it (the\n * server unreachable and nothing cached) any of our blocks naming the handle\n * counts.\n */\nexport function hasAgentsAnchorFor(params: { cfg: OpenClawConfig | undefined; handle: string; text?: string | null | undefined; agentId?: string | undefined }): {\n present: boolean\n path: string\n} {\n const found = readAgentsAnchor({ cfg: params.cfg, agentId: params.agentId })\n if (!found.present || found.text === null) return { present: false, path: found.path }\n if (typeof params.text === 'string' && params.text.trim().length > 0) {\n return { present: found.text === params.text.trim(), path: found.path }\n }\n return { present: found.text.includes(`@${bareHandle(params.handle)}`), path: found.path }\n}\n"]}
@@ -13,10 +13,12 @@ import { OpenClawConfig } from 'openclaw/plugin-sdk/channel-core';
13
13
  * triggered the run (docs.openclaw.ai/concepts/system-prompt).
14
14
  *
15
15
  * The text is served by AgentChat (`GET /v1/texts` → `identity_line`,
16
- * fetched by `../integration/texts.ts`). It is not ours: this module places
17
- * whatever text it is handed between marker fences, so re-runs upsert and
18
- * `channels remove` strips it cleanly. No official "plugin → AGENTS.md" API
19
- * exists.
16
+ * fetched by `../integration/texts.ts`). It is not ours, and neither is the
17
+ * block's shape: the SDK kit's `anchor` functions render it (the fences, a
18
+ * handle line, the served line), find it (current, legacy and unmarked
19
+ * shapes) and replace or remove it, so re-runs upsert and `channels remove`
20
+ * strips it cleanly. This module only reads and writes the file. No
21
+ * official "plugin → AGENTS.md" API exists.
20
22
  *
21
23
  * Lifecycle
22
24
  * ─────────
@@ -35,8 +37,8 @@ import { OpenClawConfig } from 'openclaw/plugin-sdk/channel-core';
35
37
  * (documented in RUNBOOK.md).
36
38
  */
37
39
 
38
- declare const ANCHOR_START = "<!-- agentchat:start -->";
39
- declare const ANCHOR_END = "<!-- agentchat:end -->";
40
+ declare const ANCHOR_START: "<!-- agentchat:start -->";
41
+ declare const ANCHOR_END: "<!-- agentchat:end -->";
40
42
  /**
41
43
  * The workspace OpenClaw loads for the agent this channel wakes — per-agent
42
44
  * `agents.entries.<id>.workspace`, then `agents.defaults.workspace`, then
@@ -48,10 +50,11 @@ declare function resolveWorkspaceDir(cfg: OpenClawConfig | undefined, agentId?:
48
50
  declare function agentsAnchorPath(cfg: OpenClawConfig | undefined, agentId?: string): string;
49
51
  /**
50
52
  * Idempotent write of `text` (the served identity line) for `handle`.
51
- * Re-running upserts the existing block (handle change, text update) without
52
- * leaving stale duplicates or blank-line drift. Throws when the handle did
53
- * not land in the file (a regression: the served text names the handle) or
54
- * when the workspace is not writable — the caller decides whether to
53
+ * Re-running upserts the existing block (handle change, text update, an
54
+ * older unmarked or legacy-fenced block) without leaving stale duplicates or
55
+ * blank-line drift. Throws — writing nothing — when the text does not name
56
+ * the handle (a peer would be handed an address that reaches someone else),
57
+ * and when the workspace is not writable; the caller decides whether to
55
58
  * surface it.
56
59
  */
57
60
  declare function writeAgentsAnchor(params: {
@@ -70,7 +73,7 @@ declare function removeAgentsAnchor(params: {
70
73
  removed: boolean;
71
74
  path: string;
72
75
  };
73
- /** What the file holds between our markers, if anything. */
76
+ /** What the file holds in our block (current or legacy fences), without the handle line, if anything. */
74
77
  declare function readAgentsAnchor(params: {
75
78
  cfg: OpenClawConfig | undefined;
76
79
  agentId?: string | undefined;