@agentchatme/openclaw 0.8.1 → 0.9.1
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 +39 -0
- package/README.md +72 -70
- package/RUNBOOK.md +65 -42
- package/SECURITY.md +9 -6
- package/dist/binding/agents-anchor.cjs +24 -20
- package/dist/binding/agents-anchor.cjs.map +1 -1
- package/dist/binding/agents-anchor.d.cts +38 -31
- package/dist/binding/agents-anchor.d.ts +38 -31
- package/dist/binding/agents-anchor.js +24 -18
- package/dist/binding/agents-anchor.js.map +1 -1
- package/dist/credentials/read-env.cjs +16 -7
- package/dist/credentials/read-env.cjs.map +1 -1
- package/dist/credentials/read-env.d.cts +26 -10
- package/dist/credentials/read-env.d.ts +26 -10
- package/dist/credentials/read-env.js +12 -6
- package/dist/credentials/read-env.js.map +1 -1
- package/dist/index.cjs +1192 -1522
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +155 -753
- package/dist/index.d.ts +155 -753
- package/dist/index.js +1178 -1514
- package/dist/index.js.map +1 -1
- package/dist/openclaw-layout.cjs.map +1 -1
- package/dist/openclaw-layout.d.cts +1 -1
- package/dist/openclaw-layout.d.ts +1 -1
- package/dist/openclaw-layout.js.map +1 -1
- package/dist/setup-entry-Dh6dRH2F.d.cts +754 -0
- package/dist/setup-entry-Dh6dRH2F.d.ts +754 -0
- package/dist/setup-entry.cjs +1144 -1527
- package/dist/setup-entry.cjs.map +1 -1
- package/dist/setup-entry.d.cts +2 -1
- package/dist/setup-entry.d.ts +2 -1
- package/dist/setup-entry.js +1145 -1528
- package/dist/setup-entry.js.map +1 -1
- package/openclaw.plugin.json +6 -12
- package/package.json +6 -6
- package/skills/agentchat/SKILL.md +132 -78
- package/dist/setup-entry-DU51IFUF.d.cts +0 -154
- package/dist/setup-entry-DU51IFUF.d.ts +0 -154
package/dist/index.d.ts
CHANGED
|
@@ -1,732 +1,107 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export { a as
|
|
1
|
+
import { L as Logger } from './setup-entry-Dh6dRH2F.js';
|
|
2
|
+
export { A as AgentInvoker, a as AgentInvokerOptions, b as AgentchatChannelConfig, c as AgentchatResolvedAccount, C as CreateMetricsOptions, d as CycleOutcome, e as CycleResult, G as GroupInvite, I as IntegrationSocket, f as IntegrationSocketOptions, g as InviteLedger, M as MetricsRecorder, h as MetricsSnapshot, P as PromFactory, i as PromRegistryLike, S as SocketBlocked, j as SocketDisconnect, k as SocketHandlers, l as SocketHealth, m as SocketState, W as WakeSource, n as agentchatChannelEntry, o as agentchatPlugin, p as agentchatSetupEntry, o as agentchatSetupPlugin, q as createInMemoryMetrics, r as createMetrics, s as createNoopMetrics, n as default, t as groupInviteFromRecord, u as parseChannelConfig, v as realtimeOptionsFor } from './setup-entry-Dh6dRH2F.js';
|
|
3
3
|
export { hasAgentChatConfiguredState } from './configured-state.js';
|
|
4
|
-
import {
|
|
4
|
+
import { AgentChatClient, Texts, ToolNamer } from 'agentchatme';
|
|
5
5
|
import 'openclaw/plugin-sdk/channel-core';
|
|
6
6
|
import 'zod';
|
|
7
7
|
|
|
8
|
-
interface Logger {
|
|
9
|
-
trace(obj: object, msg?: string): void;
|
|
10
|
-
debug(obj: object, msg?: string): void;
|
|
11
|
-
info(obj: object, msg?: string): void;
|
|
12
|
-
warn(obj: object, msg?: string): void;
|
|
13
|
-
error(obj: object, msg?: string): void;
|
|
14
|
-
child(bindings: Record<string, unknown>): Logger;
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
/**
|
|
18
|
-
* Optional Prometheus metrics for the channel plugin.
|
|
19
|
-
*
|
|
20
|
-
* Design: the gateway owns the `/metrics` endpoint. Plugins do not expose
|
|
21
|
-
* their own port. If the user passes a `prom-client` Registry, we register
|
|
22
|
-
* our counters/gauges into it. Otherwise, we return a no-op recorder — zero
|
|
23
|
-
* overhead, zero config.
|
|
24
|
-
*
|
|
25
|
-
* Names are prefixed with `agentchat_channel_` for easy scraping. The
|
|
26
|
-
* doorbell sends nothing, so there are no outbound metrics: what it reports
|
|
27
|
-
* is the socket's state and its knocks.
|
|
28
|
-
*/
|
|
29
|
-
interface MetricsRecorder {
|
|
30
|
-
/** Incremented on every reconnect attempt. */
|
|
31
|
-
incReconnect(labels: {
|
|
32
|
-
reason: string;
|
|
33
|
-
}): void;
|
|
34
|
-
/** Incremented on every transport/channel error, labeled by error class. */
|
|
35
|
-
incError(labels: {
|
|
36
|
-
errorClass: string;
|
|
37
|
-
}): void;
|
|
38
|
-
/** Set the current connection state (cardinality bounded by state kinds). */
|
|
39
|
-
setConnectionState(kind: string): void;
|
|
40
|
-
/** Incremented on every knock handed to the invoker. */
|
|
41
|
-
incKnock(labels: {
|
|
42
|
-
source: string;
|
|
43
|
-
}): void;
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* Error taxonomy for the AgentChat channel plugin.
|
|
48
|
-
*
|
|
49
|
-
* Every error that crosses a pipeline boundary (inbound receive, outbound
|
|
50
|
-
* send, config validation, transport) must be classifiable as one of:
|
|
51
|
-
*
|
|
52
|
-
* terminal-auth — 401/403. API key invalid or revoked. Do not retry.
|
|
53
|
-
* Move state machine to AUTH_FAIL.
|
|
54
|
-
* terminal-user — 400/422 (client-side validation). Bug in this plugin
|
|
55
|
-
* or malformed outbound. Log at error level, drop,
|
|
56
|
-
* do not retry.
|
|
57
|
-
* retry-rate — 429. Retry after `retryAfterMs` (or jittered
|
|
58
|
-
* exponential backoff if header absent).
|
|
59
|
-
* retry-transient — 5xx, ECONNRESET, ETIMEDOUT, network flap.
|
|
60
|
-
* Exponential backoff + jitter. Open circuit after N.
|
|
61
|
-
* idempotent-replay — 409 on POST /v1/messages with duplicate
|
|
62
|
-
* client_msg_id. Treat as success, log at info.
|
|
63
|
-
* validation — Zod schema failed on inbound payload. Likely a
|
|
64
|
-
* server change. Log at error, drop, alert.
|
|
65
|
-
*/
|
|
66
|
-
type ErrorClass = 'terminal-auth' | 'terminal-user' | 'retry-rate' | 'retry-transient' | 'idempotent-replay' | 'validation';
|
|
67
|
-
declare class AgentChatChannelError extends Error {
|
|
68
|
-
readonly class_: ErrorClass;
|
|
69
|
-
readonly retryAfterMs: number | undefined;
|
|
70
|
-
readonly statusCode: number | undefined;
|
|
71
|
-
constructor(class_: ErrorClass, message: string, options?: {
|
|
72
|
-
cause?: unknown;
|
|
73
|
-
retryAfterMs?: number;
|
|
74
|
-
statusCode?: number;
|
|
75
|
-
});
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
/**
|
|
79
|
-
* Internal shared types for @agentchatme/openclaw.
|
|
80
|
-
*
|
|
81
|
-
* Kept intentionally small. Anything externally visible is exported from
|
|
82
|
-
* `./index.ts` or `./setup-entry.ts`. Types with a public SDK shape (channel
|
|
83
|
-
* plugin, setup plugin) live next to their respective entry files.
|
|
84
|
-
*/
|
|
85
|
-
type UnixMillis = number;
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* Connection state machine for the AgentChat WebSocket.
|
|
89
|
-
*
|
|
90
|
-
* Pure functions only — no I/O, no timers. The runtime (P2) owns the socket
|
|
91
|
-
* and drives transitions by emitting events.
|
|
92
|
-
*
|
|
93
|
-
* States:
|
|
94
|
-
* DISCONNECTED — initial, and after a clean close
|
|
95
|
-
* CONNECTING — TCP/TLS handshake + WS upgrade in flight
|
|
96
|
-
* AUTHENTICATING — socket open, waiting for `hello.ok` from server
|
|
97
|
-
* READY — authenticated, receiving + sending normally
|
|
98
|
-
* DEGRADED — heartbeat missed or send buffer full; still connected but impaired
|
|
99
|
-
* DRAINING — SIGTERM received; flush in-flight sends, then close
|
|
100
|
-
* CLOSED — terminal after clean shutdown
|
|
101
|
-
* AUTH_FAIL — the server rejected the key; the runtime retries slowly
|
|
102
|
-
* (keys get rotated back, accounts get reinstated)
|
|
103
|
-
*
|
|
104
|
-
* Invariants:
|
|
105
|
-
* - CLOSED is the only terminal state: it is entered only by DRAIN_REQUESTED
|
|
106
|
-
* / DRAIN_COMPLETED (the caller's own stop), never by anything the
|
|
107
|
-
* network did. Every other state has a way back to CONNECTING.
|
|
108
|
-
* - From AUTH_FAIL, CONNECT is the slow retry and RECONFIGURED is the
|
|
109
|
-
* operator's "retry now"; both lead back to a fresh HELLO.
|
|
110
|
-
* - From CLOSED, every event is a no-op.
|
|
111
|
-
* - DRAINING has a deadline (ms timestamp) after which we force-close.
|
|
112
|
-
*/
|
|
113
|
-
|
|
114
|
-
type ConnectionState = {
|
|
115
|
-
readonly kind: 'DISCONNECTED';
|
|
116
|
-
} | {
|
|
117
|
-
readonly kind: 'CONNECTING';
|
|
118
|
-
readonly attempt: number;
|
|
119
|
-
readonly startedAt: UnixMillis;
|
|
120
|
-
} | {
|
|
121
|
-
readonly kind: 'AUTHENTICATING';
|
|
122
|
-
readonly startedAt: UnixMillis;
|
|
123
|
-
} | {
|
|
124
|
-
readonly kind: 'READY';
|
|
125
|
-
readonly connectedAt: UnixMillis;
|
|
126
|
-
} | {
|
|
127
|
-
readonly kind: 'DEGRADED';
|
|
128
|
-
readonly since: UnixMillis;
|
|
129
|
-
readonly reason: string;
|
|
130
|
-
} | {
|
|
131
|
-
readonly kind: 'DRAINING';
|
|
132
|
-
readonly since: UnixMillis;
|
|
133
|
-
readonly deadline: UnixMillis;
|
|
134
|
-
} | {
|
|
135
|
-
readonly kind: 'CLOSED';
|
|
136
|
-
} | {
|
|
137
|
-
readonly kind: 'AUTH_FAIL';
|
|
138
|
-
readonly reason: string;
|
|
139
|
-
};
|
|
140
|
-
|
|
141
|
-
/**
|
|
142
|
-
* AgentChat WebSocket client — state-machine-driven, production-grade.
|
|
143
|
-
*
|
|
144
|
-
* Responsibilities:
|
|
145
|
-
* - Own the WS transport and HELLO handshake lifecycle.
|
|
146
|
-
* - Drive the connection state machine (`./state-machine.ts`) by emitting
|
|
147
|
-
* events in response to socket/auth/heartbeat transitions.
|
|
148
|
-
* - Maintain native WS PING/PONG heartbeat at `ping.intervalMs`; declare
|
|
149
|
-
* DEGRADED on `ping.timeoutMs` miss, then force-reconnect.
|
|
150
|
-
* - Schedule reconnect with exponential backoff + ±`jitterRatio` jitter
|
|
151
|
-
* per `reconnect.*` config. Thundering-herd-safe across a fleet.
|
|
152
|
-
* - Emit typed events upwards (`inboundFrame`, `stateChanged`, `error`,
|
|
153
|
-
* `authenticated`) so the runtime can turn frames into knocks.
|
|
154
|
-
*
|
|
155
|
-
* Intentional design choices:
|
|
156
|
-
* - Uses the `ws` package directly (not `globalThis.WebSocket`) because
|
|
157
|
-
* OpenClaw runs on Node — `ws` exposes `.ping()` / `.pong()` / event
|
|
158
|
-
* hooks that native WebSocket omits. Every major agent-hosting target
|
|
159
|
-
* (Fly, Render, Vercel functions, Lambda) is Node.
|
|
160
|
-
* - Authenticates via HELLO frame (`{type: "hello", api_key}`), never via
|
|
161
|
-
* URL query string. Keeps the key out of access logs and Referers.
|
|
162
|
-
* - Advertises the `ack` capability in HELLO and NEVER acknowledges. With
|
|
163
|
-
* the capability negotiated the server keeps every envelope `stored`
|
|
164
|
-
* until an ack arrives (WS Delivery-Ack Protocol v1); none ever does
|
|
165
|
-
* from here — a verdict recorded by the gate, or a send by the agent,
|
|
166
|
-
* is what settles delivery. There is no code path in this module that
|
|
167
|
-
* can emit a frame other than HELLO: delivery is judged, never
|
|
168
|
-
* confirmed by the transport.
|
|
169
|
-
* - The client never gives up on its own. Only `stop()` ends it. A close
|
|
170
|
-
* the client itself initiated (hello-ack timeout, ping timeout, its own
|
|
171
|
-
* drain) is never read as a verdict from the server; a server-originated
|
|
172
|
-
* auth close enters `AUTH_FAIL` and retries slowly, because keys get
|
|
173
|
-
* rotated back and accounts get reinstated. A long outage widens the
|
|
174
|
-
* backoff cap to `RECONNECT_LONG_OUTAGE_BACKOFF_MS` and logs one error
|
|
175
|
-
* line so an operator sees it without a log flood.
|
|
176
|
-
* - Frame parsing is defensive: malformed JSON, unknown `type`, missing
|
|
177
|
-
* payload — all classified as `validation` errors (non-terminal for
|
|
178
|
-
* the connection, but dropped with a metric + log).
|
|
179
|
-
* - No message-layer ordering here. Per-conversation seq ordering + gap
|
|
180
|
-
* recovery belong to the SDK's `RealtimeClient` and the drain layer
|
|
181
|
-
* (P3 consumers). This module is strictly the transport.
|
|
182
|
-
*/
|
|
183
|
-
|
|
184
|
-
/** One parsed inbound server frame. */
|
|
185
|
-
interface InboundFrame {
|
|
186
|
-
readonly type: string;
|
|
187
|
-
readonly payload: Record<string, unknown>;
|
|
188
|
-
readonly receivedAt: UnixMillis;
|
|
189
|
-
readonly raw: unknown;
|
|
190
|
-
}
|
|
191
|
-
interface WsClientEvents {
|
|
192
|
-
stateChanged: (next: ConnectionState, prev: ConnectionState) => void;
|
|
193
|
-
inboundFrame: (frame: InboundFrame) => void;
|
|
194
|
-
error: (error: AgentChatChannelError) => void;
|
|
195
|
-
/** Fired once per `hello.ok` — the runtime turns it into the connect knock. */
|
|
196
|
-
authenticated: (at: UnixMillis) => void;
|
|
197
|
-
/** Fired once the client reached CLOSED — only ever after `stop()`. */
|
|
198
|
-
closed: () => void;
|
|
199
|
-
}
|
|
200
|
-
interface WsClientOptions {
|
|
201
|
-
readonly config: AgentchatChannelConfig;
|
|
202
|
-
readonly logger: Logger;
|
|
203
|
-
readonly metrics: MetricsRecorder;
|
|
204
|
-
/** Clock source — override in tests. Default: `Date.now`. */
|
|
205
|
-
readonly now?: () => UnixMillis;
|
|
206
|
-
/** WebSocket constructor override — tests pass a mock. Default: `ws`. */
|
|
207
|
-
readonly webSocketCtor?: typeof WebSocket;
|
|
208
|
-
/** Random source for jitter — override in tests. Default: `Math.random`. */
|
|
209
|
-
readonly random?: () => number;
|
|
210
|
-
/** timer.setTimeout override for tests. */
|
|
211
|
-
readonly setTimeout?: (fn: () => void, ms: number) => NodeJS.Timeout;
|
|
212
|
-
readonly clearTimeout?: (h: NodeJS.Timeout) => void;
|
|
213
|
-
readonly setInterval?: (fn: () => void, ms: number) => NodeJS.Timeout;
|
|
214
|
-
readonly clearInterval?: (h: NodeJS.Timeout) => void;
|
|
215
|
-
}
|
|
216
|
-
type Listener<E extends keyof WsClientEvents> = WsClientEvents[E];
|
|
217
|
-
/**
|
|
218
|
-
* AgentChat channel WebSocket client.
|
|
219
|
-
*
|
|
220
|
-
* Lifecycle:
|
|
221
|
-
* 1. `start()` — DISCONNECTED → CONNECTING. Transport opens, HELLO is sent.
|
|
222
|
-
* 2. `hello.ok` → READY. Heartbeat timer starts. Upstream consumers begin.
|
|
223
|
-
* 3. On socket drop → DISCONNECTED → CONNECTING (with backoff).
|
|
224
|
-
* 4. `stop(deadlineMs)` → DRAINING. Wait for in-flight drains, then CLOSED.
|
|
225
|
-
*
|
|
226
|
-
* Thread-safety: this class is single-threaded. All callbacks fire on the
|
|
227
|
-
* Node event loop; callers should never invoke public methods from timer
|
|
228
|
-
* callbacks without being aware of reentrancy (e.g., a `stateChanged`
|
|
229
|
-
* listener that calls `send()` is fine, but `start()` inside `closed()`
|
|
230
|
-
* will re-enter the lifecycle — usually a bug).
|
|
231
|
-
*/
|
|
232
|
-
declare class AgentchatWsClient {
|
|
233
|
-
private readonly config;
|
|
234
|
-
private readonly logger;
|
|
235
|
-
private readonly metrics;
|
|
236
|
-
private readonly now;
|
|
237
|
-
private readonly WebSocketCtor;
|
|
238
|
-
private readonly random;
|
|
239
|
-
private readonly _setTimeout;
|
|
240
|
-
private readonly _clearTimeout;
|
|
241
|
-
private readonly _setInterval;
|
|
242
|
-
private readonly _clearInterval;
|
|
243
|
-
private state;
|
|
244
|
-
private ws;
|
|
245
|
-
private attempt;
|
|
246
|
-
private _ackNegotiated;
|
|
247
|
-
/**
|
|
248
|
-
* Set by `closeSocket()` before it closes the current socket, read and
|
|
249
|
-
* cleared by `handleClose()`. A close this client asked for says nothing
|
|
250
|
-
* about the server, whatever code travelled with it.
|
|
251
|
-
*/
|
|
252
|
-
private closeInitiatedLocally;
|
|
253
|
-
/** One error line per long outage / per run of rejected keys, then debug. */
|
|
254
|
-
private longOutageAnnounced;
|
|
255
|
-
private authFailAnnounced;
|
|
256
|
-
private helloAckTimer;
|
|
257
|
-
private pingTimer;
|
|
258
|
-
private pongTimer;
|
|
259
|
-
private reconnectTimer;
|
|
260
|
-
private drainTimer;
|
|
261
|
-
private readonly listeners;
|
|
262
|
-
constructor(options: WsClientOptions);
|
|
263
|
-
/** Current connection state. Read-only from the caller's perspective. */
|
|
264
|
-
getState(): ConnectionState;
|
|
265
|
-
/**
|
|
266
|
-
* True when the last `hello.ok` echoed the `ack` capability: the server
|
|
267
|
-
* keeps envelopes `stored` until acknowledged — and this client never
|
|
268
|
-
* acknowledges. False against a legacy server (envelopes marked on push).
|
|
269
|
-
*/
|
|
270
|
-
get ackNegotiated(): boolean;
|
|
271
|
-
/**
|
|
272
|
-
* Kick off connection. No-op if already connecting, authenticating, ready,
|
|
273
|
-
* or waiting out a backoff / auth retry. Throws only on `CLOSED`.
|
|
274
|
-
*/
|
|
275
|
-
start(): void;
|
|
276
|
-
/**
|
|
277
|
-
* Request a graceful drain. The caller-supplied deadline is a Unix-ms
|
|
278
|
-
* timestamp; after it passes, the socket is force-closed regardless of
|
|
279
|
-
* remaining in-flight work. Safe to call from any state.
|
|
280
|
-
*/
|
|
281
|
-
stop(deadline?: UnixMillis): void;
|
|
282
|
-
/**
|
|
283
|
-
* Signal that the operator has rotated the API key: leave AUTH_FAIL and
|
|
284
|
-
* retry now instead of waiting for the slow retry timer. A no-op in every
|
|
285
|
-
* other state (the client is already connecting or connected).
|
|
286
|
-
*/
|
|
287
|
-
reconfigured(): void;
|
|
288
|
-
on<E extends keyof WsClientEvents>(event: E, handler: Listener<E>): () => void;
|
|
289
|
-
private openSocket;
|
|
290
|
-
private bindSocket;
|
|
291
|
-
private handleOpen;
|
|
292
|
-
private handleMessage;
|
|
293
|
-
private extractReason;
|
|
294
|
-
private extractPayload;
|
|
295
|
-
private handleHelloOk;
|
|
296
|
-
/** The server answered HELLO with a rejection frame (not a close). */
|
|
297
|
-
private handleAuthRejected;
|
|
298
|
-
/**
|
|
299
|
-
* The server rejected this key. AUTH_FAIL is not the end: retry a fresh
|
|
300
|
-
* HELLO every `AUTH_RETRY_INTERVAL_MS` (jittered). The first rejection in a
|
|
301
|
-
* run logs at error so an operator sees it; the following ones at debug.
|
|
302
|
-
*/
|
|
303
|
-
private enterAuthFail;
|
|
304
|
-
private handleClose;
|
|
305
|
-
private closeSocket;
|
|
306
|
-
private startHeartbeat;
|
|
307
|
-
private stopHeartbeat;
|
|
308
|
-
private sendPing;
|
|
309
|
-
private handlePong;
|
|
310
|
-
private scheduleReconnect;
|
|
311
|
-
/** AUTH_FAIL's own cadence: a fresh HELLO every AUTH_RETRY_INTERVAL_MS, jittered. */
|
|
312
|
-
private scheduleAuthRetry;
|
|
313
|
-
private clearReconnectTimer;
|
|
314
|
-
private computeReconnectDelay;
|
|
315
|
-
/**
|
|
316
|
-
* Symmetric ±`jitterRatio`. Thundering-herd-safe: a fleet that all drops
|
|
317
|
-
* at the same instant re-enters the connect queue spread across
|
|
318
|
-
* ms * [1-jitterRatio, 1+jitterRatio].
|
|
319
|
-
*/
|
|
320
|
-
private jittered;
|
|
321
|
-
private scheduleDrainDeadline;
|
|
322
|
-
/**
|
|
323
|
-
* Called by upper layers when their pending work has fully drained, to
|
|
324
|
-
* let the WS client transition CLOSED earlier than the deadline.
|
|
325
|
-
*/
|
|
326
|
-
drainCompleted(): void;
|
|
327
|
-
private applyEvent;
|
|
328
|
-
private emit;
|
|
329
|
-
private emitError;
|
|
330
|
-
}
|
|
331
|
-
|
|
332
8
|
/**
|
|
333
|
-
*
|
|
334
|
-
*
|
|
335
|
-
*
|
|
336
|
-
*
|
|
337
|
-
*
|
|
338
|
-
*
|
|
339
|
-
*
|
|
340
|
-
*
|
|
341
|
-
*
|
|
342
|
-
*
|
|
343
|
-
*
|
|
344
|
-
*
|
|
9
|
+
* The served texts: fetched from AgentChat, never bundled.
|
|
10
|
+
*
|
|
11
|
+
* Every text an agent sees is written once, in AgentChat's experience layer,
|
|
12
|
+
* and served as data (`GET /v1/texts?runtime=openclaw`): the wake
|
|
13
|
+
* instruction a turn starts with, the invite prompt, the identity line that
|
|
14
|
+
* goes into the workspace `AGENTS.md`, and where the manual is. This module
|
|
15
|
+
* fetches them at channel start and every 24 hours, keeps the last copy in
|
|
16
|
+
* the plugin's state dir, and hands them out spelled for OpenClaw (the hosted
|
|
17
|
+
* tools as `agentchat__<tool>`, see `./turn.ts`).
|
|
18
|
+
*
|
|
19
|
+
* When the server is unreachable at start the last cached copy is used; with
|
|
20
|
+
* nothing cached the channel still starts (the socket connects, the gate can
|
|
21
|
+
* run) and logs once — turns wait for the first successful fetch, which is
|
|
22
|
+
* retried every few minutes until it lands.
|
|
345
23
|
*/
|
|
346
24
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
readonly
|
|
352
|
-
readonly
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
readonly
|
|
357
|
-
readonly
|
|
358
|
-
readonly
|
|
359
|
-
readonly
|
|
360
|
-
|
|
361
|
-
type Knock = MessageKnock | GroupInviteKnock;
|
|
362
|
-
|
|
363
|
-
/**
|
|
364
|
-
* AgentChat channel runtime — the socket as a knock.
|
|
365
|
-
*
|
|
366
|
-
* One instance per (channelId, accountId). It owns the WebSocket transport
|
|
367
|
-
* (`AgentchatWsClient`: HELLO, state machine, heartbeat, reconnect) and turns
|
|
368
|
-
* what arrives on it into knocks for the doorbell's invoker:
|
|
369
|
-
*
|
|
370
|
-
* - `message.new` → `onKnock('message')` — after reading only
|
|
371
|
-
* the sender (to skip our own echo) and the
|
|
372
|
-
* ids for the log line. The body is never
|
|
373
|
-
* looked at; the agent reads it through the
|
|
374
|
-
* hosted tools inside its turn.
|
|
375
|
-
* - every successful HELLO → `onKnock('connect')` — whatever landed
|
|
376
|
-
* while the socket was down is on the tray.
|
|
377
|
-
* - `group.invite.received` → `onGroupInvite(invite)` — the second knock
|
|
378
|
-
* kind; not on the tray, not gated.
|
|
379
|
-
*
|
|
380
|
-
* Nothing is parsed into message shapes, nothing is acknowledged, nothing is
|
|
381
|
-
* sent: the socket advertises the `ack` capability so the server keeps every
|
|
382
|
-
* envelope `stored` until a verdict or a send settles it, and this runtime
|
|
383
|
-
* has no code path that could emit an ack frame (`ws-client.ts`). Delivery
|
|
384
|
-
* is judged by the agent, never by the transport.
|
|
385
|
-
*/
|
|
386
|
-
|
|
387
|
-
type KnockSource = 'message' | 'connect';
|
|
388
|
-
interface ChannelRuntimeHandlers {
|
|
389
|
-
/** A knock: the tray may have changed. `source` is for the log line only. */
|
|
390
|
-
onKnock?: (source: KnockSource) => void;
|
|
391
|
-
/** The second knock kind. */
|
|
392
|
-
onGroupInvite?: (invite: GroupInviteKnock) => void;
|
|
393
|
-
/** Called on state transitions — surface to the gateway for health/UI. */
|
|
394
|
-
onStateChanged?: (next: ConnectionState, prev: ConnectionState) => void;
|
|
395
|
-
/** Called once per successful HELLO (initial + every reconnect), before the connect knock. */
|
|
396
|
-
onAuthenticated?: (at: UnixMillis) => void;
|
|
397
|
-
/** Called on every closed/unreachable situation worth observing. */
|
|
398
|
-
onError?: (error: AgentChatChannelError) => void;
|
|
399
|
-
}
|
|
400
|
-
interface ChannelRuntimeOptions {
|
|
401
|
-
readonly config: AgentchatChannelConfig;
|
|
402
|
-
readonly handlers?: ChannelRuntimeHandlers;
|
|
403
|
-
/** Pre-built logger — if absent, we construct one from `config.observability`. */
|
|
404
|
-
readonly logger?: Logger;
|
|
405
|
-
/** Pre-built metrics recorder — if absent, uses no-op. */
|
|
406
|
-
readonly metrics?: MetricsRecorder;
|
|
407
|
-
/** Provided by tests. */
|
|
408
|
-
readonly webSocketCtor?: ConstructorParameters<typeof AgentchatWsClient>[0]['webSocketCtor'];
|
|
409
|
-
readonly now?: () => UnixMillis;
|
|
410
|
-
readonly random?: () => number;
|
|
411
|
-
}
|
|
412
|
-
interface HealthSnapshot {
|
|
413
|
-
readonly state: ConnectionState;
|
|
414
|
-
readonly authenticated: boolean;
|
|
415
|
-
/** Whether the server echoed the `ack` capability on the last HELLO (envelopes stay `stored` until judged). */
|
|
416
|
-
readonly ackNegotiated: boolean;
|
|
417
|
-
readonly counters: {
|
|
418
|
-
readonly frames: number;
|
|
419
|
-
readonly selfFiltered: number;
|
|
420
|
-
readonly knocks: number;
|
|
421
|
-
readonly invites: number;
|
|
422
|
-
};
|
|
423
|
-
}
|
|
424
|
-
declare class AgentchatChannelRuntime {
|
|
425
|
-
private readonly config;
|
|
426
|
-
private readonly handlers;
|
|
427
|
-
private readonly logger;
|
|
428
|
-
private readonly ws;
|
|
429
|
-
private readonly selfHandle;
|
|
430
|
-
private readonly now;
|
|
431
|
-
private started;
|
|
432
|
-
private authenticated;
|
|
433
|
-
private stopPromise;
|
|
434
|
-
private frames;
|
|
435
|
-
private selfFiltered;
|
|
436
|
-
private knocks;
|
|
437
|
-
private invites;
|
|
438
|
-
private authenticatedAt;
|
|
439
|
-
constructor(opts: ChannelRuntimeOptions);
|
|
440
|
-
/** Open the transport. Idempotent — subsequent calls are no-ops. */
|
|
441
|
-
start(): void;
|
|
442
|
-
/** Graceful shutdown: close the socket (nothing is in flight — the runtime sends nothing). */
|
|
443
|
-
stop(deadlineMs?: UnixMillis): Promise<void>;
|
|
444
|
-
/** Operator rotated the API key — leave AUTH_FAIL so the next `start()` can retry. */
|
|
445
|
-
reconfigured(): void;
|
|
446
|
-
getHealth(): HealthSnapshot;
|
|
447
|
-
private bindWsEvents;
|
|
448
|
-
private dispatchFrame;
|
|
449
|
-
private knock;
|
|
450
|
-
/** A failing handler never takes the socket down; the next frame knocks again and the tray keeps the cards. */
|
|
451
|
-
private guard;
|
|
452
|
-
}
|
|
453
|
-
|
|
454
|
-
/** The tray, as the server sends it. Only the fields the doorbell reads are typed; the rest passes through. */
|
|
455
|
-
interface Tray {
|
|
456
|
-
readonly you?: unknown;
|
|
457
|
-
readonly question?: unknown;
|
|
458
|
-
readonly categories?: unknown;
|
|
459
|
-
readonly conversations?: unknown;
|
|
460
|
-
readonly deferred?: unknown;
|
|
461
|
-
readonly truncated?: unknown;
|
|
462
|
-
readonly [key: string]: unknown;
|
|
463
|
-
}
|
|
464
|
-
type Decision = 'reply' | 'dismiss' | 'defer';
|
|
465
|
-
interface RecordDecisionInput {
|
|
466
|
-
readonly decision: Decision;
|
|
467
|
-
readonly category?: string | undefined;
|
|
468
|
-
readonly throughMessageId?: string | undefined;
|
|
469
|
-
readonly deferSeconds?: number | undefined;
|
|
470
|
-
}
|
|
471
|
-
/**
|
|
472
|
-
* A main-line call failed: transport error or a non-2xx answer.
|
|
473
|
-
* `status` is the HTTP status (`undefined` for transport failures); `code`
|
|
474
|
-
* is the server's error code when the body carried one.
|
|
475
|
-
*/
|
|
476
|
-
declare class MainLineError extends Error {
|
|
477
|
-
readonly status: number | undefined;
|
|
478
|
-
readonly code: string | undefined;
|
|
479
|
-
constructor(message: string, options?: {
|
|
480
|
-
status?: number;
|
|
481
|
-
code?: string;
|
|
482
|
-
cause?: unknown;
|
|
483
|
-
});
|
|
484
|
-
}
|
|
485
|
-
interface MainLineClientOptions {
|
|
486
|
-
readonly apiKey: string;
|
|
487
|
-
readonly apiBase: string;
|
|
25
|
+
type TextsClient = Pick<AgentChatClient, 'texts'>;
|
|
26
|
+
type TextsSourceKind = 'server' | 'cache';
|
|
27
|
+
interface LoadedTexts {
|
|
28
|
+
/** Spelled for OpenClaw. */
|
|
29
|
+
readonly texts: Texts;
|
|
30
|
+
readonly source: TextsSourceKind;
|
|
31
|
+
readonly fetchedAt: string;
|
|
32
|
+
}
|
|
33
|
+
interface LoadTextsParams {
|
|
34
|
+
readonly client: TextsClient;
|
|
35
|
+
readonly accountId: string;
|
|
36
|
+
readonly stateDir?: string | undefined;
|
|
37
|
+
readonly now?: () => number;
|
|
38
|
+
readonly log?: Logger | undefined;
|
|
488
39
|
readonly timeoutMs?: number;
|
|
489
|
-
/** Test seam. Production uses the global `fetch`. */
|
|
490
|
-
readonly fetch?: typeof fetch;
|
|
491
|
-
}
|
|
492
|
-
declare class MainLineClient {
|
|
493
|
-
private readonly apiKey;
|
|
494
|
-
private readonly apiBase;
|
|
495
|
-
private readonly timeoutMs;
|
|
496
|
-
private readonly fetchImpl;
|
|
497
|
-
constructor(options: MainLineClientOptions);
|
|
498
|
-
/**
|
|
499
|
-
* `GET /v1/inbox` — the briefing cards plus the gate question, returned as
|
|
500
|
-
* the server sent them (`you`, `question`, `categories`, `conversations`,
|
|
501
|
-
* `deferred`, `truncated`, and any field a newer server adds). Marks
|
|
502
|
-
* nothing delivered.
|
|
503
|
-
*/
|
|
504
|
-
inbox(params?: {
|
|
505
|
-
waitMs?: number;
|
|
506
|
-
limit?: number;
|
|
507
|
-
}): Promise<Tray>;
|
|
508
|
-
/**
|
|
509
|
-
* `POST /v1/conversations/{id}/decisions` — record one verdict. The server
|
|
510
|
-
* validates `decision`, `category` and `defer_seconds` against its own
|
|
511
|
-
* taxonomy; this client passes them through and raises `MainLineError`
|
|
512
|
-
* (`status` 400) when the server rejects a value, so the caller can retry
|
|
513
|
-
* with less.
|
|
514
|
-
*/
|
|
515
|
-
recordDecision(conversationId: string, input: RecordDecisionInput): Promise<Record<string, unknown>>;
|
|
516
|
-
private request;
|
|
517
40
|
}
|
|
518
|
-
|
|
519
41
|
/**
|
|
520
|
-
*
|
|
521
|
-
*
|
|
522
|
-
*
|
|
523
|
-
* ────────────────────────────
|
|
524
|
-
* Every word the model reads here comes from the main line: the gate question
|
|
525
|
-
* (`tray.question`) and the briefing cards (`tray.conversations`) are passed
|
|
526
|
-
* through exactly as `GET /v1/inbox` returned them. This module adds a
|
|
527
|
-
* two-line wrapper asking for strict JSON, parses the answer, and records the
|
|
528
|
-
* verdicts with `POST /v1/conversations/{id}/decisions`. No wording of its
|
|
529
|
-
* own, no category list of its own (categories are offered only when the
|
|
530
|
-
* tray carries them), no pace or relationship arithmetic — the server
|
|
531
|
-
* computes, the agent's model judges, the doorbell carries.
|
|
532
|
-
*
|
|
533
|
-
* What gets recorded
|
|
534
|
-
* ──────────────────
|
|
535
|
-
* `dismiss` and `defer` are posted; a recorded verdict settles delivery for
|
|
536
|
-
* what it covers, so the sender's tick is honest and the conversation leaves
|
|
537
|
-
* the tray. `reply` is deliberately *not* posted: the send is the reply
|
|
538
|
-
* verdict, and posting it would settle the envelopes and take the card off
|
|
539
|
-
* the tray before the agent's turn has read it. Cards decided `reply` stay
|
|
540
|
-
* on the tray; the turn that follows reads exactly those with the hosted
|
|
541
|
-
* `agentchat_inbox` tool. A model that still answers the legacy spelling
|
|
542
|
-
* `no_reply` is understood and posted as `dismiss`.
|
|
543
|
-
*
|
|
544
|
-
* Failure policy
|
|
545
|
-
* ──────────────
|
|
546
|
-
* Fail closed by default: when the model cannot be reached or answers nothing
|
|
547
|
-
* usable, nothing is posted and no turn starts. The envelopes stay `stored`,
|
|
548
|
-
* the tray keeps the cards, and the invoker re-knocks on its own ladder. With
|
|
549
|
-
* `AGENTCHAT_REPLY_GATE_FAIL_OPEN=1` a failed gate starts the turn anyway and
|
|
550
|
-
* the agent judges from the tray inside the turn.
|
|
42
|
+
* Server first; the cache when the server cannot be reached. A server
|
|
43
|
+
* success refreshes the cache (a cache write failure is logged, never
|
|
44
|
+
* fatal). `null` when neither is available. Never throws.
|
|
551
45
|
*/
|
|
552
|
-
|
|
553
|
-
interface Verdict {
|
|
554
|
-
readonly conversationId: string;
|
|
555
|
-
readonly decision: Decision;
|
|
556
|
-
readonly category?: string | undefined;
|
|
557
|
-
readonly deferSeconds?: number | undefined;
|
|
558
|
-
}
|
|
559
|
-
/** Returns the model's raw text. Injectable so tests never reach a provider. */
|
|
560
|
-
type GateCaller = (params: {
|
|
561
|
-
readonly systemPrompt: string;
|
|
562
|
-
readonly userContent: string;
|
|
563
|
-
readonly maxTokens: number;
|
|
564
|
-
readonly timeoutMs: number;
|
|
565
|
-
}) => Promise<string>;
|
|
566
|
-
type GateSource = 'llm' | 'empty' | 'fail_closed' | 'fail_open' | 'disabled';
|
|
567
|
-
interface GateResult {
|
|
568
|
-
/** How the cycle ended; see the module header. */
|
|
569
|
-
readonly source: GateSource;
|
|
570
|
-
readonly cards: number;
|
|
571
|
-
readonly verdicts: readonly Verdict[];
|
|
572
|
-
readonly undecided: readonly string[];
|
|
573
|
-
readonly replyConversations: readonly string[];
|
|
574
|
-
readonly posted: number;
|
|
575
|
-
readonly postFailures: number;
|
|
576
|
-
readonly truncated: boolean;
|
|
577
|
-
readonly latencyMs: number;
|
|
578
|
-
readonly failure: string | null;
|
|
579
|
-
}
|
|
580
|
-
|
|
46
|
+
declare function loadTexts(params: LoadTextsParams): Promise<LoadedTexts | null>;
|
|
581
47
|
/**
|
|
582
|
-
*
|
|
583
|
-
*
|
|
584
|
-
*
|
|
585
|
-
* through `defineChannelPluginEntry({ setRuntime })`:
|
|
586
|
-
*
|
|
587
|
-
* 1. **The gate call** — `runtime.llm.complete({ systemPrompt, messages,
|
|
588
|
-
* maxTokens, temperature, purpose })` runs one tool-free completion on the
|
|
589
|
-
* agent's own configured model and credentials (`LlmCompleteParams`,
|
|
590
|
-
* `plugin-sdk/types`; docs.openclaw.ai/plugins/sdk-runtime/models). Without
|
|
591
|
-
* an `agentId` OpenClaw uses the ambient default agent; passing one is an
|
|
592
|
-
* OVERRIDE that OpenClaw 2026.10.9 rejects with
|
|
593
|
-
* `LLM_COMPLETION_NOT_AUTHORIZED` unless the operator set
|
|
594
|
-
* `plugins.entries.agentchat.llm.allowAgentIdOverride: true`. The doorbell
|
|
595
|
-
* therefore passes `agentId` only when the account is genuinely routed to
|
|
596
|
-
* a non-default agent (`agentIdOverride`), and the wizard / doctor write
|
|
597
|
-
* the opt-in in that case. The judgement is the agent's; the platform
|
|
598
|
-
* computes, it never judges.
|
|
599
|
-
*
|
|
600
|
-
* 2. **The turn** — `runtime.subagent.run({ sessionKey, message, lane,
|
|
601
|
-
* deliver: false })` admits one agent run with the fixed prompt as its
|
|
602
|
-
* message and no delivery of its final text (`SubagentRunParams`;
|
|
603
|
-
* docs.openclaw.ai/plugins/sdk-runtime/background-work — the same shape
|
|
604
|
-
* OpenClaw's own background features use with `deliver: false`). The
|
|
605
|
-
* turn's output is never routed anywhere: the agent's only way to say
|
|
606
|
-
* something on AgentChat is the hosted `agentchat__agentchat_send_message`
|
|
607
|
-
* tool during the turn. `runtime.subagent.waitForRun` bounds how long the
|
|
608
|
-
* invoker waits before it may start the next cycle; it never cancels the
|
|
609
|
-
* run.
|
|
610
|
-
*
|
|
611
|
-
* The agent id is resolved the way OpenClaw routes inbound for this channel
|
|
612
|
-
* (`channelRuntime.routing.resolveAgentRoute`), so the doorbell wakes the
|
|
613
|
-
* agent the operator bound to the account; `main` when nothing is bound.
|
|
48
|
+
* The identity line for the key's own agent, spelled for OpenClaw — for the
|
|
49
|
+
* placement paths that run outside the gateway (wizard, `channels add`,
|
|
50
|
+
* `doctor --fix`, re-enable). Server, then cache; `null` when neither.
|
|
614
51
|
*/
|
|
615
|
-
|
|
616
|
-
interface
|
|
617
|
-
readonly
|
|
618
|
-
readonly prompt: string;
|
|
619
|
-
readonly lane: string;
|
|
620
|
-
}
|
|
621
|
-
interface TurnOutcome {
|
|
622
|
-
readonly ran: boolean;
|
|
623
|
-
readonly runId?: string;
|
|
624
|
-
readonly status?: string;
|
|
625
|
-
readonly error?: string;
|
|
626
|
-
}
|
|
627
|
-
/** Starts one agent turn and waits for it (bounded). Injectable so the invoker is testable without OpenClaw. */
|
|
628
|
-
type TurnRunner = (request: TurnRequest) => Promise<TurnOutcome>;
|
|
629
|
-
|
|
630
|
-
/**
|
|
631
|
-
* Knock → gate → turn. The only path from the socket to the agent.
|
|
632
|
-
*
|
|
633
|
-
* What happens on a knock
|
|
634
|
-
* ───────────────────────
|
|
635
|
-
* 1. **Coalesce.** Frames inside a short window become one knock
|
|
636
|
-
* (`KnockCoalescer`). A group waking up is one cycle, not twenty.
|
|
637
|
-
* 2. **Read the tray.** `GET /v1/inbox?wait_ms=0&limit=50` — the server's
|
|
638
|
-
* briefing cards and its gate question, as it built them.
|
|
639
|
-
* 3. **Gate.** The agent's own model answers the question per card
|
|
640
|
-
* (`./gate.ts`); `dismiss` / `defer` verdicts are recorded on the server,
|
|
641
|
-
* which settles those conversations. `reply` cards stay on the tray.
|
|
642
|
-
* 4. **Turn.** If anything was decided `reply`, start ONE OpenClaw agent turn
|
|
643
|
-
* with the fixed prompt (`./turn.ts`). The agent reads and answers through
|
|
644
|
-
* the hosted MCP tools; the send is its verdict. The turn's final text is
|
|
645
|
-
* discarded — nothing is auto-routed anywhere.
|
|
646
|
-
*
|
|
647
|
-
* One cycle at a time per account: a knock that lands while a cycle runs is
|
|
648
|
-
* remembered and runs once the cycle ends (the tray is re-read, so whatever
|
|
649
|
-
* the earlier knock announced is covered). A cycle that could not complete —
|
|
650
|
-
* model unreachable, server error, verdicts rejected — re-knocks itself on a
|
|
651
|
-
* local ladder (1 m, 5 m, 30 m) because a connected socket gets no re-ring
|
|
652
|
-
* from the server; the cards wait on the tray meanwhile. One outage climbs
|
|
653
|
-
* the ladder one rung: a retry already on its way is never replaced by a
|
|
654
|
-
* later one.
|
|
655
|
-
*
|
|
656
|
-
* Group invites are a second knock kind: not on the tray, not gated, one turn
|
|
657
|
-
* each with the fixed invite prompt, serialized on the same worker.
|
|
658
|
-
*/
|
|
659
|
-
|
|
660
|
-
interface AgentInvokerOptions {
|
|
52
|
+
declare function loadIdentityLine(params: LoadTextsParams): Promise<string | null>;
|
|
53
|
+
interface TextsStoreOptions {
|
|
54
|
+
readonly client: TextsClient;
|
|
661
55
|
readonly accountId: string;
|
|
662
|
-
readonly agentId: string;
|
|
663
|
-
readonly mainLine: MainLineClient;
|
|
664
|
-
readonly gateCaller: GateCaller;
|
|
665
|
-
readonly turnRunner: TurnRunner;
|
|
666
56
|
readonly logger: Logger;
|
|
667
|
-
readonly
|
|
668
|
-
readonly
|
|
669
|
-
readonly
|
|
670
|
-
readonly
|
|
671
|
-
readonly retryLadderMs?: readonly number[];
|
|
57
|
+
readonly stateDir?: string | undefined;
|
|
58
|
+
readonly refreshMs?: number;
|
|
59
|
+
readonly retryMs?: number;
|
|
60
|
+
readonly fetchTimeoutMs?: number;
|
|
672
61
|
readonly now?: () => number;
|
|
673
62
|
readonly setTimeout?: (fn: () => void, ms: number) => NodeJS.Timeout;
|
|
674
63
|
readonly clearTimeout?: (handle: NodeJS.Timeout) => void;
|
|
675
64
|
}
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
readonly
|
|
683
|
-
}
|
|
684
|
-
declare class AgentInvoker {
|
|
65
|
+
/**
|
|
66
|
+
* The texts for one running account: loaded at start, refreshed on a timer,
|
|
67
|
+
* available synchronously to the invoker. `ensure()` is what a cycle calls
|
|
68
|
+
* when it needs them: the current copy, or one load attempt right now.
|
|
69
|
+
*/
|
|
70
|
+
declare class TextsStore {
|
|
71
|
+
private readonly client;
|
|
685
72
|
private readonly accountId;
|
|
686
|
-
private readonly agentId;
|
|
687
|
-
private readonly mainLine;
|
|
688
|
-
private readonly gateCaller;
|
|
689
|
-
private readonly turnRunner;
|
|
690
73
|
private readonly logger;
|
|
691
|
-
private readonly
|
|
692
|
-
private readonly
|
|
693
|
-
private readonly
|
|
694
|
-
private readonly
|
|
74
|
+
private readonly stateDir;
|
|
75
|
+
private readonly refreshMs;
|
|
76
|
+
private readonly retryMs;
|
|
77
|
+
private readonly fetchTimeoutMs;
|
|
695
78
|
private readonly now;
|
|
696
|
-
private readonly
|
|
697
|
-
private
|
|
698
|
-
private
|
|
79
|
+
private readonly _setTimeout;
|
|
80
|
+
private readonly _clearTimeout;
|
|
81
|
+
private loaded;
|
|
82
|
+
private timer;
|
|
83
|
+
private inFlight;
|
|
699
84
|
private stopped;
|
|
700
|
-
private
|
|
701
|
-
private readonly
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
/**
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
/**
|
|
85
|
+
private missingAnnounced;
|
|
86
|
+
private readonly listeners;
|
|
87
|
+
loads: number;
|
|
88
|
+
serverLoads: number;
|
|
89
|
+
constructor(options: TextsStoreOptions);
|
|
90
|
+
/** The texts spelled for OpenClaw, or null until the first copy exists. */
|
|
91
|
+
get current(): Texts | null;
|
|
92
|
+
get source(): TextsSourceKind | null;
|
|
93
|
+
get fetchedAt(): string | null;
|
|
94
|
+
/** Called with every copy that arrives from the server (not with a cached one). */
|
|
95
|
+
onServerCopy(listener: (texts: Texts, source: TextsSourceKind) => void): () => void;
|
|
96
|
+
/** First load (server, then cache), then the timer. Resolves after the first attempt; never throws. */
|
|
97
|
+
start(): Promise<Texts | null>;
|
|
98
|
+
/** The current copy, or one load attempt now (coalesced with any in flight). */
|
|
99
|
+
ensure(): Promise<Texts | null>;
|
|
100
|
+
/** Force a refresh (tests, operators). Coalesced. */
|
|
101
|
+
refresh(): Promise<Texts | null>;
|
|
716
102
|
stop(): void;
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
counters(): InvokerCounters;
|
|
720
|
-
private onKnockFired;
|
|
721
|
-
/** Run the worker if idle. One cycle at a time; work that lands mid-cycle runs afterwards. */
|
|
722
|
-
private schedule;
|
|
723
|
-
private drain;
|
|
724
|
-
/** Read the tray, gate it, start a turn when warranted. Public so tests can drive one cycle. */
|
|
725
|
-
runCycle(): Promise<GateResult | null>;
|
|
726
|
-
private scheduleRetry;
|
|
727
|
-
/** Start the knock turn. Returns whether OpenClaw admitted the run. */
|
|
728
|
-
private runKnockTurn;
|
|
729
|
-
private runInviteTurn;
|
|
103
|
+
private load;
|
|
104
|
+
private arm;
|
|
730
105
|
}
|
|
731
106
|
|
|
732
107
|
declare function hostedMcpUrl(apiBase?: string): string;
|
|
@@ -788,16 +163,19 @@ declare function probeHostedMcp(params: {
|
|
|
788
163
|
declare const AGENTCHAT_CHANNEL_ID: "agentchat";
|
|
789
164
|
declare const AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
|
|
790
165
|
|
|
791
|
-
interface
|
|
166
|
+
interface WakeCoalescerOptions {
|
|
792
167
|
readonly onFire: () => void;
|
|
168
|
+
/** Called when a delayed (retry-ladder) wake fires, before it is counted like any other wake. */
|
|
169
|
+
readonly onDelayedWake?: () => void;
|
|
793
170
|
readonly debounceMs?: number;
|
|
794
171
|
readonly maxWindowMs?: number;
|
|
795
172
|
readonly now?: () => number;
|
|
796
173
|
readonly setTimeout?: (fn: () => void, ms: number) => NodeJS.Timeout;
|
|
797
174
|
readonly clearTimeout?: (handle: NodeJS.Timeout) => void;
|
|
798
175
|
}
|
|
799
|
-
declare class
|
|
176
|
+
declare class WakeCoalescer {
|
|
800
177
|
private readonly onFire;
|
|
178
|
+
private readonly onDelayedWake;
|
|
801
179
|
private readonly debounceMs;
|
|
802
180
|
private readonly maxWindowMs;
|
|
803
181
|
private readonly now;
|
|
@@ -808,76 +186,100 @@ declare class KnockCoalescer {
|
|
|
808
186
|
private delayed;
|
|
809
187
|
private delayedDeadline;
|
|
810
188
|
private stopped;
|
|
811
|
-
|
|
189
|
+
wakes: number;
|
|
812
190
|
absorbed: number;
|
|
813
191
|
fires: number;
|
|
814
|
-
constructor(options:
|
|
192
|
+
constructor(options: WakeCoalescerOptions);
|
|
815
193
|
/** True while a debounce timer is armed. */
|
|
816
194
|
get armed(): boolean;
|
|
817
|
-
/** True while a retry
|
|
195
|
+
/** True while a retry wake is scheduled and has not fired. */
|
|
818
196
|
get delayedPending(): boolean;
|
|
819
197
|
/**
|
|
820
|
-
* A
|
|
198
|
+
* A wake. The first one of a burst arms the window; every later one is
|
|
821
199
|
* absorbed and restarts it (trailing edge), never past the burst's cap.
|
|
822
200
|
*/
|
|
823
|
-
|
|
824
|
-
/** A delayed
|
|
825
|
-
|
|
826
|
-
/** Cancel everything; later
|
|
201
|
+
wake(): void;
|
|
202
|
+
/** A delayed wake (retry ladder). The sooner pending deadline is kept. */
|
|
203
|
+
wakeAfter(delayMs: number): void;
|
|
204
|
+
/** Cancel everything; later wakes are ignored. */
|
|
827
205
|
stop(): void;
|
|
828
206
|
private fire;
|
|
829
207
|
}
|
|
830
208
|
|
|
831
209
|
/**
|
|
832
|
-
*
|
|
210
|
+
* Turns: the names OpenClaw gives the hosted tools, the prompts a turn starts
|
|
211
|
+
* with, and the session keys and lane the turns run on.
|
|
833
212
|
*
|
|
834
|
-
*
|
|
835
|
-
*
|
|
836
|
-
*
|
|
837
|
-
*
|
|
838
|
-
* hosted MCP tools (`https://api.agentchat.me/mcp`), registered as the MCP
|
|
839
|
-
* server `agentchat` (see `./mcp.ts`).
|
|
213
|
+
* No product text lives here. The wake instruction and the invite prompt are
|
|
214
|
+
* served by AgentChat (`GET /v1/texts`, fetched by `./texts.ts`) and placed
|
|
215
|
+
* by this module; the one line of our own states a fact (which conversation
|
|
216
|
+
* the gate decided to answer), never judgement.
|
|
840
217
|
*
|
|
841
|
-
* OpenClaw exposes an MCP server's tools to the model as
|
|
842
|
-
*
|
|
843
|
-
*
|
|
218
|
+
* OpenClaw exposes an MCP server's tools to the model as `<server>__<tool>`:
|
|
219
|
+
* the tool-policy pipeline builds the namespace prefix as
|
|
220
|
+
* `normalizeToolName(sanitizeServerName(serverName) + "__")`
|
|
844
221
|
* (`openclaw/dist/tool-policy-*.js`, 2026.6.10) and the docs describe the
|
|
845
|
-
* same
|
|
846
|
-
*
|
|
847
|
-
* is
|
|
848
|
-
*
|
|
849
|
-
* Nothing in this module is product text of its own: the wake instruction,
|
|
850
|
-
* the manual, the identity line, the briefing card and the gate question are
|
|
851
|
-
* all written in the main line and only placed by this plugin. The one
|
|
852
|
-
* sentence that is ours states facts (which ids the gate chose), not
|
|
853
|
-
* judgement.
|
|
222
|
+
* same shape (docs.openclaw.ai/tools/mcp). The server spells the hosted
|
|
223
|
+
* tools by their bare names (`agentchat_inbox`); `spellToolsForOpenClaw`
|
|
224
|
+
* re-spells exactly those tokens so the agent is told the names it can call.
|
|
854
225
|
*/
|
|
226
|
+
|
|
855
227
|
/** Name of the MCP server entry this plugin places. Changing it changes every tool name the model sees — keep in lockstep with `./mcp.ts`. */
|
|
856
228
|
declare const MCP_SERVER_NAME = "agentchat";
|
|
857
229
|
/** `agentchat_inbox` → `agentchat__agentchat_inbox`. */
|
|
858
230
|
declare function mcpToolName(tool: string): string;
|
|
859
231
|
/**
|
|
860
|
-
*
|
|
861
|
-
*
|
|
862
|
-
* OpenClaw
|
|
863
|
-
* doorbell; a socket doorbell carries the same text so the agent is
|
|
864
|
-
* addressed the same way whichever doorbell rang. Update together with the
|
|
865
|
-
* server.
|
|
232
|
+
* How OpenClaw spells a hosted tool. Idempotent: a name that already carries
|
|
233
|
+
* the server prefix is returned as is, so a server that one day serves the
|
|
234
|
+
* OpenClaw spelling itself is not prefixed twice.
|
|
866
235
|
*/
|
|
867
|
-
declare const
|
|
868
|
-
|
|
869
|
-
declare
|
|
236
|
+
declare const OPENCLAW_TOOL_NAMER: ToolNamer;
|
|
237
|
+
/** Re-spell every bare hosted tool name in a served text the way OpenClaw exposes it. Pure, idempotent. */
|
|
238
|
+
declare function spellToolsForOpenClaw(text: string): string;
|
|
870
239
|
/**
|
|
871
|
-
* The prompt a
|
|
872
|
-
*
|
|
873
|
-
*
|
|
874
|
-
*
|
|
875
|
-
*
|
|
876
|
-
*
|
|
240
|
+
* The prompt a wake turn starts with: the served wake instruction and, when
|
|
241
|
+
* the gate decided a specific conversation, one factual line naming it. The
|
|
242
|
+
* `reply` verdict is recorded when the turn has completed — never at its
|
|
243
|
+
* start — so while the turn runs the conversation is still unread and its
|
|
244
|
+
* card still on the tray; the line says so, names the conversation to open,
|
|
245
|
+
* and says the verdict is taken care of (recording it in the turn as well is
|
|
246
|
+
* idempotent).
|
|
877
247
|
*/
|
|
878
|
-
declare function
|
|
879
|
-
/** The
|
|
880
|
-
declare function inviteTurnPrompt(): string;
|
|
248
|
+
declare function wakeTurnPrompt(texts: Pick<Texts, 'wake_instruction'>, conversationId?: string): string;
|
|
249
|
+
/** The prompt a group-invite turn starts with: the served invite prompt. */
|
|
250
|
+
declare function inviteTurnPrompt(texts: Pick<Texts, 'invite_prompt'>): string;
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Error taxonomy for the AgentChat channel plugin.
|
|
254
|
+
*
|
|
255
|
+
* Every error that crosses a pipeline boundary (inbound receive, outbound
|
|
256
|
+
* send, config validation, transport) must be classifiable as one of:
|
|
257
|
+
*
|
|
258
|
+
* terminal-auth — 401/403. API key invalid or revoked. Do not retry.
|
|
259
|
+
* Move state machine to AUTH_FAIL.
|
|
260
|
+
* terminal-user — 400/422 (client-side validation). Bug in this plugin
|
|
261
|
+
* or malformed outbound. Log at error level, drop,
|
|
262
|
+
* do not retry.
|
|
263
|
+
* retry-rate — 429. Retry after `retryAfterMs` (or jittered
|
|
264
|
+
* exponential backoff if header absent).
|
|
265
|
+
* retry-transient — 5xx, ECONNRESET, ETIMEDOUT, network flap.
|
|
266
|
+
* Exponential backoff + jitter. Open circuit after N.
|
|
267
|
+
* idempotent-replay — 409 on POST /v1/messages with duplicate
|
|
268
|
+
* client_msg_id. Treat as success, log at info.
|
|
269
|
+
* validation — Zod schema failed on inbound payload. Likely a
|
|
270
|
+
* server change. Log at error, drop, alert.
|
|
271
|
+
*/
|
|
272
|
+
type ErrorClass = 'terminal-auth' | 'terminal-user' | 'retry-rate' | 'retry-transient' | 'idempotent-replay' | 'validation';
|
|
273
|
+
declare class AgentChatChannelError extends Error {
|
|
274
|
+
readonly class_: ErrorClass;
|
|
275
|
+
readonly retryAfterMs: number | undefined;
|
|
276
|
+
readonly statusCode: number | undefined;
|
|
277
|
+
constructor(class_: ErrorClass, message: string, options?: {
|
|
278
|
+
cause?: unknown;
|
|
279
|
+
retryAfterMs?: number;
|
|
280
|
+
statusCode?: number;
|
|
281
|
+
});
|
|
282
|
+
}
|
|
881
283
|
|
|
882
284
|
/**
|
|
883
285
|
* Minimal HTTP client used by the setup plugin (P7) to:
|
|
@@ -1083,4 +485,4 @@ declare function recoverAgentVerify(input: RecoverAgentVerifyInput, opts?: Regis
|
|
|
1083
485
|
*/
|
|
1084
486
|
declare function assertApiKeyValid(apiKey: string, opts?: ValidateApiKeyOptions): Promise<AgentchatAgentIdentity>;
|
|
1085
487
|
|
|
1086
|
-
export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError,
|
|
488
|
+
export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, type EmailPolicyReason, type ErrorClass, MCP_SERVER_NAME, OPENCLAW_TOOL_NAMER, type RecoverAgentStartInput, type RecoverAgentVerifyInput, type RecoverStartResult, type RecoverVerifyResult, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, TextsStore, type ValidateApiKeyOptions, type ValidateApiKeyResult, WakeCoalescer, assertApiKeyValid, hostedMcpServerEntry, hostedMcpSnippet, hostedMcpUrl, inviteTurnPrompt, loadIdentityLine, loadTexts, mcpToolName, probeHostedMcp, recoverAgentStart, recoverAgentVerify, registerAgentStart, registerAgentVerify, spellToolsForOpenClaw, validateApiKey, wakeTurnPrompt };
|