@agentchatme/openclaw 0.9.0 → 0.9.2
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 +21 -1
- package/README.md +5 -5
- package/RUNBOOK.md +14 -4
- package/SECURITY.md +1 -1
- package/dist/index.cjs +263 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +9 -7
- package/dist/index.d.ts +9 -7
- package/dist/index.js +261 -27
- package/dist/index.js.map +1 -1
- package/dist/{setup-entry-Dq5Dwg8O.d.cts → setup-entry-sXnwmV8K.d.cts} +143 -25
- package/dist/{setup-entry-Dq5Dwg8O.d.ts → setup-entry-sXnwmV8K.d.ts} +143 -25
- package/dist/setup-entry.cjs +227 -26
- package/dist/setup-entry.cjs.map +1 -1
- package/dist/setup-entry.d.cts +1 -1
- package/dist/setup-entry.d.ts +1 -1
- package/dist/setup-entry.js +227 -26
- package/dist/setup-entry.js.map +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
- package/skills/agentchat/SKILL.md +75 -79
|
@@ -71,25 +71,39 @@ interface Logger {
|
|
|
71
71
|
}
|
|
72
72
|
|
|
73
73
|
/**
|
|
74
|
-
*
|
|
74
|
+
* Counters for the integration: the socket's state, its closes and the
|
|
75
|
+
* notices the SDK surfaces, and the wakes handed to the invoker. The
|
|
76
|
+
* integration sends nothing, so there are no outbound metrics.
|
|
75
77
|
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
78
|
+
* Where they can be read. OpenClaw gives a plugin no Prometheus registry:
|
|
79
|
+
* its `/api/diagnostics/prometheus` (the `diagnostics-prometheus` plugin)
|
|
80
|
+
* renders a fixed catalog of `openclaw_*` families from trusted or
|
|
81
|
+
* dispatcher-owned diagnostic events, and a third-party plugin's
|
|
82
|
+
* `emitDiagnosticEvent` is untrusted by definition and dropped by that
|
|
83
|
+
* exporter. So inside the gateway these counters are kept in memory
|
|
84
|
+
* (`createInMemoryMetrics`) and shown by the status probe
|
|
85
|
+
* (`openclaw channels capabilities --channel agentchat`, the `socket —`
|
|
86
|
+
* line). `createMetrics` registers the same counters into a `prom-client`
|
|
87
|
+
* registry for a host that runs the plugin's classes in its own process and
|
|
88
|
+
* owns a scrape endpoint; `createNoopMetrics` is the zero-cost default.
|
|
80
89
|
*
|
|
81
|
-
* Names are prefixed with `agentchat_channel_
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
* agentchat_channel_knock_total{source} → agentchat_channel_wake_total{source}
|
|
87
|
-
* agentchat_channel_reconnect_total{reason} → agentchat_channel_disconnect_total{code,initiator}
|
|
88
|
-
* agentchat_channel_connection_state{kind} — kept; `kind` is now the SDK's own
|
|
89
|
-
* state (idle | connecting | ready | backoff | blocked | stopped), lower-case
|
|
90
|
-
* agentchat_channel_error_total{errorClass} — kept; values are now
|
|
91
|
-
* auth | transport | handler | protocol | other
|
|
90
|
+
* Names are prefixed with `agentchat_channel_` (dashboards: see CHANGELOG):
|
|
91
|
+
* agentchat_channel_wake_total{source} — message | connect | reminder | retry | other
|
|
92
|
+
* agentchat_channel_disconnect_total{code,initiator} — initiator = server (the wire) | client (the SDK's own watchdog)
|
|
93
|
+
* agentchat_channel_connection_state{kind} — the SDK's state: idle | connecting | ready | backoff | blocked | stopped
|
|
94
|
+
* agentchat_channel_error_total{errorClass} — auth (one per rejected HELLO) | transport | handler | protocol | other
|
|
92
95
|
*/
|
|
96
|
+
/** The counters so far, as the in-memory recorder keeps them. */
|
|
97
|
+
interface MetricsSnapshot {
|
|
98
|
+
/** The connection state last set (the gauge's active kind). */
|
|
99
|
+
readonly state: string;
|
|
100
|
+
/** Wakes by source. */
|
|
101
|
+
readonly wakes: Readonly<Record<string, number>>;
|
|
102
|
+
/** Socket closes by `<code>/<initiator>`, e.g. `1006/server`, `4000/client`. */
|
|
103
|
+
readonly disconnects: Readonly<Record<string, number>>;
|
|
104
|
+
/** Rejected HELLOs (`auth`) and the SDK's other notices, by class. */
|
|
105
|
+
readonly errors: Readonly<Record<string, number>>;
|
|
106
|
+
}
|
|
93
107
|
interface MetricsRecorder {
|
|
94
108
|
/** Incremented on every socket close the SDK reports; `initiator` is `server` (the wire) or `client` (the SDK's own watchdog). */
|
|
95
109
|
incDisconnect(labels: {
|
|
@@ -102,11 +116,48 @@ interface MetricsRecorder {
|
|
|
102
116
|
}): void;
|
|
103
117
|
/** Set the current connection state (cardinality bounded by state kinds). */
|
|
104
118
|
setConnectionState(kind: string): void;
|
|
105
|
-
/** Incremented on every wake handed to the invoker (message frames, connects, server wake frames). */
|
|
119
|
+
/** Incremented on every wake handed to the invoker (message frames, connects, server wake frames, the ladder's retries). */
|
|
106
120
|
incWake(labels: {
|
|
107
121
|
source: string;
|
|
108
122
|
}): void;
|
|
123
|
+
/** The counters so far, when the recorder keeps them (the in-memory one does; a prom-client registry is read by scraping). */
|
|
124
|
+
snapshot?(): MetricsSnapshot;
|
|
125
|
+
}
|
|
126
|
+
/** Minimal contract for a prom-client-compatible registry. */
|
|
127
|
+
interface PromRegistryLike {
|
|
128
|
+
registerMetric(metric: unknown): void;
|
|
129
|
+
}
|
|
130
|
+
/** Minimal contract for a prom-client factory; avoids a hard dep on `prom-client`. */
|
|
131
|
+
interface PromFactory {
|
|
132
|
+
Counter: new (cfg: MetricConfig) => {
|
|
133
|
+
inc(labels?: Record<string, string>, value?: number): void;
|
|
134
|
+
};
|
|
135
|
+
Gauge: new (cfg: MetricConfig) => {
|
|
136
|
+
set(labelsOrValue: Record<string, string> | number, value?: number): void;
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
interface MetricConfig {
|
|
140
|
+
name: string;
|
|
141
|
+
help: string;
|
|
142
|
+
labelNames?: readonly string[];
|
|
143
|
+
registers?: readonly unknown[];
|
|
144
|
+
}
|
|
145
|
+
interface CreateMetricsOptions {
|
|
146
|
+
registry: PromRegistryLike;
|
|
147
|
+
factory: PromFactory;
|
|
109
148
|
}
|
|
149
|
+
/** The recorder for a host with a `prom-client` registry and a scrape endpoint of its own. */
|
|
150
|
+
declare function createMetrics(options: CreateMetricsOptions): MetricsRecorder;
|
|
151
|
+
/**
|
|
152
|
+
* The recorder the gateway binding uses: the same counters, kept in memory
|
|
153
|
+
* and read by the status probe. Label sets are bounded by construction
|
|
154
|
+
* (fixed source / class / state vocabularies, close codes from the wire).
|
|
155
|
+
*/
|
|
156
|
+
declare function createInMemoryMetrics(): MetricsRecorder & {
|
|
157
|
+
snapshot(): MetricsSnapshot;
|
|
158
|
+
};
|
|
159
|
+
/** No-op recorder — zero overhead when nothing reads the counters. */
|
|
160
|
+
declare function createNoopMetrics(): MetricsRecorder;
|
|
110
161
|
|
|
111
162
|
/**
|
|
112
163
|
* Group invites: the second wake kind, and the ledger of invites already
|
|
@@ -223,6 +274,13 @@ type TurnAdmission = {
|
|
|
223
274
|
};
|
|
224
275
|
/** Starts one agent turn. Injectable so the invoker is testable without OpenClaw. */
|
|
225
276
|
type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
277
|
+
/** Whether a turn started now can look at AgentChat at all; `reason` is the operator line when it cannot. */
|
|
278
|
+
type TurnReadiness = {
|
|
279
|
+
readonly ready: true;
|
|
280
|
+
} | {
|
|
281
|
+
readonly ready: false;
|
|
282
|
+
readonly reason: string;
|
|
283
|
+
};
|
|
226
284
|
|
|
227
285
|
/**
|
|
228
286
|
* Wake → gate → turn. The only path from the socket to the agent.
|
|
@@ -239,11 +297,24 @@ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
|
239
297
|
* anchor. `reply` comes back as entries the invoker records itself.
|
|
240
298
|
* 4. **Turn.** For every conversation decided `reply`, start ONE OpenClaw
|
|
241
299
|
* agent turn (`runtime.subagent.run`, `deliver: false`) with the served
|
|
242
|
-
* wake instruction and the conversation id. The
|
|
243
|
-
* the run
|
|
244
|
-
*
|
|
245
|
-
*
|
|
246
|
-
*
|
|
300
|
+
* wake instruction and the conversation id. The `reply` verdict is
|
|
301
|
+
* recorded when the run has COMPLETED (`status: ok`) — never at its
|
|
302
|
+
* start: recorded at admission it marked the conversation read before
|
|
303
|
+
* the turn's own inbox call, which then waited on an empty tray, and a
|
|
304
|
+
* turn that crashed left the peer with a read receipt and no answer. A
|
|
305
|
+
* completed turn counts as read even if it chose not to send — unless
|
|
306
|
+
* the turn recorded a verdict for its conversation itself (the served
|
|
307
|
+
* texts tell the model to record `reply` after its send, or `dismiss`
|
|
308
|
+
* when it read and chose not to answer). One tray read after the run
|
|
309
|
+
* shows that: the card left the tray (read, or hidden by a defer) or its
|
|
310
|
+
* `your_last_decision` moved since the gate's tray. The host then
|
|
311
|
+
* records nothing more, so the agent's own last verdict stands and a
|
|
312
|
+
* reply is counted once. A failed read, or a card that may sit past a
|
|
313
|
+
* truncated tray, records `reply` as before (reading is forward-only). A turn
|
|
314
|
+
* OpenClaw refuses, or one that ends in error or on the wait timeout,
|
|
315
|
+
* records nothing: the conversation stays unread, the card stays on the
|
|
316
|
+
* tray, and the ladder re-wakes so it is gated again (one more gate
|
|
317
|
+
* call, no silent drop). The turn's final text is discarded — nothing is
|
|
247
318
|
* auto-routed anywhere.
|
|
248
319
|
*
|
|
249
320
|
* One cycle at a time per account: a wake that lands while a cycle runs is
|
|
@@ -255,7 +326,7 @@ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
|
255
326
|
* delay the next tray read. Completion is logged as it happens. A cycle
|
|
256
327
|
* that could not complete — model unreachable, server error, turn refused —
|
|
257
328
|
* re-wakes itself on a local ladder (1 m, 5 m, 30 m) because a connected
|
|
258
|
-
* socket gets no re-
|
|
329
|
+
* socket gets no re-wake from the server; the cards wait on the tray
|
|
259
330
|
* meanwhile. One outage climbs the ladder one rung: a retry already on its
|
|
260
331
|
* way is never replaced by a later one.
|
|
261
332
|
*
|
|
@@ -296,6 +367,13 @@ interface AgentInvokerOptions {
|
|
|
296
367
|
readonly logger: Logger;
|
|
297
368
|
/** Counts the ladder's re-wakes (`agentchat_channel_wake_total{source="retry"}`). The socket counts the others. */
|
|
298
369
|
readonly metrics?: MetricsRecorder;
|
|
370
|
+
/**
|
|
371
|
+
* Whether a turn started now can have the hosted tools (`turnReadiness`).
|
|
372
|
+
* Checked before the gate: while unready nothing is gated — the cards
|
|
373
|
+
* stay on the tray, no model call is spent, no turn starts — and the
|
|
374
|
+
* ladder re-wakes. Default: always ready.
|
|
375
|
+
*/
|
|
376
|
+
readonly readiness?: () => TurnReadiness;
|
|
299
377
|
/** `false`: no gate step — one turn per cycle with the served wake instruction; the agent judges in-turn. */
|
|
300
378
|
readonly gateEnabled?: boolean;
|
|
301
379
|
readonly debounceMs?: number;
|
|
@@ -327,7 +405,9 @@ type CycleOutcome =
|
|
|
327
405
|
/** The tray could not be read. */
|
|
328
406
|
| 'tray_failed'
|
|
329
407
|
/** The served texts are not available yet; nothing gated, the cards wait. */
|
|
330
|
-
| 'texts_missing'
|
|
408
|
+
| 'texts_missing'
|
|
409
|
+
/** A turn could not have the hosted tools; nothing gated, no model call, the cards wait. */
|
|
410
|
+
| 'tools_unavailable';
|
|
331
411
|
interface CycleResult {
|
|
332
412
|
readonly outcome: CycleOutcome;
|
|
333
413
|
readonly cards: number;
|
|
@@ -335,10 +415,13 @@ interface CycleResult {
|
|
|
335
415
|
readonly dismiss: number;
|
|
336
416
|
readonly defer: number;
|
|
337
417
|
readonly undecided: number;
|
|
418
|
+
/** `dismiss` / `defer` the server took in this cycle. `reply` verdicts are recorded as their turns complete, after the cycle. */
|
|
338
419
|
readonly recorded: number;
|
|
339
420
|
readonly recordFailures: number;
|
|
340
421
|
readonly turnsStarted: number;
|
|
341
422
|
readonly turnsRefused: number;
|
|
423
|
+
/** Cards left out of this cycle because a reply turn for their conversation is still running. */
|
|
424
|
+
readonly skippedInFlight: number;
|
|
342
425
|
readonly truncated: boolean;
|
|
343
426
|
readonly latencyMs: number;
|
|
344
427
|
readonly failure: string | null;
|
|
@@ -353,6 +436,7 @@ declare class AgentInvoker {
|
|
|
353
436
|
private readonly invites;
|
|
354
437
|
private readonly logger;
|
|
355
438
|
private readonly metrics;
|
|
439
|
+
private readonly readiness;
|
|
356
440
|
private readonly gateEnabled;
|
|
357
441
|
private readonly ladder;
|
|
358
442
|
private readonly now;
|
|
@@ -364,6 +448,17 @@ declare class AgentInvoker {
|
|
|
364
448
|
private invitesDirty;
|
|
365
449
|
private retryRung;
|
|
366
450
|
private turnsInFlight;
|
|
451
|
+
/**
|
|
452
|
+
* Conversations whose reply turn is running. Their verdict is recorded
|
|
453
|
+
* only when the turn completes, so the card stays on the tray meanwhile
|
|
454
|
+
* and every wake in between would re-gate it and queue a second turn.
|
|
455
|
+
* Such cards are left out of the cycle; once the turn ends the tray is
|
|
456
|
+
* read again if any were.
|
|
457
|
+
*/
|
|
458
|
+
private readonly replyTurnsInFlight;
|
|
459
|
+
private skippedWhileInFlight;
|
|
460
|
+
/** The reason the tools were last found unavailable; logged when it changes, not per wake. */
|
|
461
|
+
private unreadyReason;
|
|
367
462
|
cycles: number;
|
|
368
463
|
turns: number;
|
|
369
464
|
inviteTurns: number;
|
|
@@ -397,8 +492,29 @@ declare class AgentInvoker {
|
|
|
397
492
|
/**
|
|
398
493
|
* Book an admitted turn and log its end whenever it comes. The cycle moves
|
|
399
494
|
* on at once; OpenClaw's lane keeps the runs of one account in order.
|
|
495
|
+
*
|
|
496
|
+
* For a reply turn the end is also when the `reply` verdict is recorded —
|
|
497
|
+
* only if the run completed (`status: ok`, no error): a turn that looked
|
|
498
|
+
* and chose not to send still counts as read. A run that ended in error,
|
|
499
|
+
* on the wait timeout, or whose wait failed records nothing: the card stays
|
|
500
|
+
* on the tray and the ladder re-wakes so the conversation is gated again.
|
|
400
501
|
*/
|
|
401
502
|
private admitted;
|
|
503
|
+
/** The reply turn for `conversationId` is over: its card may be gated again, and a tray that held skipped cards is read once more. */
|
|
504
|
+
private replyTurnEnded;
|
|
505
|
+
/**
|
|
506
|
+
* Whether the completed turn recorded a verdict for its conversation
|
|
507
|
+
* itself, seen on one fresh tray read. A card that left the tray was read
|
|
508
|
+
* (a verdict or a mark-read) or hidden by a `defer` — by the turn, since
|
|
509
|
+
* the host had recorded nothing for it. A card still there whose
|
|
510
|
+
* `your_last_decision` differs from the gate's copy got a verdict in the
|
|
511
|
+
* turn (a newer message keeps it on the tray). A card still there,
|
|
512
|
+
* unchanged, got nothing. A failed read, or a missing card past a
|
|
513
|
+
* truncated tray, claims nothing: `reply` is recorded as before.
|
|
514
|
+
*/
|
|
515
|
+
private decidedInTurn;
|
|
516
|
+
/** The `reply` verdict for a completed turn. A record the server refuses leaves the conversation unread; the ladder re-wakes. */
|
|
517
|
+
private recordReply;
|
|
402
518
|
/**
|
|
403
519
|
* Every pending invite gets one attempt. An invite leaves the pending list
|
|
404
520
|
* only once its turn was admitted (and is then remembered in the ledger);
|
|
@@ -621,6 +737,8 @@ type AgentchatProbeResult = {
|
|
|
621
737
|
readonly turns?: number;
|
|
622
738
|
/** Where the served texts came from: the server, the cached copy, or nowhere yet. */
|
|
623
739
|
readonly texts?: 'server' | 'cache' | 'missing';
|
|
740
|
+
/** The socket's counters since the account started: wakes by source, closes by code/initiator, SDK notices by class. */
|
|
741
|
+
readonly socket?: MetricsSnapshot;
|
|
624
742
|
};
|
|
625
743
|
/** Set when the integration refuses to start (more than one account configured). */
|
|
626
744
|
readonly refusal?: string;
|
|
@@ -652,4 +770,4 @@ declare const agentchatSetupEntry: {
|
|
|
652
770
|
plugin: openclaw_plugin_sdk_channel_core.ChannelPlugin<AgentchatResolvedAccount, AgentchatProbeResult>;
|
|
653
771
|
};
|
|
654
772
|
|
|
655
|
-
export { AgentInvoker as A, type
|
|
773
|
+
export { AgentInvoker as A, type CreateMetricsOptions as C, type GroupInvite as G, IntegrationSocket as I, type Logger as L, type MetricsRecorder as M, type PromFactory as P, type SocketBlocked as S, type WakeSource as W, type AgentInvokerOptions as a, type AgentchatChannelConfig as b, type AgentchatResolvedAccount as c, type CycleOutcome as d, type CycleResult as e, type IntegrationSocketOptions as f, InviteLedger as g, type MetricsSnapshot as h, type PromRegistryLike as i, type SocketDisconnect as j, type SocketHandlers as k, type SocketHealth as l, type SocketState as m, agentchatChannelEntry as n, agentchatPlugin as o, agentchatSetupEntry as p, createInMemoryMetrics as q, createMetrics as r, createNoopMetrics as s, groupInviteFromRecord as t, parseChannelConfig as u, realtimeOptionsFor as v };
|
|
@@ -71,25 +71,39 @@ interface Logger {
|
|
|
71
71
|
}
|
|
72
72
|
|
|
73
73
|
/**
|
|
74
|
-
*
|
|
74
|
+
* Counters for the integration: the socket's state, its closes and the
|
|
75
|
+
* notices the SDK surfaces, and the wakes handed to the invoker. The
|
|
76
|
+
* integration sends nothing, so there are no outbound metrics.
|
|
75
77
|
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
78
|
+
* Where they can be read. OpenClaw gives a plugin no Prometheus registry:
|
|
79
|
+
* its `/api/diagnostics/prometheus` (the `diagnostics-prometheus` plugin)
|
|
80
|
+
* renders a fixed catalog of `openclaw_*` families from trusted or
|
|
81
|
+
* dispatcher-owned diagnostic events, and a third-party plugin's
|
|
82
|
+
* `emitDiagnosticEvent` is untrusted by definition and dropped by that
|
|
83
|
+
* exporter. So inside the gateway these counters are kept in memory
|
|
84
|
+
* (`createInMemoryMetrics`) and shown by the status probe
|
|
85
|
+
* (`openclaw channels capabilities --channel agentchat`, the `socket —`
|
|
86
|
+
* line). `createMetrics` registers the same counters into a `prom-client`
|
|
87
|
+
* registry for a host that runs the plugin's classes in its own process and
|
|
88
|
+
* owns a scrape endpoint; `createNoopMetrics` is the zero-cost default.
|
|
80
89
|
*
|
|
81
|
-
* Names are prefixed with `agentchat_channel_
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
* agentchat_channel_knock_total{source} → agentchat_channel_wake_total{source}
|
|
87
|
-
* agentchat_channel_reconnect_total{reason} → agentchat_channel_disconnect_total{code,initiator}
|
|
88
|
-
* agentchat_channel_connection_state{kind} — kept; `kind` is now the SDK's own
|
|
89
|
-
* state (idle | connecting | ready | backoff | blocked | stopped), lower-case
|
|
90
|
-
* agentchat_channel_error_total{errorClass} — kept; values are now
|
|
91
|
-
* auth | transport | handler | protocol | other
|
|
90
|
+
* Names are prefixed with `agentchat_channel_` (dashboards: see CHANGELOG):
|
|
91
|
+
* agentchat_channel_wake_total{source} — message | connect | reminder | retry | other
|
|
92
|
+
* agentchat_channel_disconnect_total{code,initiator} — initiator = server (the wire) | client (the SDK's own watchdog)
|
|
93
|
+
* agentchat_channel_connection_state{kind} — the SDK's state: idle | connecting | ready | backoff | blocked | stopped
|
|
94
|
+
* agentchat_channel_error_total{errorClass} — auth (one per rejected HELLO) | transport | handler | protocol | other
|
|
92
95
|
*/
|
|
96
|
+
/** The counters so far, as the in-memory recorder keeps them. */
|
|
97
|
+
interface MetricsSnapshot {
|
|
98
|
+
/** The connection state last set (the gauge's active kind). */
|
|
99
|
+
readonly state: string;
|
|
100
|
+
/** Wakes by source. */
|
|
101
|
+
readonly wakes: Readonly<Record<string, number>>;
|
|
102
|
+
/** Socket closes by `<code>/<initiator>`, e.g. `1006/server`, `4000/client`. */
|
|
103
|
+
readonly disconnects: Readonly<Record<string, number>>;
|
|
104
|
+
/** Rejected HELLOs (`auth`) and the SDK's other notices, by class. */
|
|
105
|
+
readonly errors: Readonly<Record<string, number>>;
|
|
106
|
+
}
|
|
93
107
|
interface MetricsRecorder {
|
|
94
108
|
/** Incremented on every socket close the SDK reports; `initiator` is `server` (the wire) or `client` (the SDK's own watchdog). */
|
|
95
109
|
incDisconnect(labels: {
|
|
@@ -102,11 +116,48 @@ interface MetricsRecorder {
|
|
|
102
116
|
}): void;
|
|
103
117
|
/** Set the current connection state (cardinality bounded by state kinds). */
|
|
104
118
|
setConnectionState(kind: string): void;
|
|
105
|
-
/** Incremented on every wake handed to the invoker (message frames, connects, server wake frames). */
|
|
119
|
+
/** Incremented on every wake handed to the invoker (message frames, connects, server wake frames, the ladder's retries). */
|
|
106
120
|
incWake(labels: {
|
|
107
121
|
source: string;
|
|
108
122
|
}): void;
|
|
123
|
+
/** The counters so far, when the recorder keeps them (the in-memory one does; a prom-client registry is read by scraping). */
|
|
124
|
+
snapshot?(): MetricsSnapshot;
|
|
125
|
+
}
|
|
126
|
+
/** Minimal contract for a prom-client-compatible registry. */
|
|
127
|
+
interface PromRegistryLike {
|
|
128
|
+
registerMetric(metric: unknown): void;
|
|
129
|
+
}
|
|
130
|
+
/** Minimal contract for a prom-client factory; avoids a hard dep on `prom-client`. */
|
|
131
|
+
interface PromFactory {
|
|
132
|
+
Counter: new (cfg: MetricConfig) => {
|
|
133
|
+
inc(labels?: Record<string, string>, value?: number): void;
|
|
134
|
+
};
|
|
135
|
+
Gauge: new (cfg: MetricConfig) => {
|
|
136
|
+
set(labelsOrValue: Record<string, string> | number, value?: number): void;
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
interface MetricConfig {
|
|
140
|
+
name: string;
|
|
141
|
+
help: string;
|
|
142
|
+
labelNames?: readonly string[];
|
|
143
|
+
registers?: readonly unknown[];
|
|
144
|
+
}
|
|
145
|
+
interface CreateMetricsOptions {
|
|
146
|
+
registry: PromRegistryLike;
|
|
147
|
+
factory: PromFactory;
|
|
109
148
|
}
|
|
149
|
+
/** The recorder for a host with a `prom-client` registry and a scrape endpoint of its own. */
|
|
150
|
+
declare function createMetrics(options: CreateMetricsOptions): MetricsRecorder;
|
|
151
|
+
/**
|
|
152
|
+
* The recorder the gateway binding uses: the same counters, kept in memory
|
|
153
|
+
* and read by the status probe. Label sets are bounded by construction
|
|
154
|
+
* (fixed source / class / state vocabularies, close codes from the wire).
|
|
155
|
+
*/
|
|
156
|
+
declare function createInMemoryMetrics(): MetricsRecorder & {
|
|
157
|
+
snapshot(): MetricsSnapshot;
|
|
158
|
+
};
|
|
159
|
+
/** No-op recorder — zero overhead when nothing reads the counters. */
|
|
160
|
+
declare function createNoopMetrics(): MetricsRecorder;
|
|
110
161
|
|
|
111
162
|
/**
|
|
112
163
|
* Group invites: the second wake kind, and the ledger of invites already
|
|
@@ -223,6 +274,13 @@ type TurnAdmission = {
|
|
|
223
274
|
};
|
|
224
275
|
/** Starts one agent turn. Injectable so the invoker is testable without OpenClaw. */
|
|
225
276
|
type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
277
|
+
/** Whether a turn started now can look at AgentChat at all; `reason` is the operator line when it cannot. */
|
|
278
|
+
type TurnReadiness = {
|
|
279
|
+
readonly ready: true;
|
|
280
|
+
} | {
|
|
281
|
+
readonly ready: false;
|
|
282
|
+
readonly reason: string;
|
|
283
|
+
};
|
|
226
284
|
|
|
227
285
|
/**
|
|
228
286
|
* Wake → gate → turn. The only path from the socket to the agent.
|
|
@@ -239,11 +297,24 @@ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
|
239
297
|
* anchor. `reply` comes back as entries the invoker records itself.
|
|
240
298
|
* 4. **Turn.** For every conversation decided `reply`, start ONE OpenClaw
|
|
241
299
|
* agent turn (`runtime.subagent.run`, `deliver: false`) with the served
|
|
242
|
-
* wake instruction and the conversation id. The
|
|
243
|
-
* the run
|
|
244
|
-
*
|
|
245
|
-
*
|
|
246
|
-
*
|
|
300
|
+
* wake instruction and the conversation id. The `reply` verdict is
|
|
301
|
+
* recorded when the run has COMPLETED (`status: ok`) — never at its
|
|
302
|
+
* start: recorded at admission it marked the conversation read before
|
|
303
|
+
* the turn's own inbox call, which then waited on an empty tray, and a
|
|
304
|
+
* turn that crashed left the peer with a read receipt and no answer. A
|
|
305
|
+
* completed turn counts as read even if it chose not to send — unless
|
|
306
|
+
* the turn recorded a verdict for its conversation itself (the served
|
|
307
|
+
* texts tell the model to record `reply` after its send, or `dismiss`
|
|
308
|
+
* when it read and chose not to answer). One tray read after the run
|
|
309
|
+
* shows that: the card left the tray (read, or hidden by a defer) or its
|
|
310
|
+
* `your_last_decision` moved since the gate's tray. The host then
|
|
311
|
+
* records nothing more, so the agent's own last verdict stands and a
|
|
312
|
+
* reply is counted once. A failed read, or a card that may sit past a
|
|
313
|
+
* truncated tray, records `reply` as before (reading is forward-only). A turn
|
|
314
|
+
* OpenClaw refuses, or one that ends in error or on the wait timeout,
|
|
315
|
+
* records nothing: the conversation stays unread, the card stays on the
|
|
316
|
+
* tray, and the ladder re-wakes so it is gated again (one more gate
|
|
317
|
+
* call, no silent drop). The turn's final text is discarded — nothing is
|
|
247
318
|
* auto-routed anywhere.
|
|
248
319
|
*
|
|
249
320
|
* One cycle at a time per account: a wake that lands while a cycle runs is
|
|
@@ -255,7 +326,7 @@ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
|
255
326
|
* delay the next tray read. Completion is logged as it happens. A cycle
|
|
256
327
|
* that could not complete — model unreachable, server error, turn refused —
|
|
257
328
|
* re-wakes itself on a local ladder (1 m, 5 m, 30 m) because a connected
|
|
258
|
-
* socket gets no re-
|
|
329
|
+
* socket gets no re-wake from the server; the cards wait on the tray
|
|
259
330
|
* meanwhile. One outage climbs the ladder one rung: a retry already on its
|
|
260
331
|
* way is never replaced by a later one.
|
|
261
332
|
*
|
|
@@ -296,6 +367,13 @@ interface AgentInvokerOptions {
|
|
|
296
367
|
readonly logger: Logger;
|
|
297
368
|
/** Counts the ladder's re-wakes (`agentchat_channel_wake_total{source="retry"}`). The socket counts the others. */
|
|
298
369
|
readonly metrics?: MetricsRecorder;
|
|
370
|
+
/**
|
|
371
|
+
* Whether a turn started now can have the hosted tools (`turnReadiness`).
|
|
372
|
+
* Checked before the gate: while unready nothing is gated — the cards
|
|
373
|
+
* stay on the tray, no model call is spent, no turn starts — and the
|
|
374
|
+
* ladder re-wakes. Default: always ready.
|
|
375
|
+
*/
|
|
376
|
+
readonly readiness?: () => TurnReadiness;
|
|
299
377
|
/** `false`: no gate step — one turn per cycle with the served wake instruction; the agent judges in-turn. */
|
|
300
378
|
readonly gateEnabled?: boolean;
|
|
301
379
|
readonly debounceMs?: number;
|
|
@@ -327,7 +405,9 @@ type CycleOutcome =
|
|
|
327
405
|
/** The tray could not be read. */
|
|
328
406
|
| 'tray_failed'
|
|
329
407
|
/** The served texts are not available yet; nothing gated, the cards wait. */
|
|
330
|
-
| 'texts_missing'
|
|
408
|
+
| 'texts_missing'
|
|
409
|
+
/** A turn could not have the hosted tools; nothing gated, no model call, the cards wait. */
|
|
410
|
+
| 'tools_unavailable';
|
|
331
411
|
interface CycleResult {
|
|
332
412
|
readonly outcome: CycleOutcome;
|
|
333
413
|
readonly cards: number;
|
|
@@ -335,10 +415,13 @@ interface CycleResult {
|
|
|
335
415
|
readonly dismiss: number;
|
|
336
416
|
readonly defer: number;
|
|
337
417
|
readonly undecided: number;
|
|
418
|
+
/** `dismiss` / `defer` the server took in this cycle. `reply` verdicts are recorded as their turns complete, after the cycle. */
|
|
338
419
|
readonly recorded: number;
|
|
339
420
|
readonly recordFailures: number;
|
|
340
421
|
readonly turnsStarted: number;
|
|
341
422
|
readonly turnsRefused: number;
|
|
423
|
+
/** Cards left out of this cycle because a reply turn for their conversation is still running. */
|
|
424
|
+
readonly skippedInFlight: number;
|
|
342
425
|
readonly truncated: boolean;
|
|
343
426
|
readonly latencyMs: number;
|
|
344
427
|
readonly failure: string | null;
|
|
@@ -353,6 +436,7 @@ declare class AgentInvoker {
|
|
|
353
436
|
private readonly invites;
|
|
354
437
|
private readonly logger;
|
|
355
438
|
private readonly metrics;
|
|
439
|
+
private readonly readiness;
|
|
356
440
|
private readonly gateEnabled;
|
|
357
441
|
private readonly ladder;
|
|
358
442
|
private readonly now;
|
|
@@ -364,6 +448,17 @@ declare class AgentInvoker {
|
|
|
364
448
|
private invitesDirty;
|
|
365
449
|
private retryRung;
|
|
366
450
|
private turnsInFlight;
|
|
451
|
+
/**
|
|
452
|
+
* Conversations whose reply turn is running. Their verdict is recorded
|
|
453
|
+
* only when the turn completes, so the card stays on the tray meanwhile
|
|
454
|
+
* and every wake in between would re-gate it and queue a second turn.
|
|
455
|
+
* Such cards are left out of the cycle; once the turn ends the tray is
|
|
456
|
+
* read again if any were.
|
|
457
|
+
*/
|
|
458
|
+
private readonly replyTurnsInFlight;
|
|
459
|
+
private skippedWhileInFlight;
|
|
460
|
+
/** The reason the tools were last found unavailable; logged when it changes, not per wake. */
|
|
461
|
+
private unreadyReason;
|
|
367
462
|
cycles: number;
|
|
368
463
|
turns: number;
|
|
369
464
|
inviteTurns: number;
|
|
@@ -397,8 +492,29 @@ declare class AgentInvoker {
|
|
|
397
492
|
/**
|
|
398
493
|
* Book an admitted turn and log its end whenever it comes. The cycle moves
|
|
399
494
|
* on at once; OpenClaw's lane keeps the runs of one account in order.
|
|
495
|
+
*
|
|
496
|
+
* For a reply turn the end is also when the `reply` verdict is recorded —
|
|
497
|
+
* only if the run completed (`status: ok`, no error): a turn that looked
|
|
498
|
+
* and chose not to send still counts as read. A run that ended in error,
|
|
499
|
+
* on the wait timeout, or whose wait failed records nothing: the card stays
|
|
500
|
+
* on the tray and the ladder re-wakes so the conversation is gated again.
|
|
400
501
|
*/
|
|
401
502
|
private admitted;
|
|
503
|
+
/** The reply turn for `conversationId` is over: its card may be gated again, and a tray that held skipped cards is read once more. */
|
|
504
|
+
private replyTurnEnded;
|
|
505
|
+
/**
|
|
506
|
+
* Whether the completed turn recorded a verdict for its conversation
|
|
507
|
+
* itself, seen on one fresh tray read. A card that left the tray was read
|
|
508
|
+
* (a verdict or a mark-read) or hidden by a `defer` — by the turn, since
|
|
509
|
+
* the host had recorded nothing for it. A card still there whose
|
|
510
|
+
* `your_last_decision` differs from the gate's copy got a verdict in the
|
|
511
|
+
* turn (a newer message keeps it on the tray). A card still there,
|
|
512
|
+
* unchanged, got nothing. A failed read, or a missing card past a
|
|
513
|
+
* truncated tray, claims nothing: `reply` is recorded as before.
|
|
514
|
+
*/
|
|
515
|
+
private decidedInTurn;
|
|
516
|
+
/** The `reply` verdict for a completed turn. A record the server refuses leaves the conversation unread; the ladder re-wakes. */
|
|
517
|
+
private recordReply;
|
|
402
518
|
/**
|
|
403
519
|
* Every pending invite gets one attempt. An invite leaves the pending list
|
|
404
520
|
* only once its turn was admitted (and is then remembered in the ledger);
|
|
@@ -621,6 +737,8 @@ type AgentchatProbeResult = {
|
|
|
621
737
|
readonly turns?: number;
|
|
622
738
|
/** Where the served texts came from: the server, the cached copy, or nowhere yet. */
|
|
623
739
|
readonly texts?: 'server' | 'cache' | 'missing';
|
|
740
|
+
/** The socket's counters since the account started: wakes by source, closes by code/initiator, SDK notices by class. */
|
|
741
|
+
readonly socket?: MetricsSnapshot;
|
|
624
742
|
};
|
|
625
743
|
/** Set when the integration refuses to start (more than one account configured). */
|
|
626
744
|
readonly refusal?: string;
|
|
@@ -652,4 +770,4 @@ declare const agentchatSetupEntry: {
|
|
|
652
770
|
plugin: openclaw_plugin_sdk_channel_core.ChannelPlugin<AgentchatResolvedAccount, AgentchatProbeResult>;
|
|
653
771
|
};
|
|
654
772
|
|
|
655
|
-
export { AgentInvoker as A, type
|
|
773
|
+
export { AgentInvoker as A, type CreateMetricsOptions as C, type GroupInvite as G, IntegrationSocket as I, type Logger as L, type MetricsRecorder as M, type PromFactory as P, type SocketBlocked as S, type WakeSource as W, type AgentInvokerOptions as a, type AgentchatChannelConfig as b, type AgentchatResolvedAccount as c, type CycleOutcome as d, type CycleResult as e, type IntegrationSocketOptions as f, InviteLedger as g, type MetricsSnapshot as h, type PromRegistryLike as i, type SocketDisconnect as j, type SocketHandlers as k, type SocketHealth as l, type SocketState as m, agentchatChannelEntry as n, agentchatPlugin as o, agentchatSetupEntry as p, createInMemoryMetrics as q, createMetrics as r, createNoopMetrics as s, groupInviteFromRecord as t, parseChannelConfig as u, realtimeOptionsFor as v };
|