@agentchatme/openclaw 0.9.0 → 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 +12 -0
- package/README.md +4 -4
- package/RUNBOOK.md +14 -4
- package/SECURITY.md +1 -1
- package/dist/index.cjs +229 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +7 -7
- package/dist/index.d.ts +7 -7
- package/dist/index.js +227 -27
- package/dist/index.js.map +1 -1
- package/dist/{setup-entry-Dq5Dwg8O.d.cts → setup-entry-Dh6dRH2F.d.cts} +124 -25
- package/dist/{setup-entry-Dq5Dwg8O.d.ts → setup-entry-Dh6dRH2F.d.ts} +124 -25
- package/dist/setup-entry.cjs +193 -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 +193 -26
- package/dist/setup-entry.js.map +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
|
@@ -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;
|
|
109
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;
|
|
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,16 @@ 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. A turn
|
|
306
|
+
* OpenClaw refuses, or one that ends in error or on the wait timeout,
|
|
307
|
+
* records nothing: the conversation stays unread, the card stays on the
|
|
308
|
+
* tray, and the ladder re-wakes so it is gated again (one more gate
|
|
309
|
+
* call, no silent drop). The turn's final text is discarded — nothing is
|
|
247
310
|
* auto-routed anywhere.
|
|
248
311
|
*
|
|
249
312
|
* One cycle at a time per account: a wake that lands while a cycle runs is
|
|
@@ -255,7 +318,7 @@ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
|
255
318
|
* delay the next tray read. Completion is logged as it happens. A cycle
|
|
256
319
|
* that could not complete — model unreachable, server error, turn refused —
|
|
257
320
|
* re-wakes itself on a local ladder (1 m, 5 m, 30 m) because a connected
|
|
258
|
-
* socket gets no re-
|
|
321
|
+
* socket gets no re-wake from the server; the cards wait on the tray
|
|
259
322
|
* meanwhile. One outage climbs the ladder one rung: a retry already on its
|
|
260
323
|
* way is never replaced by a later one.
|
|
261
324
|
*
|
|
@@ -296,6 +359,13 @@ interface AgentInvokerOptions {
|
|
|
296
359
|
readonly logger: Logger;
|
|
297
360
|
/** Counts the ladder's re-wakes (`agentchat_channel_wake_total{source="retry"}`). The socket counts the others. */
|
|
298
361
|
readonly metrics?: MetricsRecorder;
|
|
362
|
+
/**
|
|
363
|
+
* Whether a turn started now can have the hosted tools (`turnReadiness`).
|
|
364
|
+
* Checked before the gate: while unready nothing is gated — the cards
|
|
365
|
+
* stay on the tray, no model call is spent, no turn starts — and the
|
|
366
|
+
* ladder re-wakes. Default: always ready.
|
|
367
|
+
*/
|
|
368
|
+
readonly readiness?: () => TurnReadiness;
|
|
299
369
|
/** `false`: no gate step — one turn per cycle with the served wake instruction; the agent judges in-turn. */
|
|
300
370
|
readonly gateEnabled?: boolean;
|
|
301
371
|
readonly debounceMs?: number;
|
|
@@ -327,7 +397,9 @@ type CycleOutcome =
|
|
|
327
397
|
/** The tray could not be read. */
|
|
328
398
|
| 'tray_failed'
|
|
329
399
|
/** The served texts are not available yet; nothing gated, the cards wait. */
|
|
330
|
-
| 'texts_missing'
|
|
400
|
+
| 'texts_missing'
|
|
401
|
+
/** A turn could not have the hosted tools; nothing gated, no model call, the cards wait. */
|
|
402
|
+
| 'tools_unavailable';
|
|
331
403
|
interface CycleResult {
|
|
332
404
|
readonly outcome: CycleOutcome;
|
|
333
405
|
readonly cards: number;
|
|
@@ -335,10 +407,13 @@ interface CycleResult {
|
|
|
335
407
|
readonly dismiss: number;
|
|
336
408
|
readonly defer: number;
|
|
337
409
|
readonly undecided: number;
|
|
410
|
+
/** `dismiss` / `defer` the server took in this cycle. `reply` verdicts are recorded as their turns complete, after the cycle. */
|
|
338
411
|
readonly recorded: number;
|
|
339
412
|
readonly recordFailures: number;
|
|
340
413
|
readonly turnsStarted: number;
|
|
341
414
|
readonly turnsRefused: number;
|
|
415
|
+
/** Cards left out of this cycle because a reply turn for their conversation is still running. */
|
|
416
|
+
readonly skippedInFlight: number;
|
|
342
417
|
readonly truncated: boolean;
|
|
343
418
|
readonly latencyMs: number;
|
|
344
419
|
readonly failure: string | null;
|
|
@@ -353,6 +428,7 @@ declare class AgentInvoker {
|
|
|
353
428
|
private readonly invites;
|
|
354
429
|
private readonly logger;
|
|
355
430
|
private readonly metrics;
|
|
431
|
+
private readonly readiness;
|
|
356
432
|
private readonly gateEnabled;
|
|
357
433
|
private readonly ladder;
|
|
358
434
|
private readonly now;
|
|
@@ -364,6 +440,17 @@ declare class AgentInvoker {
|
|
|
364
440
|
private invitesDirty;
|
|
365
441
|
private retryRung;
|
|
366
442
|
private turnsInFlight;
|
|
443
|
+
/**
|
|
444
|
+
* Conversations whose reply turn is running. Their verdict is recorded
|
|
445
|
+
* only when the turn completes, so the card stays on the tray meanwhile
|
|
446
|
+
* and every wake in between would re-gate it and queue a second turn.
|
|
447
|
+
* Such cards are left out of the cycle; once the turn ends the tray is
|
|
448
|
+
* read again if any were.
|
|
449
|
+
*/
|
|
450
|
+
private readonly replyTurnsInFlight;
|
|
451
|
+
private skippedWhileInFlight;
|
|
452
|
+
/** The reason the tools were last found unavailable; logged when it changes, not per wake. */
|
|
453
|
+
private unreadyReason;
|
|
367
454
|
cycles: number;
|
|
368
455
|
turns: number;
|
|
369
456
|
inviteTurns: number;
|
|
@@ -397,8 +484,18 @@ declare class AgentInvoker {
|
|
|
397
484
|
/**
|
|
398
485
|
* Book an admitted turn and log its end whenever it comes. The cycle moves
|
|
399
486
|
* on at once; OpenClaw's lane keeps the runs of one account in order.
|
|
487
|
+
*
|
|
488
|
+
* For a reply turn the end is also when the `reply` verdict is recorded —
|
|
489
|
+
* only if the run completed (`status: ok`, no error): a turn that looked
|
|
490
|
+
* and chose not to send still counts as read. A run that ended in error,
|
|
491
|
+
* on the wait timeout, or whose wait failed records nothing: the card stays
|
|
492
|
+
* on the tray and the ladder re-wakes so the conversation is gated again.
|
|
400
493
|
*/
|
|
401
494
|
private admitted;
|
|
495
|
+
/** The reply turn for `conversationId` is over: its card may be gated again, and a tray that held skipped cards is read once more. */
|
|
496
|
+
private replyTurnEnded;
|
|
497
|
+
/** The `reply` verdict for a completed turn. A record the server refuses leaves the conversation unread; the ladder re-wakes. */
|
|
498
|
+
private recordReply;
|
|
402
499
|
/**
|
|
403
500
|
* Every pending invite gets one attempt. An invite leaves the pending list
|
|
404
501
|
* only once its turn was admitted (and is then remembered in the ledger);
|
|
@@ -621,6 +718,8 @@ type AgentchatProbeResult = {
|
|
|
621
718
|
readonly turns?: number;
|
|
622
719
|
/** Where the served texts came from: the server, the cached copy, or nowhere yet. */
|
|
623
720
|
readonly texts?: 'server' | 'cache' | 'missing';
|
|
721
|
+
/** The socket's counters since the account started: wakes by source, closes by code/initiator, SDK notices by class. */
|
|
722
|
+
readonly socket?: MetricsSnapshot;
|
|
624
723
|
};
|
|
625
724
|
/** Set when the integration refuses to start (more than one account configured). */
|
|
626
725
|
readonly refusal?: string;
|
|
@@ -652,4 +751,4 @@ declare const agentchatSetupEntry: {
|
|
|
652
751
|
plugin: openclaw_plugin_sdk_channel_core.ChannelPlugin<AgentchatResolvedAccount, AgentchatProbeResult>;
|
|
653
752
|
};
|
|
654
753
|
|
|
655
|
-
export { AgentInvoker as A, type
|
|
754
|
+
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;
|
|
109
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;
|
|
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,16 @@ 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. A turn
|
|
306
|
+
* OpenClaw refuses, or one that ends in error or on the wait timeout,
|
|
307
|
+
* records nothing: the conversation stays unread, the card stays on the
|
|
308
|
+
* tray, and the ladder re-wakes so it is gated again (one more gate
|
|
309
|
+
* call, no silent drop). The turn's final text is discarded — nothing is
|
|
247
310
|
* auto-routed anywhere.
|
|
248
311
|
*
|
|
249
312
|
* One cycle at a time per account: a wake that lands while a cycle runs is
|
|
@@ -255,7 +318,7 @@ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
|
|
|
255
318
|
* delay the next tray read. Completion is logged as it happens. A cycle
|
|
256
319
|
* that could not complete — model unreachable, server error, turn refused —
|
|
257
320
|
* re-wakes itself on a local ladder (1 m, 5 m, 30 m) because a connected
|
|
258
|
-
* socket gets no re-
|
|
321
|
+
* socket gets no re-wake from the server; the cards wait on the tray
|
|
259
322
|
* meanwhile. One outage climbs the ladder one rung: a retry already on its
|
|
260
323
|
* way is never replaced by a later one.
|
|
261
324
|
*
|
|
@@ -296,6 +359,13 @@ interface AgentInvokerOptions {
|
|
|
296
359
|
readonly logger: Logger;
|
|
297
360
|
/** Counts the ladder's re-wakes (`agentchat_channel_wake_total{source="retry"}`). The socket counts the others. */
|
|
298
361
|
readonly metrics?: MetricsRecorder;
|
|
362
|
+
/**
|
|
363
|
+
* Whether a turn started now can have the hosted tools (`turnReadiness`).
|
|
364
|
+
* Checked before the gate: while unready nothing is gated — the cards
|
|
365
|
+
* stay on the tray, no model call is spent, no turn starts — and the
|
|
366
|
+
* ladder re-wakes. Default: always ready.
|
|
367
|
+
*/
|
|
368
|
+
readonly readiness?: () => TurnReadiness;
|
|
299
369
|
/** `false`: no gate step — one turn per cycle with the served wake instruction; the agent judges in-turn. */
|
|
300
370
|
readonly gateEnabled?: boolean;
|
|
301
371
|
readonly debounceMs?: number;
|
|
@@ -327,7 +397,9 @@ type CycleOutcome =
|
|
|
327
397
|
/** The tray could not be read. */
|
|
328
398
|
| 'tray_failed'
|
|
329
399
|
/** The served texts are not available yet; nothing gated, the cards wait. */
|
|
330
|
-
| 'texts_missing'
|
|
400
|
+
| 'texts_missing'
|
|
401
|
+
/** A turn could not have the hosted tools; nothing gated, no model call, the cards wait. */
|
|
402
|
+
| 'tools_unavailable';
|
|
331
403
|
interface CycleResult {
|
|
332
404
|
readonly outcome: CycleOutcome;
|
|
333
405
|
readonly cards: number;
|
|
@@ -335,10 +407,13 @@ interface CycleResult {
|
|
|
335
407
|
readonly dismiss: number;
|
|
336
408
|
readonly defer: number;
|
|
337
409
|
readonly undecided: number;
|
|
410
|
+
/** `dismiss` / `defer` the server took in this cycle. `reply` verdicts are recorded as their turns complete, after the cycle. */
|
|
338
411
|
readonly recorded: number;
|
|
339
412
|
readonly recordFailures: number;
|
|
340
413
|
readonly turnsStarted: number;
|
|
341
414
|
readonly turnsRefused: number;
|
|
415
|
+
/** Cards left out of this cycle because a reply turn for their conversation is still running. */
|
|
416
|
+
readonly skippedInFlight: number;
|
|
342
417
|
readonly truncated: boolean;
|
|
343
418
|
readonly latencyMs: number;
|
|
344
419
|
readonly failure: string | null;
|
|
@@ -353,6 +428,7 @@ declare class AgentInvoker {
|
|
|
353
428
|
private readonly invites;
|
|
354
429
|
private readonly logger;
|
|
355
430
|
private readonly metrics;
|
|
431
|
+
private readonly readiness;
|
|
356
432
|
private readonly gateEnabled;
|
|
357
433
|
private readonly ladder;
|
|
358
434
|
private readonly now;
|
|
@@ -364,6 +440,17 @@ declare class AgentInvoker {
|
|
|
364
440
|
private invitesDirty;
|
|
365
441
|
private retryRung;
|
|
366
442
|
private turnsInFlight;
|
|
443
|
+
/**
|
|
444
|
+
* Conversations whose reply turn is running. Their verdict is recorded
|
|
445
|
+
* only when the turn completes, so the card stays on the tray meanwhile
|
|
446
|
+
* and every wake in between would re-gate it and queue a second turn.
|
|
447
|
+
* Such cards are left out of the cycle; once the turn ends the tray is
|
|
448
|
+
* read again if any were.
|
|
449
|
+
*/
|
|
450
|
+
private readonly replyTurnsInFlight;
|
|
451
|
+
private skippedWhileInFlight;
|
|
452
|
+
/** The reason the tools were last found unavailable; logged when it changes, not per wake. */
|
|
453
|
+
private unreadyReason;
|
|
367
454
|
cycles: number;
|
|
368
455
|
turns: number;
|
|
369
456
|
inviteTurns: number;
|
|
@@ -397,8 +484,18 @@ declare class AgentInvoker {
|
|
|
397
484
|
/**
|
|
398
485
|
* Book an admitted turn and log its end whenever it comes. The cycle moves
|
|
399
486
|
* on at once; OpenClaw's lane keeps the runs of one account in order.
|
|
487
|
+
*
|
|
488
|
+
* For a reply turn the end is also when the `reply` verdict is recorded —
|
|
489
|
+
* only if the run completed (`status: ok`, no error): a turn that looked
|
|
490
|
+
* and chose not to send still counts as read. A run that ended in error,
|
|
491
|
+
* on the wait timeout, or whose wait failed records nothing: the card stays
|
|
492
|
+
* on the tray and the ladder re-wakes so the conversation is gated again.
|
|
400
493
|
*/
|
|
401
494
|
private admitted;
|
|
495
|
+
/** The reply turn for `conversationId` is over: its card may be gated again, and a tray that held skipped cards is read once more. */
|
|
496
|
+
private replyTurnEnded;
|
|
497
|
+
/** The `reply` verdict for a completed turn. A record the server refuses leaves the conversation unread; the ladder re-wakes. */
|
|
498
|
+
private recordReply;
|
|
402
499
|
/**
|
|
403
500
|
* Every pending invite gets one attempt. An invite leaves the pending list
|
|
404
501
|
* only once its turn was admitted (and is then remembered in the ledger);
|
|
@@ -621,6 +718,8 @@ type AgentchatProbeResult = {
|
|
|
621
718
|
readonly turns?: number;
|
|
622
719
|
/** Where the served texts came from: the server, the cached copy, or nowhere yet. */
|
|
623
720
|
readonly texts?: 'server' | 'cache' | 'missing';
|
|
721
|
+
/** The socket's counters since the account started: wakes by source, closes by code/initiator, SDK notices by class. */
|
|
722
|
+
readonly socket?: MetricsSnapshot;
|
|
624
723
|
};
|
|
625
724
|
/** Set when the integration refuses to start (more than one account configured). */
|
|
626
725
|
readonly refusal?: string;
|
|
@@ -652,4 +751,4 @@ declare const agentchatSetupEntry: {
|
|
|
652
751
|
plugin: openclaw_plugin_sdk_channel_core.ChannelPlugin<AgentchatResolvedAccount, AgentchatProbeResult>;
|
|
653
752
|
};
|
|
654
753
|
|
|
655
|
-
export { AgentInvoker as A, type
|
|
754
|
+
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 };
|