@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.
@@ -71,25 +71,39 @@ interface Logger {
71
71
  }
72
72
 
73
73
  /**
74
- * Optional Prometheus metrics for the channel plugin.
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
- * Design: the gateway owns the `/metrics` endpoint. Plugins do not expose
77
- * their own port. If the user passes a `prom-client` Registry, we register
78
- * our counters/gauges into it. Otherwise, we return a no-op recorder — zero
79
- * overhead, zero config.
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_`. The integration sends
82
- * nothing, so there are no outbound metrics: what it reports is the
83
- * socket's state, its closes and errors, and the wakes it hands on.
84
- *
85
- * Renamed with the move to the SDK socket (dashboards: see CHANGELOG):
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 moment OpenClaw admits
243
- * the run the `reply` verdict is recorded — the conversation is read from
244
- * then on. A turn OpenClaw refuses records nothing: the conversation
245
- * stays unread, and the next wake gates it again (one more gate call, no
246
- * silent drop). The turn's final text is discarded — nothing is
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-ring from the server; the cards wait on the tray
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 CycleOutcome as C, type GroupInvite as G, IntegrationSocket as I, type Logger as L, type SocketBlocked as S, type WakeSource as W, type AgentInvokerOptions as a, type AgentchatChannelConfig as b, type AgentchatResolvedAccount as c, type CycleResult as d, type IntegrationSocketOptions as e, InviteLedger as f, type SocketDisconnect as g, type SocketHandlers as h, type SocketHealth as i, type SocketState as j, agentchatChannelEntry as k, agentchatPlugin as l, agentchatSetupEntry as m, groupInviteFromRecord as n, parseChannelConfig as p, realtimeOptionsFor as r };
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
- * Optional Prometheus metrics for the channel plugin.
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
- * Design: the gateway owns the `/metrics` endpoint. Plugins do not expose
77
- * their own port. If the user passes a `prom-client` Registry, we register
78
- * our counters/gauges into it. Otherwise, we return a no-op recorder — zero
79
- * overhead, zero config.
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_`. The integration sends
82
- * nothing, so there are no outbound metrics: what it reports is the
83
- * socket's state, its closes and errors, and the wakes it hands on.
84
- *
85
- * Renamed with the move to the SDK socket (dashboards: see CHANGELOG):
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 moment OpenClaw admits
243
- * the run the `reply` verdict is recorded — the conversation is read from
244
- * then on. A turn OpenClaw refuses records nothing: the conversation
245
- * stays unread, and the next wake gates it again (one more gate call, no
246
- * silent drop). The turn's final text is discarded — nothing is
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-ring from the server; the cards wait on the tray
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 CycleOutcome as C, type GroupInvite as G, IntegrationSocket as I, type Logger as L, type SocketBlocked as S, type WakeSource as W, type AgentInvokerOptions as a, type AgentchatChannelConfig as b, type AgentchatResolvedAccount as c, type CycleResult as d, type IntegrationSocketOptions as e, InviteLedger as f, type SocketDisconnect as g, type SocketHandlers as h, type SocketHealth as i, type SocketState as j, agentchatChannelEntry as k, agentchatPlugin as l, agentchatSetupEntry as m, groupInviteFromRecord as n, parseChannelConfig as p, realtimeOptionsFor as r };
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 };