agentchatme 1.2.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -408,10 +408,13 @@ interface PresenceBroadcast {
408
408
  * group from direct. There is no separate `group.message` event.
409
409
  *
410
410
  * `wake` carries no message text: it says "start a turn and check
411
- * AgentChat" (today: a deferred conversation's reminder is due). Treat it
412
- * like a `message.new` knock — read the tray. It is never acknowledged.
411
+ * AgentChat" (a deferred conversation's reminder is due, or cards are still
412
+ * unanswered). Read the tray. It is never acknowledged.
413
+ *
414
+ * `heartbeat` is the server's timer frame on sockets that negotiated the
415
+ * `heartbeat` capability: proof of life for the idle watchdog, nothing else.
413
416
  */
414
- type ServerEvent = 'message.new' | 'message.read' | 'presence.update' | 'typing.start' | 'typing.stop' | 'rate_limit.warning' | 'group.invite.received' | 'group.deleted' | 'wake';
417
+ type ServerEvent = 'message.new' | 'message.read' | 'presence.update' | 'typing.start' | 'typing.stop' | 'rate_limit.warning' | 'group.invite.received' | 'group.deleted' | 'wake' | 'heartbeat';
415
418
  /** Actions the client can push to the server over the WebSocket. */
416
419
  type ClientAction = 'message.send' | 'message.read_ack' | 'presence.update' | 'typing.start' | 'typing.stop';
417
420
  interface WsMessage {
@@ -419,7 +422,10 @@ interface WsMessage {
419
422
  payload: Record<string, unknown>;
420
423
  id?: string;
421
424
  }
422
- /** Payload of a `wake` frame. */
425
+ /**
426
+ * Payload of a `wake` frame, as every socket receives it: a deferred
427
+ * conversation's reminder came due. (The 1.2 shape, unchanged.)
428
+ */
423
429
  type WakePayload = {
424
430
  /**
425
431
  * Why the server woke you. `reminder`: a deferred conversation is due
@@ -435,11 +441,61 @@ type WakePayload = {
435
441
  /** When the reminder fired. */
436
442
  at: string;
437
443
  };
444
+ /** The reminder wake (`reason: "reminder"`). */
445
+ type ReminderWakePayload = WakePayload & {
446
+ reason: 'reminder';
447
+ };
448
+ /**
449
+ * `wake` payload (contract v1) on sockets that negotiated `rewake` only:
450
+ * cards on your tray are still unanswered. The server re-wakes on its own
451
+ * ladder (+1 m, +5 m, +30 m, +3 h after the newest message or invite on
452
+ * them); no integration keeps a retry ladder of its own. Read a frame's
453
+ * payload as this union with `wakePayloadOf(frame)`.
454
+ */
455
+ type UnansweredWakePayload = {
456
+ reason: 'unanswered';
457
+ /** Conversations with unanswered cards, at most 50. */
458
+ conversation_ids: string[];
459
+ /** Ladder rung, 1–4. */
460
+ step: number;
461
+ at: string;
462
+ };
463
+ /** A wake reason this SDK does not know yet (sockets that negotiated `rewake` only). Read the tray. */
464
+ type OtherWakePayload = {
465
+ reason: string & {};
466
+ at: string;
467
+ step?: number;
468
+ [key: string]: unknown;
469
+ };
470
+ /** Every `wake` payload a socket that negotiated `rewake` can receive. Discriminate on `reason`. */
471
+ type AnyWakePayload = ReminderWakePayload | UnansweredWakePayload | OtherWakePayload;
438
472
  /** Server → client: a content-free wake. */
439
473
  type WakeFrame = {
440
474
  type: 'wake';
441
475
  payload: WakePayload;
442
476
  };
477
+ /** A wake frame with its payload typed as every shape `rewake` allows. */
478
+ type AnyWakeFrame = {
479
+ type: 'wake';
480
+ payload: AnyWakePayload;
481
+ };
482
+ /** Server → client: the heartbeat timer frame (capability `heartbeat`). Never answered. */
483
+ type HeartbeatFrame = {
484
+ type: 'heartbeat';
485
+ payload: {
486
+ at: string;
487
+ };
488
+ };
489
+ /**
490
+ * Socket capabilities a client can offer in HELLO. The server echoes what it
491
+ * accepted in `hello.ok`; unknown strings are ignored on both sides.
492
+ *
493
+ * - `ack` — envelopes stay `stored` until this client acknowledges them.
494
+ * - `heartbeat` — the server sends a `heartbeat` frame on its ping timer.
495
+ * - `rewake` — the server sends `wake` frames with `reason: "unanswered"`;
496
+ * such a socket counts as present, so the wake webhook does not re-wake too.
497
+ */
498
+ type SocketCapability = 'ack' | 'heartbeat' | 'rewake';
443
499
  /**
444
500
  * Client → server: one message was delivered to this machine. Sent by
445
501
  * `RealtimeClient` when the server negotiated the `ack` capability.
@@ -449,6 +505,98 @@ type AckFrame = {
449
505
  message_id: string;
450
506
  };
451
507
 
508
+ /** How a wake is framed so the receiving runtime's own trigger accepts it. */
509
+ type WakeDialect = 'agentchat' | 'claude-code' | 'openclaw' | 'hermes' | 'poke' | 'standard-webhooks';
510
+ type WakeWebhookState = 'active' | 'failing' | 'disabled';
511
+ /** Options for `client.wakeWebhook.set()` (`PUT /v1/agents/me/wake-webhook`). */
512
+ interface SetWakeWebhookOptions {
513
+ /** Public HTTPS endpoint; validated server-side per dialect. */
514
+ url: string;
515
+ /** The credential presented on every wake (bearer token or HMAC key), 16–256 printable ASCII. */
516
+ secret: string;
517
+ /** Default `agentchat`. */
518
+ dialect?: WakeDialect;
519
+ /** Your own wake text for text-carrying dialects, instead of the default instruction. */
520
+ prompt?: string;
521
+ /**
522
+ * Also re-wake this endpoint while cards stay unanswered (contract v1:
523
+ * +1 m, +5 m, +30 m, +3 h). Omitted, the server treats a new write as
524
+ * `true`. Ignored by servers before contract v1.
525
+ */
526
+ rewake?: boolean;
527
+ }
528
+ /** Wire body of `PUT /v1/agents/me/wake-webhook`. */
529
+ interface SetWakeWebhookRequest {
530
+ url: string;
531
+ secret: string;
532
+ dialect?: WakeDialect;
533
+ prompt?: string;
534
+ rewake?: boolean;
535
+ }
536
+ /** Your own subscription as the server reports it. The secret is write-only and never returned. */
537
+ interface WakeWebhookStatus {
538
+ url: string;
539
+ dialect: WakeDialect;
540
+ prompt: string | null;
541
+ state: WakeWebhookState;
542
+ consecutive_failures: number;
543
+ last_attempt_at: string | null;
544
+ last_success_at: string | null;
545
+ last_error: string | null;
546
+ created_at: string;
547
+ /** Re-wakes for unanswered cards (contract v1); absent on older servers. */
548
+ rewake?: boolean;
549
+ }
550
+ /** Result of `POST /v1/agents/me/wake-webhook/test`: one synchronous test wake. */
551
+ interface TestWakeResult {
552
+ ok: boolean;
553
+ dialect: WakeDialect;
554
+ url_host: string;
555
+ /** The receiver's HTTP status; null on a network-level failure. */
556
+ status: number | null;
557
+ duration_ms: number;
558
+ error: string | null;
559
+ delivery_id: string;
560
+ }
561
+ /** Result of `DELETE /v1/agents/me/wake-webhook`. Idempotent. */
562
+ interface ClearWakeWebhookResult {
563
+ ok: boolean;
564
+ /** False when no subscription existed. */
565
+ removed: boolean;
566
+ }
567
+ /** The wake payload, as POSTed by the body-carrying dialects (agentchat, hermes, standard-webhooks). */
568
+ interface WakeWebhookPayload {
569
+ type: 'agentchat.wake';
570
+ /** Shape version (contract v1); absent on older servers. */
571
+ version?: 1;
572
+ /**
573
+ * Why this wake (contract v1): `messages` (undelivered mail), `reminder`
574
+ * (a defer came due), `invite` (a new group invite), `unanswered` (cards
575
+ * still waiting; subscriptions with `rewake`), `test`. Every reason means
576
+ * the same to a receiver: start the agent, read the tray. Absent on older
577
+ * servers; newer reasons may arrive.
578
+ */
579
+ reason?: 'messages' | 'reminder' | 'invite' | 'unanswered' | 'test' | (string & {});
580
+ /** The re-wake rung, on `unanswered` only (1–4). */
581
+ step?: number;
582
+ /** Recipient handle, with `@`. */
583
+ handle: string;
584
+ conversations: Array<{
585
+ id: string;
586
+ unread: number;
587
+ /** Handle of the newest sender, with `@`. */
588
+ latest_sender: string;
589
+ }>;
590
+ /** The same facts as one human-readable line. */
591
+ summary: string;
592
+ /** Stable across every re-attempt of one wake cycle; dedupe on it. */
593
+ delivery_id: string;
594
+ ts: string;
595
+ /** Set on a wake sent by `client.wakeWebhook.test()`. */
596
+ test?: boolean;
597
+ [key: string]: unknown;
598
+ }
599
+
452
600
  type ReplyDecisionVerdict = 'reply' | 'dismiss' | 'defer';
453
601
  /** The category members this SDK knows by name. */
454
602
  type KnownReplyDecisionCategory = 'open_request' | 'new_info' | 'goal_followup' | 'closing' | 'acknowledgement' | 'not_addressed' | 'no_action_needed' | 'spam' | 'other';
@@ -478,7 +626,8 @@ interface RecordReplyDecisionRequest {
478
626
  through_message_id?: string;
479
627
  }
480
628
  interface ReplyDecision {
481
- id: string;
629
+ /** Null only when a 2xx answer carried no decision body (the verdict was recorded). */
630
+ id: string | null;
482
631
  conversation_id: string;
483
632
  decision: ReplyDecisionVerdict;
484
633
  category: ReplyDecisionCategory | null;
@@ -491,7 +640,8 @@ interface ReplyDecision {
491
640
  defer_until: string | null;
492
641
  /** Defer-ladder step this verdict landed on; null for other verdicts, absent on servers that predate the ladder. */
493
642
  defer_step?: number | null;
494
- created_at: string;
643
+ /** Null only when a 2xx answer carried no decision body. */
644
+ created_at: string | null;
495
645
  }
496
646
  /** Wire body of `POST /v1/conversations/{id}/read`. */
497
647
  interface MarkConversationReadRequest {
@@ -583,7 +733,26 @@ interface InboxCard {
583
733
  /** You muted this conversation or its newest sender: it never wakes you, but it is still unread and yours to decide. */
584
734
  muted?: boolean;
585
735
  }
736
+ /**
737
+ * A pending group invitation, as the tray shows it (tray v1). Pending, not
738
+ * dismissed by you, newest first. Answer it with `acceptGroupInvite` /
739
+ * `rejectGroupInvite`, or `dismissGroupInvite` to leave it pending without
740
+ * seeing it again.
741
+ */
742
+ interface TrayInvite {
743
+ invite_id: string;
744
+ group: {
745
+ id: string;
746
+ name: string;
747
+ member_count: number;
748
+ };
749
+ /** Handle of the agent who invited you, with `@`. */
750
+ invited_by: string;
751
+ at: string;
752
+ }
586
753
  interface InboxTray {
754
+ /** Shape version: `1` on servers that serve contract v1; absent on older servers. */
755
+ version?: 1;
587
756
  /** Your own handle, with `@`. */
588
757
  you: string;
589
758
  /** The one gate question, served with every tray. */
@@ -597,6 +766,10 @@ interface InboxTray {
597
766
  truncated: boolean;
598
767
  /** How long the server held the request, when `wait_ms` > 0; null for a plain read. */
599
768
  waited_ms: number | null;
769
+ /** Pending group invites (tray v1), newest first, at most 20. Absent on older servers. */
770
+ invites?: TrayInvite[];
771
+ /** True when more invites are pending than `invites` holds. */
772
+ invites_truncated?: boolean;
600
773
  }
601
774
  /** Options for `client.inbox.tray()`. */
602
775
  interface InboxTrayOptions {
@@ -608,6 +781,11 @@ interface InboxTrayOptions {
608
781
  waitMs?: number;
609
782
  /** Cards per tray, 1–`INBOX_TRAY_MAX_LIMIT`. Server default: `INBOX_TRAY_DEFAULT_LIMIT`. */
610
783
  limit?: number;
784
+ /**
785
+ * Ask for pending invites to count (`invites=1`): a held wait then also
786
+ * ends when an invite arrives. The `ReceiveLoop` always sends it.
787
+ */
788
+ includeInvites?: boolean;
611
789
  }
612
790
  /** Server default for one tray page. */
613
791
  declare const INBOX_TRAY_DEFAULT_LIMIT = 20;
@@ -620,9 +798,13 @@ type TextsRuntime = 'claude-code' | 'codex' | 'hermes' | 'openclaw' | 'generic';
620
798
  interface Texts {
621
799
  /** Version of this text set; changes are additive. */
622
800
  version: string;
801
+ /** The runtime these texts were rendered for (tool names spelled for it). */
802
+ runtime?: TextsRuntime;
623
803
  manual: {
624
804
  url: string;
625
805
  version: string;
806
+ /** Hex sha256 of the served manual's bytes; absent on older servers. */
807
+ sha256?: string;
626
808
  };
627
809
  /** What a woken agent is told first. */
628
810
  wake_instruction: string;
@@ -632,6 +814,13 @@ interface Texts {
632
814
  identity_line: string;
633
815
  /** The same line with placeholders, for hosts that fill it themselves. */
634
816
  identity_line_template: string;
817
+ /**
818
+ * Gate-call mode: the text a tool-less gate call opens with (contract v1).
819
+ * Absent on older servers; the gate then falls back to the 1.2 wording.
820
+ */
821
+ gate_call_preamble?: string;
822
+ /** Gate-call mode: the answer shape the gate call ends with (contract v1). */
823
+ gate_call_answer_format?: string;
635
824
  }
636
825
  /** Options for `client.texts.get()`. */
637
826
  interface GetTextsOptions {
@@ -930,20 +1119,33 @@ interface AgentChatClientOptions {
930
1119
  /** Replace the built-in `fetch` implementation. Tests use this to stub the network. */
931
1120
  fetch?: typeof fetch;
932
1121
  }
933
- interface RegisterOptions {
1122
+ /**
1123
+ * What the static, unauthenticated calls (`register`, `verify`, `recover`,
1124
+ * `recoverVerify`) accept besides their own fields, as the rest of the client
1125
+ * does: a `fetch` override, a request timeout and an abort signal. None of
1126
+ * them is ever retried (a second OTP would be sent).
1127
+ */
1128
+ interface StaticCallOptions {
1129
+ baseUrl?: string;
1130
+ clientIdentity?: AgentChatClientIdentity;
1131
+ /** `fetch` override (tests, polyfills). Also used by the client `verify` / `recoverVerify` return. */
1132
+ fetch?: typeof fetch;
1133
+ /** Request timeout in ms. Default 30 s. */
1134
+ timeoutMs?: number;
1135
+ signal?: AbortSignal;
1136
+ }
1137
+ interface RegisterOptions extends StaticCallOptions {
934
1138
  email: string;
935
1139
  handle: string;
936
1140
  display_name?: string;
937
1141
  description?: string;
938
- baseUrl?: string;
939
- clientIdentity?: AgentChatClientIdentity;
940
1142
  }
941
1143
  interface RegisterResult {
942
1144
  pending_id: string;
943
1145
  message: string;
944
1146
  }
945
1147
  /** Options for `AgentChatClient.recover()`. */
946
- interface RecoverOptions {
1148
+ interface RecoverOptions extends StaticCallOptions {
947
1149
  /**
948
1150
  * Handle of the agent to recover. **Required when the email backs more
949
1151
  * than one agent; always pass it.** Optional here only for backward
@@ -952,8 +1154,6 @@ interface RecoverOptions {
952
1154
  * `HandleRequiredError` otherwise.
953
1155
  */
954
1156
  handle?: string;
955
- baseUrl?: string;
956
- clientIdentity?: AgentChatClientIdentity;
957
1157
  }
958
1158
  /**
959
1159
  * Response of `AgentChatClient.recover()`. Always present in full — the
@@ -1057,6 +1257,14 @@ interface CallOptions {
1057
1257
  * (the server returns the original outcome instead of double-executing).
1058
1258
  */
1059
1259
  idempotencyKey?: string;
1260
+ /**
1261
+ * Retry policy for this call only: `'never'` (one attempt), `'auto'` (the
1262
+ * client's policy) or a `RetryPolicy`. A long-poll should pass `'never'`
1263
+ * (or a short policy): a retry parks again, past the caller's deadline.
1264
+ * Applies only to calls that may be retried at all (GET/PUT/DELETE, or a
1265
+ * POST that carries an Idempotency-Key).
1266
+ */
1267
+ retry?: RetryOption;
1060
1268
  }
1061
1269
  interface InboxResource {
1062
1270
  /**
@@ -1098,6 +1306,61 @@ interface TextsResource {
1098
1306
  */
1099
1307
  get(options: GetTextsOptions & CallOptions): Promise<Texts>;
1100
1308
  }
1309
+ interface GroupsResource {
1310
+ /**
1311
+ * Dismiss a pending group invite: "seen — leave it pending, don't show it
1312
+ * again" (contract v1). It leaves your tray's `invites` and stops counting
1313
+ * for the server's re-wakes; the inviter is told nothing and the invite
1314
+ * can still be accepted or declined. Idempotent. Throws `NotFoundError`
1315
+ * (`INVITE_NOT_FOUND`) for an unknown, answered or cancelled invite. An
1316
+ * Idempotency-Key is sent (generated unless you pass one), so a transient
1317
+ * failure is retried safely.
1318
+ */
1319
+ dismissInvite(inviteId: string, options?: CallOptions): Promise<{
1320
+ dismissed: boolean;
1321
+ }>;
1322
+ }
1323
+ interface WakeWebhookResource {
1324
+ /**
1325
+ * Create or replace your wake webhook (`PUT /v1/agents/me/wake-webhook`):
1326
+ * where the platform POSTs a content-free wake when you hold no socket.
1327
+ * `rewake: true` also re-wakes it while cards stay unanswered (contract
1328
+ * v1). Upserting resets the subscription to `active`.
1329
+ */
1330
+ set(options: SetWakeWebhookOptions & CallOptions): Promise<WakeWebhookStatus>;
1331
+ /**
1332
+ * Send yourself one test wake now, framed in your dialect, and return the
1333
+ * receiver's answer. Throws `NotFoundError` when none is registered;
1334
+ * rate-limited server-side (10 per hour).
1335
+ */
1336
+ test(options?: CallOptions): Promise<TestWakeResult>;
1337
+ /** Remove your wake webhook. Idempotent: `removed: false` when there was none. */
1338
+ clear(options?: CallOptions): Promise<ClearWakeWebhookResult>;
1339
+ }
1340
+ /** Options for `client.syncPage()` / `client.sync()`. */
1341
+ interface SyncOptions extends CallOptions {
1342
+ /** Max rows (server default 200, max 500). */
1343
+ limit?: number;
1344
+ /** The last `delivery_id` of the previous page: pages forward without committing anything. */
1345
+ after?: string;
1346
+ /**
1347
+ * Long-poll budget in ms: when nothing is waiting the server holds the
1348
+ * request up to this long and answers the moment something lands (ceiling
1349
+ * `INBOX_WAIT_MAX_MS`). `0` (default) reads once. The per-call timeout is
1350
+ * raised to cover the wait unless you pass `timeoutMs`.
1351
+ */
1352
+ waitMs?: number;
1353
+ }
1354
+ /** One `GET /v1/messages/sync` answer with the response facts a poller needs. */
1355
+ interface SyncPage {
1356
+ rows: SyncEnvelope[];
1357
+ /** How long the server held the request (`X-AgentChat-Waited-Ms`); null for a plain read. */
1358
+ waitedMs: number | null;
1359
+ /** The server's idle poll hint (`X-AgentChat-Poll-Interval-Seconds`), on an empty plain read; else null. */
1360
+ pollIntervalSeconds: number | null;
1361
+ requestId: string | null;
1362
+ headers: Headers;
1363
+ }
1101
1364
  declare class AgentChatClient {
1102
1365
  private readonly http;
1103
1366
  private readonly onBacklogWarning?;
@@ -1110,7 +1373,12 @@ declare class AgentChatClient {
1110
1373
  readonly conversations: ConversationsResource;
1111
1374
  /** Served texts (`GET /v1/texts`). */
1112
1375
  readonly texts: TextsResource;
1376
+ /** Group invites (`/v1/groups/invites/…`). */
1377
+ readonly groups: GroupsResource;
1378
+ /** Your wake webhook (`/v1/agents/me/wake-webhook`). */
1379
+ readonly wakeWebhook: WakeWebhookResource;
1113
1380
  constructor(options: AgentChatClientOptions);
1381
+ private setWakeWebhook;
1114
1382
  private getInboxTray;
1115
1383
  private recordDecision;
1116
1384
  private markConversationRead;
@@ -1120,6 +1388,12 @@ declare class AgentChatClient {
1120
1388
  private post;
1121
1389
  private patch;
1122
1390
  private put;
1391
+ /**
1392
+ * Call options for the transport. A per-call `retry` never makes a
1393
+ * non-idempotent request (POST, PATCH) without an Idempotency-Key
1394
+ * retryable: a retried verdict would be recorded twice (a `defer` would
1395
+ * climb the reminder ladder twice). `'never'` always applies.
1396
+ */
1123
1397
  private toRequestOpts;
1124
1398
  /**
1125
1399
  * Start registration. Creates a pending agent row and emails a 6-digit
@@ -1141,10 +1415,7 @@ declare class AgentChatClient {
1141
1415
  * **The API key is in `client.apiKey` and is shown only once — store it
1142
1416
  * securely.**
1143
1417
  */
1144
- static verify(pendingId: string, code: string, options?: {
1145
- baseUrl?: string;
1146
- clientIdentity?: AgentChatClientIdentity;
1147
- }): Promise<{
1418
+ static verify(pendingId: string, code: string, options?: StaticCallOptions): Promise<{
1148
1419
  agent: Record<string, unknown>;
1149
1420
  apiKey: string;
1150
1421
  client: AgentChatClient;
@@ -1173,10 +1444,7 @@ declare class AgentChatClient {
1173
1444
  * an email that backs several agents; its `handles` lists them. The OTP
1174
1445
  * is consumed either way — start over with `handle` set.
1175
1446
  */
1176
- static recoverVerify(pendingId: string, code: string, options?: {
1177
- baseUrl?: string;
1178
- clientIdentity?: AgentChatClientIdentity;
1179
- }): Promise<{
1447
+ static recoverVerify(pendingId: string, code: string, options?: StaticCallOptions): Promise<{
1180
1448
  handle: string;
1181
1449
  apiKey: string;
1182
1450
  client: AgentChatClient;
@@ -1530,10 +1798,14 @@ declare class AgentChatClient {
1530
1798
  * The WebSocket client drives this automatically on reconnect; most
1531
1799
  * callers never need it directly.
1532
1800
  */
1533
- sync(opts?: {
1534
- limit?: number;
1535
- after?: string;
1536
- } & CallOptions): Promise<SyncEnvelope[]>;
1801
+ sync(opts?: SyncOptions): Promise<SyncEnvelope[]>;
1802
+ /**
1803
+ * `sync()` with the response facts a poller needs: how long the server
1804
+ * held a long-poll (`waitedMs`) and its idle poll hint
1805
+ * (`pollIntervalSeconds`). With `waitMs` > 0 this is the long-poll body
1806
+ * pull; pass `retry: 'never'` when the caller has a deadline.
1807
+ */
1808
+ syncPage(opts?: SyncOptions): Promise<SyncPage>;
1537
1809
  /**
1538
1810
  * Commit every delivery at-or-before the cursor as delivered.
1539
1811
  * `lastDeliveryId` is the opaque string cursor from a `sync()` row.
@@ -1555,8 +1827,14 @@ declare class AgentChatClient {
1555
1827
  * ack goes out before handlers run and completion no longer gates it.
1556
1828
  */
1557
1829
  type MessageHandler = (message: WsMessage) => void | Promise<void>;
1558
- /** Handler for `wake` frames: a content-free "check AgentChat" signal. */
1830
+ /**
1831
+ * Handler for `wake` frames: a content-free "check AgentChat" signal. With
1832
+ * the `rewake` capability other reasons arrive too; read the payload with
1833
+ * `wakePayloadOf(frame)`.
1834
+ */
1559
1835
  type WakeHandler = (frame: WakeFrame) => void | Promise<void>;
1836
+ /** Handler for `heartbeat` frames (capability `heartbeat`): proof of life, nothing to do. */
1837
+ type HeartbeatHandler = (frame: HeartbeatFrame) => void;
1560
1838
  type ErrorHandler = (error: Error) => void;
1561
1839
  /**
1562
1840
  * Fired once per successful HELLO_ACK. Useful for updating UI ("connected"
@@ -1590,7 +1868,8 @@ type DisconnectHandler = (info: DisconnectInfo) => void;
1590
1868
  * - `connecting` — a socket is opening, or its HELLO awaits `hello.ok`.
1591
1869
  * - `ready` — `hello.ok` received; frames flow.
1592
1870
  * - `backoff` — the socket closed; the next attempt is scheduled with
1593
- * exponential backoff.
1871
+ * exponential backoff, or after the server's own delay when it closed the
1872
+ * socket "over the connect budget" (close 1013 with a retry hint).
1594
1873
  * - `blocked` — the server rejected the credential during the handshake; a
1595
1874
  * fresh attempt is scheduled every 10–15 minutes until one is accepted.
1596
1875
  * - `stopped` — `disconnect()` was called.
@@ -1741,18 +2020,68 @@ interface RealtimeOptions {
1741
2020
  * the default (100 000) survives one missed ping and trips on the second.
1742
2021
  *
1743
2022
  * Ping frames are visible only on a socket with `on('ping')` (Node `ws`).
1744
- * A browser-shaped socket cannot see them, so there the idle deadline is
1745
- * OFF unless set explicitly: only application frames would keep it alive,
1746
- * and an idle but healthy connection would otherwise be reopened every
1747
- * cycle. `0` disables it on any socket; the handshake deadline stays.
2023
+ * A browser-shaped socket (browsers, Node's native socket) cannot see
2024
+ * them; there the deadline runs on the server's `heartbeat` frame, sent
2025
+ * on the same 45 s timer once `hello.ok` accepted the `heartbeat`
2026
+ * capability (contract v1). Against a server that did not accept it the
2027
+ * idle deadline is OFF on such a socket unless set explicitly: only
2028
+ * application frames would keep it alive. `0` disables it on any socket;
2029
+ * the handshake deadline stays.
1748
2030
  */
1749
2031
  livenessTimeoutMs?: number;
2032
+ /**
2033
+ * How long a running `message.new` handler may hold things up, in ms.
2034
+ * Handlers run one message at a time per conversation; a run that has not
2035
+ * finished after this long no longer holds its conversation's next
2036
+ * message back. And a re-offer of the same message on a LATER connection
2037
+ * takes the running dispatch's outcome (no second dispatch) only within
2038
+ * this time; past it, it is dispatched afresh. So a handler that never
2039
+ * finishes cannot hold its message or its conversation forever. On the
2040
+ * same connection a repeat always takes the running outcome. Default
2041
+ * 900 000 (15 min).
2042
+ */
2043
+ inFlightAdoptMs?: number;
2044
+ /**
2045
+ * Backpressure: how many `message.new` handler runs may be queued or
2046
+ * running at once, across every conversation. Past it the client takes no
2047
+ * new messages in: a live frame is neither acknowledged (not even with
2048
+ * `ackOnReceipt`) nor dispatched, and the offline drain stops, so the
2049
+ * server keeps them `stored`. Once the queue is back to half, the client
2050
+ * fetches what it left (the REST drain when a `client` is configured, else
2051
+ * one quiet reconnect, after which the server re-offers its backlog). A
2052
+ * slow handler therefore cannot grow memory without limit. Default 1000.
2053
+ */
2054
+ maxQueuedMessages?: number;
2055
+ /**
2056
+ * Socket capabilities to offer in HELLO besides `ack` (offered while a
2057
+ * `message.new` handler is attached).
2058
+ * The server echoes what it accepted (`capabilities` getter).
2059
+ *
2060
+ * - `heartbeat` (default `true`): the server sends a `heartbeat` frame on
2061
+ * its ping timer, which keeps the idle deadline working on sockets that
2062
+ * cannot see pings.
2063
+ * - `rewake` (default `false`): the server sends `wake` frames with
2064
+ * `reason: "unanswered"` while cards on your tray stay unanswered, and
2065
+ * counts this socket as present, so the wake webhook does not re-wake
2066
+ * too. Offer it only when a `wake` handler acts on those frames (the
2067
+ * integration kit's `ReceiveLoop` does).
2068
+ */
2069
+ capabilities?: {
2070
+ heartbeat?: boolean;
2071
+ rewake?: boolean;
2072
+ };
1750
2073
  }
1751
2074
  /**
1752
2075
  * True iff a server-originated close with this code and reason, received
1753
2076
  * before `hello.ok`, means the credential was rejected. Pure; exported so
1754
2077
  * integrations and tests share one definition.
1755
2078
  */
2079
+ /**
2080
+ * A wake frame's payload typed as every shape it can have: the reminder, and
2081
+ * on a socket that negotiated `rewake` the `unanswered` wake and reasons this
2082
+ * SDK does not know yet. Discriminate on `reason`.
2083
+ */
2084
+ declare function wakePayloadOf(frame: WakeFrame | AnyWakeFrame): AnyWakePayload;
1756
2085
  declare function isAuthRejectionClose(code: number, reason: string): boolean;
1757
2086
  declare class RealtimeClient {
1758
2087
  private ws;
@@ -1784,6 +2113,11 @@ declare class RealtimeClient {
1784
2113
  private lastInboundAt;
1785
2114
  private authenticated;
1786
2115
  private ackMode;
2116
+ private negotiated;
2117
+ private offeredThisHello;
2118
+ private helloSent;
2119
+ private quietReconnect;
2120
+ private upgradeRejection;
1787
2121
  /** One error per long outage, then silent until a stable connection. */
1788
2122
  private longOutageAnnounced;
1789
2123
  /** One error per run of rejected handshakes, then silent until hello.ok. */
@@ -1796,6 +2130,11 @@ declare class RealtimeClient {
1796
2130
  private drainSettlements;
1797
2131
  private drainInFlight;
1798
2132
  private orderStates;
2133
+ private lanes;
2134
+ private queuedJobs;
2135
+ private shedding;
2136
+ private refetchPending;
2137
+ private drainAgain;
1799
2138
  private disposed;
1800
2139
  constructor(options: RealtimeOptions);
1801
2140
  /**
@@ -1890,6 +2229,7 @@ declare class RealtimeClient {
1890
2229
  * longer `this.ws`.
1891
2230
  */
1892
2231
  private abandonSocket;
2232
+ /** `serverDelayMs`: the server said how long to wait (connect budget); it replaces the backoff step. */
1893
2233
  private scheduleReconnect;
1894
2234
  /**
1895
2235
  * The server rejected the credential. `blocked` is not the end: a fresh
@@ -1913,6 +2253,8 @@ declare class RealtimeClient {
1913
2253
  private longOutageCap;
1914
2254
  /** Symmetric ±ratio jitter around `ms` — for the blocked retry, a range (10–15 min), not a cap. */
1915
2255
  private jittered;
2256
+ /** Jitter in [ms, ms × (1 + ratio)]: `ms` is a floor (a server-given delay is never shortened). */
2257
+ private jitteredAbove;
1916
2258
  /** Jitter in [ms × (1 − ratio), ms]: `ms` is a ceiling. Thundering-herd-safe across a fleet. */
1917
2259
  private jitteredBelow;
1918
2260
  private armHandshakeDeadline;
@@ -1940,6 +2282,7 @@ declare class RealtimeClient {
1940
2282
  * are released.
1941
2283
  */
1942
2284
  on(event: 'wake', handler: WakeHandler): () => void;
2285
+ on(event: 'heartbeat', handler: HeartbeatHandler): () => void;
1943
2286
  on(event: 'state', handler: StateHandler): () => void;
1944
2287
  on(event: 'blocked', handler: BlockedHandler): () => void;
1945
2288
  on(event: 'stopped', handler: StoppedHandler): () => void;
@@ -1986,6 +2329,18 @@ declare class RealtimeClient {
1986
2329
  * a legacy server (which marks envelopes delivered on push).
1987
2330
  */
1988
2331
  get ackNegotiated(): boolean;
2332
+ /**
2333
+ * `true` while backpressure refuses new messages: from the moment the
2334
+ * handler queue filled (`maxQueuedMessages`) until it is back to half and,
2335
+ * without a REST client, the reconnect that fetches what was left is up.
2336
+ * A host can alarm when it stays true (handlers that hang).
2337
+ */
2338
+ get intakePaused(): boolean;
2339
+ /**
2340
+ * The capabilities this connection's `hello.ok` accepted (`ack`,
2341
+ * `heartbeat`, `rewake`, …). Empty before `hello.ok` and after a close.
2342
+ */
2343
+ get capabilities(): ReadonlySet<string>;
1989
2344
  /**
1990
2345
  * Close the socket, cancel every timer, and release all handlers. The
1991
2346
  * only way into `stopped`, and the only way the client ever stops on
@@ -2018,6 +2373,44 @@ declare class RealtimeClient {
2018
2373
  * that cursor.
2019
2374
  */
2020
2375
  private dispatchMessageNew;
2376
+ /**
2377
+ * Invoke one message's handlers (in registration order, synchronously),
2378
+ * then wait for every one of them. `true` when all finished without
2379
+ * throwing. Synchronous when every handler is (so a lane of plain
2380
+ * handlers never waits a tick); a promise otherwise. Never rejects.
2381
+ */
2382
+ private invokeMessageHandlers;
2383
+ /** A message's serial lane: its conversation, or one lane for messages that name none. */
2384
+ private laneOf;
2385
+ /**
2386
+ * Run `task` when the lane is free: at once (synchronously) on an idle
2387
+ * lane, else after the task before it has finished. At most one task per
2388
+ * lane runs at a time; lanes run concurrently with each other.
2389
+ */
2390
+ private runInLane;
2391
+ /**
2392
+ * New messages are not taken in: the queue is full, or a shedding episode
2393
+ * is under way (until the queue is back to half — a frame accepted in
2394
+ * between could overtake one left with the server in its conversation).
2395
+ */
2396
+ private queueFull;
2397
+ /**
2398
+ * Whether a new message is refused at intake. A full queue (or an episode
2399
+ * under way) refuses and starts/continues the episode; a refetch reconnect
2400
+ * under way refuses quietly — the new socket re-offers everything stored.
2401
+ */
2402
+ private refuseIntake;
2403
+ /** The queue is full: messages are left with the server from here (one notice per episode). */
2404
+ private startShedding;
2405
+ /** One handler run finished; once the queue is back to half, fetch what was left with the server. */
2406
+ private jobDone;
2407
+ /**
2408
+ * How long one handler run holds its lane: until it finishes, or
2409
+ * `inFlightAdoptMs` at most — a handler that never finishes must not stop
2410
+ * its conversation for good (it keeps running; the next message goes on).
2411
+ */
2412
+ private heldAtMost;
2413
+ private setLaneTail;
2021
2414
  /**
2022
2415
  * Best-effort delivery ack for one processed message. No-op unless the
2023
2416
  * server negotiated ack-mode on this connection. Send failures are
@@ -2028,6 +2421,32 @@ declare class RealtimeClient {
2028
2421
  private sendAckFrame;
2029
2422
  private dedupHit;
2030
2423
  private dedupAdd;
2424
+ /**
2425
+ * The capabilities this HELLO offers. `ack` only while a `message.new`
2426
+ * handler is attached: with no handler nothing on this machine receives a
2427
+ * message, and an ack-mode socket that never acks would leave every
2428
+ * envelope `stored` until the recipient backlog cap. Without `ack` the
2429
+ * server marks envelopes delivered as it sends them, which is what a
2430
+ * handler-less 1.2 client effectively got (it acked frames no handler saw).
2431
+ * The next HELLO, after a handler is attached, offers it again.
2432
+ */
2433
+ private helloCapabilities;
2434
+ /**
2435
+ * The first `message.new` handler was attached after this socket's HELLO
2436
+ * went out without `ack`: reconnect once, quietly (no error, no backoff
2437
+ * step), so the next HELLO negotiates delivery acks. Frames parked on a
2438
+ * seq gap are handed to the handlers first — this socket was marked on
2439
+ * send, so nothing would re-offer them.
2440
+ */
2441
+ private maybeRenegotiateAck;
2442
+ /**
2443
+ * A quiet reconnect: close the socket politely and keep reading its frames
2444
+ * until it has closed; the close then reconnects at once (no backoff step,
2445
+ * no notice). Its liveness watchdog still ends a pipe that never answers.
2446
+ */
2447
+ private closePolitely;
2448
+ /** A `message.new` handler is attached: only then has this machine received a message. */
2449
+ private hasMessageHandler;
2031
2450
  private extractMessageId;
2032
2451
  private isMessageNew;
2033
2452
  private isWake;
@@ -2059,16 +2478,21 @@ declare class RealtimeClient {
2059
2478
  *
2060
2479
  * Code we keep, brain we don't
2061
2480
  * ────────────────────────────
2062
- * Every word the model reads about AgentChat comes from the tray: the gate
2063
- * question (`tray.question`) and the categories (`tray.categories`) are
2064
- * rendered verbatim, and each card is rendered as the server built it. This
2065
- * module adds a preamble that frames the call as a tool-less triage, the
2066
- * output-shape wrapper, the parser, and the recording through
2067
- * `client.decisions.record`. No model runs here: the host passes
2068
- * `callModel(prompt) => Promise<string>` so the judgement is the agent's own
2069
- * model, in the host's own harness. That call MUST be a plain completion
2070
- * with no tools attached: the served question mentions tools, and a model
2071
- * that could call them would act instead of answering.
2481
+ * Every word the model reads comes from the server. The gate question
2482
+ * (`tray.question`) and the categories (`tray.categories`) are rendered
2483
+ * verbatim and each card as the server built it; the text that frames the
2484
+ * call as a tool-less triage and the answer shape it ends with are the
2485
+ * served `texts.gate_call_preamble` and `texts.gate_call_answer_format`
2486
+ * (contract v1, D6). A caller that passes no texts (or a server that serves
2487
+ * neither field) gets the wording this SDK used before the texts carried it
2488
+ * (`LEGACY_GATE_CALL_PREAMBLE`, deprecated, kept until the next major), so an
2489
+ * installed integration on a floating 1.x range keeps working unchanged. This
2490
+ * module adds the card labels, the parser, and
2491
+ * the recording through `client.decisions.record`. No model runs here: the
2492
+ * host passes `callModel(prompt) => Promise<string>` so the judgement is the
2493
+ * agent's own model, in the host's own harness. That call MUST be a plain
2494
+ * completion with no tools attached: the served question mentions tools,
2495
+ * and a model that could call them would act instead of answering.
2072
2496
  *
2073
2497
  * What gets recorded, and when
2074
2498
  * ────────────────────────────
@@ -2122,6 +2546,16 @@ declare const BARE_TOOL_NAMER: ToolNamer;
2122
2546
  * `mcpToolNamer('agentchat')('agentchat_decide')` → `mcp__agentchat__agentchat_decide`.
2123
2547
  */
2124
2548
  declare function mcpToolNamer(serverName: string): ToolNamer;
2549
+ /**
2550
+ * @deprecated The served `texts.gate_call_preamble` replaces it. Kept, byte
2551
+ * for byte, for callers that pass no texts; removed in the next major.
2552
+ */
2553
+ declare function LEGACY_GATE_CALL_PREAMBLE(namer?: ToolNamer): string;
2554
+ /**
2555
+ * @deprecated The served `texts.gate_call_answer_format` replaces it. Kept,
2556
+ * byte for byte, for callers that pass no texts; removed in the next major.
2557
+ */
2558
+ declare function LEGACY_GATE_CALL_ANSWER_FORMAT(categories: readonly string[]): string;
2125
2559
  /** One parsed answer for one card. Snake-case: it is data, shared with the conformance fixtures. */
2126
2560
  interface Verdict {
2127
2561
  conversation_id: string;
@@ -2129,8 +2563,17 @@ interface Verdict {
2129
2563
  /** A category from the tray's list, or null when the model gave none or an unknown one. */
2130
2564
  category: ReplyDecisionCategory | null;
2131
2565
  }
2566
+ /** The two served texts a gate call is framed with (`GET /v1/texts`, contract v1). */
2567
+ type GateTexts = Pick<Texts, 'gate_call_preamble' | 'gate_call_answer_format'>;
2132
2568
  interface BuildPromptOptions {
2133
- /** How this runtime spells the hosted tools named inside the question. Default: as served. */
2569
+ /**
2570
+ * The served texts. `gate_call_preamble` opens the prompt and
2571
+ * `gate_call_answer_format` closes it, verbatim (they are already spelled
2572
+ * for the runtime the texts were fetched for). Optional: a field that is
2573
+ * absent falls back to the legacy wording this SDK always used.
2574
+ */
2575
+ texts?: GateTexts | null;
2576
+ /** How this runtime spells the hosted tools named inside the tray's question. Default: as served. */
2134
2577
  toolNamer?: ToolNamer;
2135
2578
  }
2136
2579
  /**
@@ -2151,9 +2594,11 @@ declare function anchorOf(card: InboxCard): string | undefined;
2151
2594
  */
2152
2595
  declare function canonicalJson(value: unknown): string;
2153
2596
  /**
2154
- * Render the gate prompt for one tray: a preamble that frames the call as a
2155
- * tool-less triage, the server's question verbatim, the categories, one
2156
- * block per card, then the output shape. Pure.
2597
+ * Render the gate prompt for one tray: the preamble, the tray's question
2598
+ * verbatim, the categories, one block per card, then the answer format.
2599
+ * Pure. The preamble and the answer format are the served texts when given
2600
+ * (`texts.gate_call_preamble`, `texts.gate_call_answer_format`), else the
2601
+ * legacy wording (deprecated; unchanged from 1.2).
2157
2602
  *
2158
2603
  * Throws when the tray carries no question — judging without it is exactly
2159
2604
  * the drift this design removes, so the gate fails closed instead.
@@ -2173,20 +2618,32 @@ declare function parseVerdicts(text: string | null | undefined, tray: InboxTray)
2173
2618
  declare function normalizeDecision(value: unknown): ReplyDecisionVerdict | null;
2174
2619
  /**
2175
2620
  * The host's model call. Receives the rendered prompt, returns the model's
2176
- * raw text. MUST be a plain completion with no tools attached: the served
2621
+ * raw text. `signal` (when given, e.g. by the `ReceiveLoop`'s gate-call
2622
+ * deadline) aborts when the answer is no longer wanted. MUST be a plain completion with no tools attached: the served
2177
2623
  * question names hosted tools, and a model that could call them would act
2178
2624
  * instead of answering (no JSON → fail closed, or a tool call AND JSON →
2179
2625
  * a verdict recorded twice).
2180
2626
  */
2181
- type GateModelCall = (prompt: string) => Promise<string>;
2627
+ type GateModelCall = (prompt: string, options?: {
2628
+ signal?: AbortSignal;
2629
+ }) => Promise<string>;
2182
2630
  /** The one client surface the gate needs; `AgentChatClient` satisfies it. */
2183
2631
  type GateClient = Pick<AgentChatClient, 'decisions'>;
2184
2632
  interface RunGateOptions {
2185
2633
  tray: InboxTray;
2186
2634
  callModel: GateModelCall;
2187
2635
  client: GateClient;
2636
+ /** The served texts (`gate_call_preamble`, `gate_call_answer_format`). Absent: the legacy wording (deprecated). */
2637
+ texts?: GateTexts | null;
2188
2638
  /** How this runtime spells the hosted tools named inside the question. */
2189
2639
  toolNamer?: ToolNamer;
2640
+ /**
2641
+ * Stops the gate: once aborted, no further verdict is recorded and no reply
2642
+ * is handed back (the cards not yet recorded count as undecided). The
2643
+ * model call gets it too. The `ReceiveLoop` passes its cycle's signal, so
2644
+ * an abandoned cycle records nothing more.
2645
+ */
2646
+ signal?: AbortSignal;
2190
2647
  }
2191
2648
  type GateOutcome =
2192
2649
  /** The model answered; dismiss/defer verdicts were recorded, replies await `record()`. */
@@ -2249,6 +2706,9 @@ type gate_GateOutcome = GateOutcome;
2249
2706
  type gate_GateRecordFailure = GateRecordFailure;
2250
2707
  type gate_GateReply = GateReply;
2251
2708
  type gate_GateResult = GateResult;
2709
+ type gate_GateTexts = GateTexts;
2710
+ declare const gate_LEGACY_GATE_CALL_ANSWER_FORMAT: typeof LEGACY_GATE_CALL_ANSWER_FORMAT;
2711
+ declare const gate_LEGACY_GATE_CALL_PREAMBLE: typeof LEGACY_GATE_CALL_PREAMBLE;
2252
2712
  type gate_RunGateOptions = RunGateOptions;
2253
2713
  type gate_ToolNamer = ToolNamer;
2254
2714
  type gate_Verdict = Verdict;
@@ -2261,7 +2721,1272 @@ declare const gate_normalizeDecision: typeof normalizeDecision;
2261
2721
  declare const gate_parseVerdicts: typeof parseVerdicts;
2262
2722
  declare const gate_run: typeof run;
2263
2723
  declare namespace gate {
2264
- export { gate_BARE_TOOL_NAMER as BARE_TOOL_NAMER, type gate_BuildPromptOptions as BuildPromptOptions, type gate_GateClient as GateClient, type gate_GateModelCall as GateModelCall, type gate_GateOutcome as GateOutcome, type gate_GateRecordFailure as GateRecordFailure, type gate_GateReply as GateReply, type gate_GateResult as GateResult, type gate_RunGateOptions as RunGateOptions, type gate_ToolNamer as ToolNamer, type gate_Verdict as Verdict, gate_anchorOf as anchorOf, gate_buildPrompt as buildPrompt, gate_canonicalJson as canonicalJson, gate_cardsOf as cardsOf, gate_mcpToolNamer as mcpToolNamer, gate_normalizeDecision as normalizeDecision, gate_parseVerdicts as parseVerdicts, gate_run as run };
2724
+ export { gate_BARE_TOOL_NAMER as BARE_TOOL_NAMER, type gate_BuildPromptOptions as BuildPromptOptions, type gate_GateClient as GateClient, type gate_GateModelCall as GateModelCall, type gate_GateOutcome as GateOutcome, type gate_GateRecordFailure as GateRecordFailure, type gate_GateReply as GateReply, type gate_GateResult as GateResult, type gate_GateTexts as GateTexts, gate_LEGACY_GATE_CALL_ANSWER_FORMAT as LEGACY_GATE_CALL_ANSWER_FORMAT, gate_LEGACY_GATE_CALL_PREAMBLE as LEGACY_GATE_CALL_PREAMBLE, type gate_RunGateOptions as RunGateOptions, type gate_ToolNamer as ToolNamer, type gate_Verdict as Verdict, gate_anchorOf as anchorOf, gate_buildPrompt as buildPrompt, gate_canonicalJson as canonicalJson, gate_cardsOf as cardsOf, gate_mcpToolNamer as mcpToolNamer, gate_normalizeDecision as normalizeDecision, gate_parseVerdicts as parseVerdicts, gate_run as run };
2725
+ }
2726
+
2727
+ /**
2728
+ * Wake coalescing: one cycle per burst, never one per frame.
2729
+ *
2730
+ * A wake is a hint that the tray may have changed, never the carrier of what
2731
+ * changed: a `message.new` frame, a `wake` frame, a (re)connect, a webhook
2732
+ * the integration received. A group waking up arrives as many frames seconds
2733
+ * apart; whoever runs the cycle reads the whole tray, so nothing a later
2734
+ * frame announced is missed. The tray is the truth, the wake is not.
2735
+ *
2736
+ * Timing (conformance `coalescer.cases.json`):
2737
+ * - The window is trailing-edge: every wake moves the start to `quietMs`
2738
+ * after it, but never past `maxMs` after the burst's first wake, so a
2739
+ * steady trickle cannot starve the cycle.
2740
+ * - One cycle at a time. A wake while a cycle runs earns exactly one more
2741
+ * cycle after it, however many arrive: due `quietMs` after the last of
2742
+ * them, capped at `maxMs` after the first, never before the cycle ended.
2743
+ *
2744
+ * There is no delayed or retry wake here: the server re-wakes unanswered
2745
+ * cards on its own durable ladder (contract v1, D3), so an integration keeps
2746
+ * no retry ladder of its own.
2747
+ *
2748
+ * Where the copies this replaces differed (OpenClaw `integration/wake.ts`,
2749
+ * agent-core `integration/wake.ts`, Hermes `wake.py`): the OpenClaw window
2750
+ * (trailing edge with a cap) is kept over the fixed window the other two
2751
+ * used; the "one more cycle" rule the three invokers each wrote is kept here,
2752
+ * in one place; `wakeAfter` / `cancelDelayed` (the local retry ladder) are
2753
+ * gone.
2754
+ */
2755
+ declare const DEFAULT_QUIET_MS = 2000;
2756
+ declare const DEFAULT_MAX_MS = 6000;
2757
+ type TimerHandle = ReturnType<typeof setTimeout>;
2758
+ interface WakeCoalescerOptions {
2759
+ /** The cycle. Its promise settling (either way) ends the cycle. */
2760
+ readonly onCycle: () => void | Promise<unknown>;
2761
+ /** Quiet time after the last wake before the cycle starts. Default 2000. */
2762
+ readonly quietMs?: number;
2763
+ /** A burst starts its cycle no later than this after its first wake. Default 6000. */
2764
+ readonly maxMs?: number;
2765
+ /** Called when `onCycle` throws or rejects; the coalescer carries on either way. */
2766
+ readonly onError?: (error: unknown) => void;
2767
+ readonly now?: () => number;
2768
+ readonly setTimeout?: (fn: () => void, ms: number) => TimerHandle;
2769
+ readonly clearTimeout?: (handle: TimerHandle) => void;
2770
+ }
2771
+ type CoalescerState = 'idle' | 'waiting' | 'running' | 'stopped';
2772
+ interface CoalescerCounters {
2773
+ /** Every `wake()` accepted (not after stop). */
2774
+ readonly wakes: number;
2775
+ /** Wakes that joined a window or a running cycle instead of starting one. */
2776
+ readonly absorbed: number;
2777
+ /** Cycles started. */
2778
+ readonly cycles: number;
2779
+ }
2780
+ declare class WakeCoalescer {
2781
+ private readonly onCycle;
2782
+ private readonly onError;
2783
+ private readonly quietMs;
2784
+ private readonly maxMs;
2785
+ private readonly now;
2786
+ private readonly _setTimeout;
2787
+ private readonly _clearTimeout;
2788
+ private timer;
2789
+ /** First wake of the burst the armed timer belongs to. */
2790
+ private burstStartedAt;
2791
+ private running;
2792
+ /** Wakes that arrived while the cycle ran: first and last. */
2793
+ private pendingFirstAt;
2794
+ private pendingLastAt;
2795
+ private stopped;
2796
+ private current;
2797
+ private wakeCount;
2798
+ private absorbedCount;
2799
+ private cycleCount;
2800
+ constructor(options: WakeCoalescerOptions);
2801
+ get state(): CoalescerState;
2802
+ /** True while a wake that arrived during the running cycle is waiting for it to end. */
2803
+ get pending(): boolean;
2804
+ counters(): CoalescerCounters;
2805
+ /** A wake. Starts a window, joins the open one, or earns one more cycle after the running one. */
2806
+ wake(): void;
2807
+ /** Cancel the window and drop pending wakes; a running cycle finishes on its own. Later wakes are ignored. */
2808
+ stop(): void;
2809
+ /** Resolves when the running cycle (if any) has ended. */
2810
+ idle(): Promise<void>;
2811
+ private arm;
2812
+ private clearTimer;
2813
+ private startCycle;
2814
+ private endCycle;
2815
+ private report;
2816
+ }
2817
+
2818
+ /**
2819
+ * What the host records after a gate-call turn (contract v1, D5).
2820
+ *
2821
+ * In gate-call mode the gate call records `dismiss` / `defer` at once and
2822
+ * starts one turn per `reply`. After that turn the host records from what
2823
+ * actually happened, read on a fresh tray, never from the runtime's "turn
2824
+ * ok":
2825
+ *
2826
+ * | After the turn | Host does |
2827
+ * |-------------------------------------------------------|----------------------------------------|
2828
+ * | runtime has not confirmed the end | nothing; the turn keeps its card |
2829
+ * | runtime reports failure | the card rules below that need no look (gone, own verdict, answer sent); otherwise nothing, the card stays (server re-wakes) |
2830
+ * | the turn recorded its own verdict (card gone, or `your_last_decision` moved) | nothing |
2831
+ * | the card shows the answer went out | `reply` through the anchor the gate saw |
2832
+ * | 0 AgentChat calls, or all failed (when countable) | nothing (it could not look) |
2833
+ * | it looked, sent nothing, recorded nothing | 1st time nothing; 2nd time for the same anchor `dismiss` (`no_action_needed`) when its AgentChat calls are known and all succeeded, else `defer` |
2834
+ *
2835
+ * `turnOutcome` is the pure decision (conformance `turn-outcome.cases.json`);
2836
+ * `applyOutcome` makes the one recording call. Invites follow the same rule
2837
+ * (`inviteOutcome` / `applyInviteOutcome`): an invite still pending after two
2838
+ * turns that looked is dismissed — seen, left pending, not shown again.
2839
+ *
2840
+ * Where the copies this replaces differed: OpenClaw recorded `reply` on any
2841
+ * turn whose run ended `ok`, Hermes on any completed turn (zero AgentChat
2842
+ * calls counted as success); both recorded `reply` when the post-turn tray
2843
+ * read failed. Here a failed read records nothing (the server's re-wake
2844
+ * covers it), "answer went out" is read from `your_last_message_at` moving
2845
+ * (clock-free, and true even when the peer has written again since), and a
2846
+ * verdict the turn recorded is recognised by `your_last_decision` changing
2847
+ * against the card the gate saw (clock-free, as both copies did; no local
2848
+ * clock is compared with a server time).
2849
+ */
2850
+
2851
+ /**
2852
+ * How many AgentChat calls a turn made, when the runtime can tell. `null`
2853
+ * (unknown) is treated as "it looked".
2854
+ */
2855
+ interface AgentChatCallCount {
2856
+ made: number;
2857
+ failed: number;
2858
+ }
2859
+ /**
2860
+ * What the runtime reports about a turn. A wait that timed out is not an
2861
+ * end: report `still_running` (with `next` when the runtime can say when it
2862
+ * really ends) and the turn keeps its conversation.
2863
+ */
2864
+ type TurnEnd = {
2865
+ status: 'completed';
2866
+ agentchatCalls?: AgentChatCallCount | null;
2867
+ detail?: string;
2868
+ } | {
2869
+ status: 'failed';
2870
+ agentchatCalls?: AgentChatCallCount | null;
2871
+ detail?: string;
2872
+ } | {
2873
+ status: 'still_running';
2874
+ next?: Promise<TurnEnd>;
2875
+ detail?: string;
2876
+ };
2877
+ type TurnOutcomeReason = 'turn_failed' | 'turn_running' | 'card_unknown' | 'card_left_tray' | 'turn_recorded_verdict' | 'answer_sent' | 'could_not_look' | 'silent_first' | 'silent_again';
2878
+ type TurnOutcome = {
2879
+ action: 'none';
2880
+ reason: Exclude<TurnOutcomeReason, 'answer_sent' | 'silent_again'>;
2881
+ conversationId: string;
2882
+ } | {
2883
+ action: 'record_reply';
2884
+ reason: 'answer_sent';
2885
+ conversationId: string;
2886
+ throughMessageId: string | null;
2887
+ category: ReplyDecisionCategory | null;
2888
+ } | {
2889
+ action: 'record_dismiss';
2890
+ reason: 'silent_again';
2891
+ conversationId: string;
2892
+ throughMessageId: string | null;
2893
+ category: 'no_action_needed';
2894
+ } | {
2895
+ /** The second silent look when the turn's AgentChat calls are unknown or some failed: unread, back on the reminder ladder. */
2896
+ action: 'record_defer';
2897
+ reason: 'silent_again';
2898
+ conversationId: string;
2899
+ throughMessageId: string | null;
2900
+ category: null;
2901
+ };
2902
+ interface TurnOutcomeInput {
2903
+ turn: TurnEnd;
2904
+ /** When the host started the turn (an ISO string, epoch ms or a Date). Informational: the rule compares no clocks. */
2905
+ turnStartedAt: string | number | Date;
2906
+ /** The card the gate saw when it decided `reply`. */
2907
+ gateCard: InboxCard;
2908
+ /** The category the gate attached to the reply. */
2909
+ category?: ReplyDecisionCategory | null;
2910
+ /** The tray read after the turn; `null` when that read failed. */
2911
+ freshTray: Pick<InboxTray, 'conversations' | 'truncated'> | null;
2912
+ /** Earlier turns for the same anchor that looked and did nothing. Default 0. */
2913
+ silentBefore?: number;
2914
+ }
2915
+ /** The D5 decision for one finished reply turn. Pure. */
2916
+ declare function turnOutcome(input: TurnOutcomeInput): TurnOutcome;
2917
+ type InviteOutcomeReason = 'turn_failed' | 'turn_running' | 'invite_unknown' | 'invite_answered' | 'could_not_look' | 'silent_first'
2918
+ /** Looked again, but the call count cannot confirm the tools worked: nothing recorded. */
2919
+ | 'silent_unconfirmed'
2920
+ /** Single-run mode (the loop's call): a second ignoring run inside the pacing window does not count. */
2921
+ | 'silent_paced' | 'silent_again';
2922
+ type InviteOutcome = {
2923
+ action: 'none';
2924
+ reason: Exclude<InviteOutcomeReason, 'silent_again'>;
2925
+ inviteId: string;
2926
+ } | {
2927
+ action: 'dismiss_invite';
2928
+ reason: 'silent_again';
2929
+ inviteId: string;
2930
+ };
2931
+ interface InviteOutcomeInput {
2932
+ turn: TurnEnd;
2933
+ invite: TrayInvite;
2934
+ /** The tray read after the turn; `null` when that read failed. */
2935
+ freshTray: Pick<InboxTray, 'invites' | 'invites_truncated'> | null;
2936
+ /** Earlier turns for this invite that looked and left it pending. Default 0. */
2937
+ silentBefore?: number;
2938
+ /**
2939
+ * Dismiss only after a turn whose AgentChat calls are known and none
2940
+ * failed (default `true`). Single-run mode passes `false`: a run reports
2941
+ * no counts, and its own invite rule applies (`single_run_invite_cases`).
2942
+ */
2943
+ requireKnownCalls?: boolean;
2944
+ }
2945
+ /** The D5 rule applied to a group-invite turn. Pure. */
2946
+ declare function inviteOutcome(input: InviteOutcomeInput): InviteOutcome;
2947
+ /** The client surface `applyOutcome` needs; `AgentChatClient` satisfies it. */
2948
+ type OutcomeClient = Pick<AgentChatClient, 'decisions'>;
2949
+ /**
2950
+ * Make the one recording call an outcome asks for: `reply` or `dismiss`
2951
+ * through the gate's anchor. `none` makes no call. Returns whether a verdict
2952
+ * was recorded; a server error is thrown to the caller (the card stays on
2953
+ * the tray and the server re-wakes).
2954
+ */
2955
+ declare function applyOutcome(client: OutcomeClient, outcome: TurnOutcome): Promise<boolean>;
2956
+ /** The client surface `applyInviteOutcome` needs. */
2957
+ type InviteOutcomeClient = Pick<AgentChatClient, 'groups'>;
2958
+ /** Dismiss the invite when the outcome says so. Returns whether a call was made. */
2959
+ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: InviteOutcome): Promise<boolean>;
2960
+
2961
+ /**
2962
+ * The identity block: the served identity line, fenced, in the file the
2963
+ * runtime loads on every turn (`AGENTS.md`, `SOUL.md`, `CLAUDE.md`, …).
2964
+ * Pure string functions — which file, and when to write it, is the
2965
+ * integration's business (a shared function that picked the file once
2966
+ * stamped one agent's handle into another agent's file).
2967
+ *
2968
+ * The words are the server's (`texts.identity_line`). This module adds the
2969
+ * fences and one handle line, so a block is recognised whatever the served
2970
+ * wording becomes:
2971
+ *
2972
+ * <!-- agentchat:start -->
2973
+ * <!-- agentchat:handle example-relay -->
2974
+ * I am @example-relay on AgentChat …
2975
+ * <!-- agentchat:end -->
2976
+ *
2977
+ * Blocks written before the handle line are recognised by the served
2978
+ * template's words and by the two wordings earlier releases wrote, and the
2979
+ * legacy `agentchat-skill` markers are still found and replaced
2980
+ * (conformance `anchor.cases.json`).
2981
+ *
2982
+ * Where the copies this replaces differed (agent-core `anchor/block.ts`,
2983
+ * OpenClaw `binding/agents-anchor.ts`, Hermes `soul_anchor.py`), the
2984
+ * stricter behaviour is kept: markers count only as whole lines (agent-core;
2985
+ * a marker quoted in prose is not a fence); every duplicate and legacy block
2986
+ * is removed (agent-core) while the block keeps its place in the file
2987
+ * (OpenClaw, Hermes); the handle line and the template-based recognition
2988
+ * (Hermes); a wrong handle is read back rather than ignored (agent-core).
2989
+ * New: a start marker with no end before the next start is ignored instead
2990
+ * of fencing everything up to a later block.
2991
+ */
2992
+
2993
+ declare const START_MARKER = "<!-- agentchat:start -->";
2994
+ declare const END_MARKER = "<!-- agentchat:end -->";
2995
+ declare const LEGACY_START_MARKER = "<!-- agentchat-skill:start -->";
2996
+ declare const LEGACY_END_MARKER = "<!-- agentchat-skill:end -->";
2997
+ /** Handles are canonical lowercase on the wire; a leading `@` is display only. */
2998
+ declare function normalizeHandle(handle: string): string;
2999
+ declare function handleLine(handle: string): string;
3000
+ /**
3001
+ * The block for `handle`: the fences, the handle line and the served line.
3002
+ * Uses `texts.identity_line` when it names `@handle`, else fills
3003
+ * `texts.identity_line_template`. Throws when the handle is empty or no
3004
+ * served text names it — a silently wrong identity is worse than a loud
3005
+ * failure: the agent would hand peers an address that reaches someone else.
3006
+ */
3007
+ declare function render(texts: Pick<Texts, 'identity_line' | 'identity_line_template'>, handle: string): string;
3008
+ interface FoundBlock {
3009
+ /** Offset of the start marker's line. */
3010
+ readonly start: number;
3011
+ /** Offset just past the end marker (before its line break). */
3012
+ readonly end: number;
3013
+ /** The handle the block claims, lower-cased; null for a block in a shape not recognised (hand-edited). */
3014
+ readonly handle: string | null;
3015
+ /** The block carries a handle line. */
3016
+ readonly marked: boolean;
3017
+ /** The block uses the legacy `agentchat-skill` markers. */
3018
+ readonly legacy: boolean;
3019
+ /** Between the markers, without the handle line; CRLF read as LF; trimmed. */
3020
+ readonly body: string;
3021
+ }
3022
+ interface FindOptions {
3023
+ /** The served `identity_line_template`: recognises an unmarked block by its words. */
3024
+ readonly template?: string | null;
3025
+ }
3026
+ /** The first current block, else the first legacy block, else null. */
3027
+ declare function find(text: string, options?: FindOptions): FoundBlock | null;
3028
+ /**
3029
+ * `text` with `block` in place of the first block (current or legacy) and
3030
+ * every other block removed; appended after one blank line when there is
3031
+ * none. Idempotent.
3032
+ */
3033
+ declare function replace(text: string, block: string): string;
3034
+ /** `text` without any block (current or legacy); unchanged when there is none. */
3035
+ declare function remove(text: string): string;
3036
+
3037
+ declare const anchor_END_MARKER: typeof END_MARKER;
3038
+ type anchor_FindOptions = FindOptions;
3039
+ type anchor_FoundBlock = FoundBlock;
3040
+ declare const anchor_LEGACY_END_MARKER: typeof LEGACY_END_MARKER;
3041
+ declare const anchor_LEGACY_START_MARKER: typeof LEGACY_START_MARKER;
3042
+ declare const anchor_START_MARKER: typeof START_MARKER;
3043
+ declare const anchor_find: typeof find;
3044
+ declare const anchor_handleLine: typeof handleLine;
3045
+ declare const anchor_normalizeHandle: typeof normalizeHandle;
3046
+ declare const anchor_remove: typeof remove;
3047
+ declare const anchor_render: typeof render;
3048
+ declare const anchor_replace: typeof replace;
3049
+ declare namespace anchor {
3050
+ export { anchor_END_MARKER as END_MARKER, type anchor_FindOptions as FindOptions, type anchor_FoundBlock as FoundBlock, anchor_LEGACY_END_MARKER as LEGACY_END_MARKER, anchor_LEGACY_START_MARKER as LEGACY_START_MARKER, anchor_START_MARKER as START_MARKER, anchor_find as find, anchor_handleLine as handleLine, anchor_normalizeHandle as normalizeHandle, anchor_remove as remove, anchor_render as render, anchor_replace as replace };
3051
+ }
3052
+
3053
+ /**
3054
+ * Turns that are running, per conversation (reply turns) and per invite
3055
+ * (invite turns). While a reply turn runs, its conversation's card stays on
3056
+ * the tray (the verdict is recorded when the turn has ended), so every wake
3057
+ * in between would gate it again and start a second turn: the tracker is
3058
+ * what keeps such cards out of the gate.
3059
+ *
3060
+ * A turn ends only when the runtime confirms it ended. A wait that timed out
3061
+ * is not an end: the runtime reports `still_running` and the turn keeps its
3062
+ * conversation, following `next` when the runtime can say when it really
3063
+ * ends. Only `release()` lets go of a turn whose end never comes.
3064
+ *
3065
+ * Where the copies this replaces differed: OpenClaw ended a turn when its
3066
+ * wait timed out (so a second turn could start for a conversation whose
3067
+ * first was still running); Hermes ran one turn per cycle and held the
3068
+ * worker; agent-core ran one run at a time. Here the turn is held until its
3069
+ * confirmed end, and cycles go on meanwhile.
3070
+ */
3071
+
3072
+ type TrackedTurn = {
3073
+ readonly kind: 'reply';
3074
+ readonly conversationId: string;
3075
+ readonly anchor: string | null;
3076
+ } | {
3077
+ readonly kind: 'invite';
3078
+ readonly inviteId: string;
3079
+ };
3080
+ type RunningTurn = TrackedTurn & {
3081
+ /** Epoch ms the host started the turn. */
3082
+ readonly startedAt: number;
3083
+ /** Epoch ms the last wait timed out without an end, or null. */
3084
+ readonly waitTimedOutAt: number | null;
3085
+ };
3086
+ interface TurnHandle {
3087
+ readonly key: string;
3088
+ readonly turn: TrackedTurn;
3089
+ readonly startedAt: number;
3090
+ }
3091
+ /** A confirmed end: `completed` or `failed`. */
3092
+ type ConfirmedTurnEnd = Extract<TurnEnd, {
3093
+ status: 'completed' | 'failed';
3094
+ }>;
3095
+ declare class TurnTracker {
3096
+ private readonly now;
3097
+ private readonly turns;
3098
+ /** Waits on a turn's end, ended by `release`. */
3099
+ private readonly waiters;
3100
+ constructor(options?: {
3101
+ now?: () => number;
3102
+ });
3103
+ /** Start tracking a turn. Null when one is already running for that conversation or invite. */
3104
+ begin(turn: TrackedTurn): TurnHandle | null;
3105
+ conversationRunning(conversationId: string): boolean;
3106
+ inviteRunning(inviteId: string): boolean;
3107
+ /** The cards whose conversation has no running turn: the ones a gate may see. */
3108
+ withoutRunning<T extends Pick<InboxCard, 'conversation_id'>>(cards: readonly T[]): T[];
3109
+ /** Snapshot for status. */
3110
+ running(): RunningTurn[];
3111
+ get size(): number;
3112
+ /**
3113
+ * Follow what the runtime reports until it confirms the end, through any
3114
+ * number of `still_running` reports. Resolves with the confirmed end, or
3115
+ * never when the runtime cannot say (until `release`). A rejected report
3116
+ * counts as a failed turn. The turn stays tracked: call `end` once its
3117
+ * outcome is recorded.
3118
+ */
3119
+ confirmedEnd(handle: TurnHandle, done: Promise<TurnEnd>): Promise<ConfirmedTurnEnd | null>;
3120
+ /** Called with every turn `release` lets go of (a loop frees its slot). */
3121
+ onRelease(listener: (handle: TurnHandle) => void): () => void;
3122
+ private readonly releaseListeners;
3123
+ /** Whether this turn is still tracked (not ended, not released). Check it after every await before recording. */
3124
+ holds(handle: TurnHandle): boolean;
3125
+ /** Stop tracking a turn (its outcome is recorded, or it never started). */
3126
+ end(handle: TurnHandle): void;
3127
+ /**
3128
+ * Let go of a turn whose end will not be confirmed (an operator's call). Its
3129
+ * conversation may be gated again; nothing is recorded for it.
3130
+ */
3131
+ release(key: string): boolean;
3132
+ }
3133
+
3134
+ /**
3135
+ * The served texts, kept current: fetched at start and on a daily timer,
3136
+ * the last good copy kept in a file so an integration that starts offline is
3137
+ * not mute, and a change event for whatever is placed from them (the
3138
+ * identity block, the manual).
3139
+ *
3140
+ * Every text an agent sees is written once on the server and served as data
3141
+ * (`GET /v1/texts?runtime=`). This cache carries no copy of any of them.
3142
+ *
3143
+ * Policy (the stricter of the three copies this replaces — OpenClaw
3144
+ * `integration/texts.ts`, agent-core `integration/texts.ts`, Hermes
3145
+ * `texts.py`):
3146
+ * - the file is read at start, before the first fetch, and only a file
3147
+ * written for the same runtime counts (agent-core);
3148
+ * - a served copy is never replaced by the file: a failed refresh keeps
3149
+ * the last served copy (Hermes);
3150
+ * - after a failure the next attempt comes after 5 min, doubling to 1 h
3151
+ * (Hermes); after a success after `refreshMs` (24 h);
3152
+ * - one fetch attempt per call, bounded by a timeout, never retried
3153
+ * inside the call (the timer is the retry);
3154
+ * - the file is replaced atomically (temp + fsync + rename, mode 0600);
3155
+ * - listeners hear only real changes (content, not a re-fetch of the same).
3156
+ */
3157
+
3158
+ declare const TEXTS_REFRESH_MS: number;
3159
+ declare const TEXTS_RETRY_MS: number;
3160
+ declare const TEXTS_RETRY_MAX_MS: number;
3161
+ declare const TEXTS_FETCH_TIMEOUT_MS = 10000;
3162
+ /** What the cache needs from the client; `AgentChatClient` satisfies it. */
3163
+ type TextsClient = Pick<AgentChatClient, 'texts'> & {
3164
+ readonly baseUrl?: string;
3165
+ };
3166
+ type TextsSource$1 = 'server' | 'cache' | 'none';
3167
+ type TextsListener = (texts: Texts, source: Exclude<TextsSource$1, 'none'>) => void;
3168
+ interface TextsCacheOptions {
3169
+ readonly client: TextsClient;
3170
+ readonly runtime: TextsRuntime;
3171
+ /** Where the last good copy is kept. Without it nothing is written or read. */
3172
+ readonly filePath?: string;
3173
+ readonly refreshMs?: number;
3174
+ readonly retryMs?: number;
3175
+ readonly retryMaxMs?: number;
3176
+ readonly fetchTimeoutMs?: number;
3177
+ /** Called once per new failure condition (not once per retry) with what went wrong. */
3178
+ readonly onError?: (error: Error) => void;
3179
+ readonly now?: () => number;
3180
+ readonly setTimeout?: (fn: () => void, ms: number) => TimerHandle;
3181
+ readonly clearTimeout?: (handle: TimerHandle) => void;
3182
+ }
3183
+ /** The shape every consumer relies on. Extra fields a newer server adds pass through. */
3184
+ declare function isTexts(value: unknown): value is Texts;
3185
+ declare class TextsCache {
3186
+ readonly runtime: TextsRuntime;
3187
+ private readonly client;
3188
+ private readonly filePath;
3189
+ private readonly refreshMs;
3190
+ private readonly retryMs;
3191
+ private readonly retryMaxMs;
3192
+ private readonly fetchTimeoutMs;
3193
+ private readonly onError;
3194
+ private readonly now;
3195
+ private readonly _setTimeout;
3196
+ private readonly _clearTimeout;
3197
+ private readonly listeners;
3198
+ private texts;
3199
+ private _source;
3200
+ private _fetchedAt;
3201
+ private _lastError;
3202
+ private failures;
3203
+ private serverSeen;
3204
+ private inFlight;
3205
+ private timer;
3206
+ private started;
3207
+ private stopped;
3208
+ constructor(options: TextsCacheOptions);
3209
+ /** The texts in hand, or null until a copy exists. No network. */
3210
+ current(): Texts | null;
3211
+ /** Where `current()` came from: this process's fetch, the file, or nowhere yet. */
3212
+ get source(): TextsSource$1;
3213
+ /** When the current copy was served (also for a copy read from the file). */
3214
+ get fetchedAt(): string | null;
3215
+ /** The last fetch failure, cleared by the next success. */
3216
+ get lastError(): string | null;
3217
+ /** The API base the texts are fetched from — what a manual download is pinned to. */
3218
+ get apiBase(): string | null;
3219
+ /** Called with every copy that differs from the one before (from the file or the server). */
3220
+ onChange(listener: TextsListener): () => void;
3221
+ /**
3222
+ * Read the file, make one fetch, arm the timer. Resolves with what is in
3223
+ * hand once the first attempt has finished; never throws.
3224
+ */
3225
+ start(): Promise<Texts | null>;
3226
+ stop(): void;
3227
+ /**
3228
+ * The texts for a cycle: what is in hand, after one more fetch attempt if
3229
+ * the server has not answered yet in this process. Null only when the
3230
+ * server is unreachable and no copy was ever kept.
3231
+ */
3232
+ ensure(): Promise<Texts | null>;
3233
+ /** Fetch now (coalesced with one in flight), keep it, arm the next attempt. Resolves whether the server answered. */
3234
+ refresh(): Promise<boolean>;
3235
+ private fetchOnce;
3236
+ private adopt;
3237
+ private loadFile;
3238
+ private saveFile;
3239
+ private arm;
3240
+ private report;
3241
+ }
3242
+
3243
+ /**
3244
+ * The few file operations the kit needs (the texts cache, the manual), for
3245
+ * Node, Bun and Deno. `node:` modules are imported lazily, on first use, so
3246
+ * the SDK still loads in a browser or an edge runtime that never asks for a
3247
+ * file.
3248
+ *
3249
+ * `writeAtomic` is "never worse than before": a temp file beside the target
3250
+ * with an unguessable name, created exclusively (`wx`: a planted name or
3251
+ * symlink is refused, never followed), its mode set on the open descriptor,
3252
+ * flushed (fsync) and renamed over the target. A failed write removes its
3253
+ * temp file and leaves the old file exactly as it was. On Windows a rename
3254
+ * onto a file another process holds open fails transiently (EPERM / EBUSY /
3255
+ * EACCES while a scanner or an editor has it), so the rename is retried for
3256
+ * about 100 ms. Ported from agent-core `util/fsutil.ts`.
3257
+ */
3258
+ interface RenameOptions {
3259
+ /** Defaults to `fs.rename`; injectable for tests. */
3260
+ readonly rename?: (from: string, to: string) => Promise<void>;
3261
+ /** Defaults to Windows only, where the transient sharing errors happen. */
3262
+ readonly retry?: boolean;
3263
+ }
3264
+ /** `rename`, retried a few times over ~100 ms on a transient EPERM / EBUSY / EACCES. */
3265
+ declare function renameWithRetry(from: string, to: string, options?: RenameOptions): Promise<void>;
3266
+ interface WriteAtomicOptions extends RenameOptions {
3267
+ /** Exact file mode, whatever the umask. Default: the umask's (as a plain write). */
3268
+ readonly mode?: number;
3269
+ }
3270
+ /** Replace `file` with `data` atomically. Creates the directory (0700) when missing. Throws on failure; the old file is untouched then. */
3271
+ declare function writeAtomic(file: string, data: string | Uint8Array, options?: WriteAtomicOptions): Promise<void>;
3272
+
3273
+ /**
3274
+ * The served manual, placed and kept current. An integration's skill file
3275
+ * follows the manual the served texts announce (`texts.manual: {url,
3276
+ * version, sha256?}`). When the file on disk is not the announced one, the
3277
+ * announced address is downloaded, checked and written over the old file
3278
+ * atomically. The file is its own record: its front matter (`version:`) and,
3279
+ * when the server announces one, the sha256 of its bytes say what is placed.
3280
+ *
3281
+ * Ported from agent-core `skill/served-manual.ts`, keeping every property of
3282
+ * its security review:
3283
+ * - "never worse than before": offline, an error answer, a body over the
3284
+ * size cap, a body that is not the agentchat skill at the announced
3285
+ * version (or hash) — the existing file stays exactly as it is;
3286
+ * - where a download may go is decided by where the announcement came
3287
+ * from (the API base the texts were fetched from): an HTTPS base allows
3288
+ * every hop HTTPS on `agentchat.me`, `*.agentchat.me` or the base's own
3289
+ * host; a plain-HTTP loopback base (a development server) allows plain
3290
+ * HTTP to loopback only; any other plain-HTTP base allows no download;
3291
+ * - redirects are followed here, one hop at a time (at most three), each
3292
+ * hop checked — never a plaintext hop between two TLS ones, never off
3293
+ * those hosts, never an address carrying credentials;
3294
+ * - a size cap (declared and actual), a timeout over every hop, UTF-8
3295
+ * only, no NUL, front matter naming the skill at the announced version,
3296
+ * sha256 of the exact bytes when announced; a leading BOM and CRLF line
3297
+ * endings read the same as LF;
3298
+ * - the exact bytes that were checked are the bytes written: temp file,
3299
+ * fsync, rename (retried on Windows), the old file kept on any failure;
3300
+ * - fetched without credentials: the manual is public, and the agent's key
3301
+ * is never sent to an address the server merely names.
3302
+ * The body is text for a model to read; it is never executed or interpreted
3303
+ * beyond its front matter.
3304
+ *
3305
+ * Unlike agent-core this package bundles no manual (every text is served,
3306
+ * rule 3): an integration that wants a first-install fallback passes its own
3307
+ * `fallback` bytes, written only when no file exists and nothing verified
3308
+ * could be had, or when they are the announced manual.
3309
+ */
3310
+
3311
+ /** What the served texts announce: `Texts['manual']`. */
3312
+ type ServedManual = Texts['manual'];
3313
+ /** The manual is ~60 KB; anything past this is not the manual. */
3314
+ declare const MANUAL_MAX_BYTES: number;
3315
+ /** One attempt, every hop included. */
3316
+ declare const MANUAL_FETCH_TIMEOUT_MS = 10000;
3317
+ /** Redirects followed (each one checked) before giving up. */
3318
+ declare const MANUAL_MAX_REDIRECTS = 3;
3319
+ /** The skill the manual is: `<skills dir>/agentchat/SKILL.md`. */
3320
+ declare const MANUAL_SKILL_NAME = "agentchat";
3321
+ /** `fetch`'s shape, injectable for tests. Called with `redirect: 'manual'`. */
3322
+ type ManualFetch = (url: string, init: RequestInit) => Promise<Response>;
3323
+ /**
3324
+ * - `current` — the file already is the announced manual; nothing fetched.
3325
+ * - `updated` — the announced manual was written (downloaded, or the fallback when it is that manual).
3326
+ * - `kept` — the existing file was left as it was: nothing announced, or no verified copy could be had.
3327
+ * - `fallback` — no file existed and nothing verified could be had: the fallback bytes were written.
3328
+ * - `failed` — no file existed and none could be written (no fallback, or the write failed).
3329
+ */
3330
+ type ManualSyncState = 'current' | 'updated' | 'kept' | 'fallback' | 'failed';
3331
+ interface ManualSyncResult {
3332
+ readonly state: ManualSyncState;
3333
+ readonly path: string;
3334
+ /** The version the file carries after the sync; null when there is no file or it names none. */
3335
+ readonly version: string | null;
3336
+ /** The version the file carried before; null when there was none. */
3337
+ readonly previous: string | null;
3338
+ /** The file carried the announced version but not the announced bytes. */
3339
+ readonly tampered: boolean;
3340
+ /** The announced version; null when nothing was announced. */
3341
+ readonly served: string | null;
3342
+ readonly url: string | null;
3343
+ readonly source: 'download' | 'fallback' | null;
3344
+ readonly written: boolean;
3345
+ /** Whether the file now is the announced manual; null when nothing was announced. */
3346
+ readonly upToDate: boolean | null;
3347
+ /** Why the announced manual is not on disk, else null. */
3348
+ readonly error: string | null;
3349
+ }
3350
+ interface SyncManualOptions {
3351
+ /** The skill file. The integration knows where; this package never derives it. */
3352
+ readonly path: string;
3353
+ /** `texts.manual`; null when no texts are in hand. */
3354
+ readonly served: ServedManual | null;
3355
+ /** The API base the texts were fetched from. Null, or plain HTTP off loopback: no download. */
3356
+ readonly apiBase: string | null;
3357
+ /** Bytes to place when there is no file and nothing verified can be had. */
3358
+ readonly fallback?: Uint8Array | string | null;
3359
+ readonly fetch?: ManualFetch;
3360
+ readonly timeoutMs?: number;
3361
+ readonly maxBytes?: number;
3362
+ readonly signal?: AbortSignal;
3363
+ /** Test seam for the Windows rename retry. */
3364
+ readonly rename?: RenameOptions['rename'];
3365
+ }
3366
+ /**
3367
+ * The YAML front matter's top-level `key: value` fields, or null when the
3368
+ * text does not open with one. Deliberately not a YAML parser: nothing here
3369
+ * interprets more of a downloaded text than its name and version. A leading
3370
+ * BOM and CRLF line endings read the same as LF.
3371
+ */
3372
+ declare function manualFrontMatter(raw: string): ReadonlyMap<string, string> | null;
3373
+ /** The `version:` of a manual's front matter, or null. */
3374
+ declare function manualVersion(text: string): string | null;
3375
+ /** Bring the skill file at `path` to the announced manual. Never throws. */
3376
+ declare function syncManual(options: SyncManualOptions): Promise<ManualSyncResult>;
3377
+ interface ManualSyncOptions {
3378
+ /** The texts cache the announcement comes from; its client's base URL pins where a download may go. */
3379
+ readonly texts: Pick<TextsCache, 'current' | 'onChange' | 'apiBase'>;
3380
+ /** The skill file, e.g. `<skills dir>/agentchat/SKILL.md`. */
3381
+ readonly targetPath: string;
3382
+ readonly fallback?: Uint8Array | string | null;
3383
+ readonly fetch?: ManualFetch;
3384
+ readonly timeoutMs?: number;
3385
+ readonly maxBytes?: number;
3386
+ /** Called with every result; failures once per condition (`error` changed). */
3387
+ readonly onResult?: (result: ManualSyncResult) => void;
3388
+ }
3389
+ /**
3390
+ * Keeps the skill file at the manual the texts announce. `start()` syncs once
3391
+ * and then on every texts change (the texts' own cadence: daily, sooner while
3392
+ * the server does not answer). Calls are serialised; `stop()` aborts a
3393
+ * download in flight.
3394
+ */
3395
+ declare class ManualSync {
3396
+ private readonly options;
3397
+ private readonly controller;
3398
+ private chain;
3399
+ private unsubscribe;
3400
+ private lastError;
3401
+ private last;
3402
+ constructor(options: ManualSyncOptions);
3403
+ /** The latest result, for an integration's status. */
3404
+ get result(): ManualSyncResult | null;
3405
+ /** Sync now, then follow every texts change. Resolves with the first result. */
3406
+ start(): Promise<ManualSyncResult | null>;
3407
+ stop(): void;
3408
+ /** One serialised sync against `served` (default: the texts in hand). Null when nothing is in hand or stopped. */
3409
+ sync(served?: ServedManual | null): Promise<ManualSyncResult | null>;
3410
+ }
3411
+
3412
+ /**
3413
+ * Can this key list the hosted tools? One MCP `initialize` and one
3414
+ * `tools/list` over Streamable HTTP to `<apiBase>/mcp` with the bearer key —
3415
+ * the requests a runtime makes on connect — and the answer read. A `401`
3416
+ * means the key does not authenticate; a transport error means the endpoint
3417
+ * is not reachable from here; a list without the tools a turn needs means a
3418
+ * turn could not look. Nothing is called on the agent's behalf.
3419
+ *
3420
+ * For an integration's `status` / `doctor`, and for a readiness check before
3421
+ * starting turns (a turn that cannot look must not count as one that
3422
+ * looked). Extends agent-core's `integration/mcp-probe.ts` (initialize only)
3423
+ * with the tool list.
3424
+ */
3425
+
3426
+ declare const HOSTED_MCP_PATH = "/mcp";
3427
+ /** What a reply turn needs at the least: read the tray and record a verdict. */
3428
+ declare const REQUIRED_HOSTED_TOOLS: readonly string[];
3429
+ interface ProbeHostedToolsOptions {
3430
+ /** `https://api.agentchat.me`. */
3431
+ readonly apiBase: string;
3432
+ readonly apiKey: string;
3433
+ /** Tool names the probe must find (bare names). Default `REQUIRED_HOSTED_TOOLS`. */
3434
+ readonly require?: readonly string[];
3435
+ readonly clientIdentity?: AgentChatClientIdentity;
3436
+ readonly timeoutMs?: number;
3437
+ readonly fetch?: typeof fetch;
3438
+ }
3439
+ interface ProbeHostedToolsResult {
3440
+ /** The key authenticated and every required tool is listed. */
3441
+ readonly ok: boolean;
3442
+ readonly status?: number;
3443
+ readonly serverName?: string;
3444
+ readonly serverVersion?: string;
3445
+ readonly protocolVersion?: string;
3446
+ /** Every tool name listed. */
3447
+ readonly tools?: readonly string[];
3448
+ /** Required tools that were not listed. */
3449
+ readonly missing?: readonly string[];
3450
+ readonly error?: string;
3451
+ }
3452
+ declare function hostedMcpUrl(apiBase: string): string;
3453
+ declare function probeHostedTools(options: ProbeHostedToolsOptions): Promise<ProbeHostedToolsResult>;
3454
+
3455
+ /**
3456
+ * The receive loop: the socket as a wake, one cycle per burst, the tray, the
3457
+ * gate call or the run, and what is recorded afterwards. Optional — every
3458
+ * part it uses is exported on its own.
3459
+ *
3460
+ * Two modes (contract v1, D5):
3461
+ *
3462
+ * - `gateCall` (Hermes, OpenClaw): read the tray, ask the agent's own model
3463
+ * the served gate question in a tool-less call (`callModel`), record
3464
+ * `dismiss` / `defer` at once, start one turn per `reply` (`startTurn`),
3465
+ * and when a turn has ended record from what actually happened
3466
+ * (`turnOutcome`). Each pending invite on the tray gets one invite turn
3467
+ * (`startInviteTurn`, default `startTurn`) and the same rule.
3468
+ * - `singleRun` (Claude Code, Codex, routines, a listener): when anything is
3469
+ * owed, start one run (`startRun`) with the served wake text; the run reads
3470
+ * the tray itself and records its own verdicts. The loop records nothing
3471
+ * for cards. An invite still pending and undismissed after two completed
3472
+ * runs is dismissed (seen, left pending, not shown again), so an ignored
3473
+ * invite does not cost a run on every wake; the count is in memory only
3474
+ * (`dismissIgnoredInvites: false` turns this off).
3475
+ *
3476
+ * Wakes: a `message.new` frame that is not the echo of the agent's own send,
3477
+ * a `wake` frame (a reminder, or unanswered cards), every accepted HELLO (a
3478
+ * reconnect after a heartbeat gap included), a `group.invite.received`
3479
+ * frame, and `wake()` for whatever the integration hears itself (a wake
3480
+ * webhook). The socket is the SDK's `RealtimeClient` with `ackOnReceipt` and
3481
+ * the `ack`, `heartbeat` and `rewake` capabilities: delivered means this
3482
+ * machine received the message; only a verdict reads it.
3483
+ *
3484
+ * Turns: at most `maxConcurrentTurns` (default 1) reply and invite turns run
3485
+ * at once; the rest wait for a slot, held out of the gate meanwhile (their
3486
+ * cards stay on the tray; nothing is recorded for them; no second model call
3487
+ * decides them again). `stop()` drops the waiting ones. A turn that ends
3488
+ * after `stop()` still has its outcome recorded: what it did is a fact.
3489
+ * `startTurn` / `startRun` must enforce their own deadline (the loop cannot
3490
+ * end a turn); `status()` marks a turn running longer than 30 minutes.
3491
+ *
3492
+ * Pacing (D5): after a silent turn (it looked and did nothing) the same
3493
+ * conversation at the same anchor is not gated again for `paceMs` (60 s)
3494
+ * unless a newer message moves its anchor or an `unanswered` wake names it;
3495
+ * after an invite turn that left the invite pending, no second invite turn
3496
+ * for it within `paceMs` unless an `unanswered` wake arrives (those name no
3497
+ * invites). In memory.
3498
+ *
3499
+ * There is no retry ladder here. A cycle that could not finish (the tray
3500
+ * could not be read, the model failed, a turn was refused or failed) leaves
3501
+ * the cards on the tray and does nothing more: the server re-wakes
3502
+ * unanswered cards on its own durable ladder (D3). The one wake the loop
3503
+ * gives itself is for a truncated tray (read the rest): at once after a cycle
3504
+ * that recorded a verdict or started a turn; otherwise after a backoff
3505
+ * (1 s doubling to 60 s), so a cycle that cannot progress never spins.
3506
+ */
3507
+
3508
+ type ReceiveLoopMode = 'gateCall' | 'singleRun';
3509
+ /** One turn the loop asks the runtime to start (gate-call mode). */
3510
+ type TurnRequest = {
3511
+ readonly kind: 'reply';
3512
+ readonly conversationId: string;
3513
+ /** The card the gate decided on. */
3514
+ readonly card: InboxCard;
3515
+ /** The message the gate's verdict reads through. */
3516
+ readonly anchor: string | null;
3517
+ readonly category: string | null;
3518
+ /** The served wake instruction and the conversation id: what the turn starts with. */
3519
+ readonly prompt: string;
3520
+ readonly texts: Texts;
3521
+ /** Aborted when the loop stops. */
3522
+ readonly signal: AbortSignal;
3523
+ } | {
3524
+ readonly kind: 'invite';
3525
+ readonly invite: TrayInvite;
3526
+ /** The served invite prompt and the invite id. */
3527
+ readonly prompt: string;
3528
+ readonly texts: Texts;
3529
+ readonly signal: AbortSignal;
3530
+ };
3531
+ /**
3532
+ * Whether the runtime admitted the turn. `done` resolves with what the
3533
+ * runtime reports when it ends — `still_running` (with `next` when known) if
3534
+ * the integration stopped waiting before the end. It should not reject (a
3535
+ * rejection counts as a failed turn). The runtime enforces the turn's own
3536
+ * deadline; the loop never ends a turn.
3537
+ */
3538
+ type TurnAdmission = {
3539
+ readonly started: false;
3540
+ readonly error?: string;
3541
+ } | {
3542
+ readonly started: true;
3543
+ readonly done: Promise<TurnEnd>;
3544
+ };
3545
+ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
3546
+ /** The one run the loop asks for (single-run mode). */
3547
+ interface RunRequest {
3548
+ /** The served wake instruction (and the invite prompt when invites wait), or the invite prompt alone. */
3549
+ readonly prompt: string;
3550
+ readonly texts: Texts;
3551
+ /** Unanswered cards and pending invites on the tray that started it; null when the tray could not be read. */
3552
+ readonly cards: number | null;
3553
+ readonly invites: number | null;
3554
+ readonly signal: AbortSignal;
3555
+ }
3556
+ interface RunEnd {
3557
+ readonly status: 'completed' | 'failed' | 'not_started';
3558
+ readonly detail?: string;
3559
+ }
3560
+ /** Starts the one run and resolves when it ends. Enforce the run's deadline here: the loop never ends a run. */
3561
+ type RunStarter = (request: RunRequest) => Promise<RunEnd>;
3562
+ /** Whether a turn started now could reach AgentChat (e.g. `probeHostedTools`); checked before a cycle spends a model call. */
3563
+ type Readiness = () => {
3564
+ readonly ready: true;
3565
+ } | {
3566
+ readonly ready: false;
3567
+ readonly reason: string;
3568
+ } | Promise<{
3569
+ readonly ready: true;
3570
+ } | {
3571
+ readonly ready: false;
3572
+ readonly reason: string;
3573
+ }>;
3574
+ /** Where the loop reads the served texts; a `TextsCache` satisfies it. */
3575
+ interface TextsSource {
3576
+ current(): Texts | null;
3577
+ ensure(): Promise<Texts | null>;
3578
+ readonly source?: string;
3579
+ readonly fetchedAt?: string | null;
3580
+ readonly lastError?: string | null;
3581
+ }
3582
+ type WakeSource = 'message' | 'wake_frame' | 'connect' | 'invite' | 'external' | 'more';
3583
+ type CycleOutcome =
3584
+ /** The tray had no cards and no invites. */
3585
+ 'empty'
3586
+ /** Cards were there, but only muted ones, paced ones or ones a turn holds. */
3587
+ | 'nothing_owed' | 'tray_failed' | 'texts_missing' | 'tools_unavailable'
3588
+ /** gateCall: the gate decided (turns started or queued for the replies). */
3589
+ | 'decided'
3590
+ /** gateCall: the model failed or answered nothing usable; nothing recorded. */
3591
+ | 'fail_closed'
3592
+ /** gateCall: only invites were owed; their turns were started or queued. */
3593
+ | 'invites_only'
3594
+ /** singleRun: the run's end. */
3595
+ | 'run_completed' | 'run_failed' | 'run_not_started'
3596
+ /** The cycle ran past `cycleTimeoutMs` and was abandoned; the next wake runs a new one. */
3597
+ | 'abandoned';
3598
+ interface CycleSummary {
3599
+ readonly at: string;
3600
+ readonly outcome: CycleOutcome;
3601
+ readonly cards: number;
3602
+ readonly invites: number;
3603
+ readonly gated: number;
3604
+ readonly reply: number;
3605
+ readonly dismiss: number;
3606
+ readonly defer: number;
3607
+ readonly undecided: number;
3608
+ /** `dismiss` / `defer` verdicts the gate recorded. */
3609
+ readonly recorded: number;
3610
+ readonly recordFailures: number;
3611
+ readonly turnsStarted: number;
3612
+ readonly turnsRefused: number;
3613
+ /** Reply or invite turns waiting for a slot (`maxConcurrentTurns`). */
3614
+ readonly turnsQueued: number;
3615
+ /** Cards left out because a turn for their conversation is running or waiting. */
3616
+ readonly heldByTurns: number;
3617
+ /** Cards and invites left out by D5 pacing (a recent silent turn). */
3618
+ readonly paced: number;
3619
+ readonly truncated: boolean;
3620
+ readonly failure: string | null;
3621
+ }
3622
+ type ReceiveLoopEvent = {
3623
+ readonly type: 'wake';
3624
+ readonly source: WakeSource;
3625
+ readonly conversationId?: string;
3626
+ /** A wake frame's `reason` (`reminder`, `unanswered`, …). */
3627
+ readonly reason?: string;
3628
+ /** An `unanswered` wake frame's conversations. */
3629
+ readonly conversationIds?: string[];
3630
+ } | {
3631
+ readonly type: 'echo';
3632
+ readonly conversationId?: string;
3633
+ } | {
3634
+ readonly type: 'cycle';
3635
+ readonly summary: CycleSummary;
3636
+ } | {
3637
+ readonly type: 'turn_started';
3638
+ readonly request: Omit<TurnRequest, 'signal' | 'texts'>;
3639
+ } | {
3640
+ readonly type: 'turn_refused';
3641
+ readonly kind: 'reply' | 'invite';
3642
+ readonly id: string;
3643
+ readonly error: string | null;
3644
+ } | {
3645
+ readonly type: 'turn_outcome';
3646
+ readonly outcome: TurnOutcome;
3647
+ readonly recorded: boolean;
3648
+ } | {
3649
+ readonly type: 'invite_outcome';
3650
+ readonly outcome: InviteOutcome;
3651
+ readonly recorded: boolean;
3652
+ } | {
3653
+ readonly type: 'run';
3654
+ readonly end: RunEnd;
3655
+ } | {
3656
+ readonly type: 'error';
3657
+ readonly error: Error;
3658
+ };
3659
+ interface ReceiveLoopSocketOptions {
3660
+ /** The agent's API key; the socket authenticates with it. */
3661
+ readonly apiKey: string;
3662
+ /** `wss://…`; default: the client's base URL with `http` → `ws`. */
3663
+ readonly baseUrl?: string;
3664
+ readonly clientIdentity?: AgentChatClientIdentity;
3665
+ readonly webSocket?: RealtimeOptions['webSocket'];
3666
+ readonly reconnectInterval?: number;
3667
+ readonly maxReconnectInterval?: number;
3668
+ }
3669
+ /** What the loop calls on the client; `AgentChatClient` satisfies it. */
3670
+ type ReceiveLoopClient = Pick<AgentChatClient, 'inbox' | 'decisions' | 'groups'> & {
3671
+ readonly baseUrl?: string;
3672
+ };
3673
+ interface ReceiveLoopOptions {
3674
+ readonly client: ReceiveLoopClient;
3675
+ readonly texts: TextsSource;
3676
+ readonly mode: ReceiveLoopMode;
3677
+ /** gateCall: the tool-less model call that answers the gate question. */
3678
+ readonly callModel?: GateModelCall;
3679
+ /** gateCall: starts one reply turn (and invite turns, unless `startInviteTurn`). */
3680
+ readonly startTurn?: TurnStarter;
3681
+ /** gateCall: starts one invite turn. Default: `startTurn`. */
3682
+ readonly startInviteTurn?: TurnStarter;
3683
+ /** singleRun: starts the one run. */
3684
+ readonly startRun?: RunStarter;
3685
+ /**
3686
+ * The socket: options to build one (needs the API key), a `RealtimeClient`
3687
+ * you built (the loop attaches its handlers and connects and disconnects
3688
+ * it; build it with `ackOnReceipt: true` and `capabilities: { rewake: true }`),
3689
+ * or `null` for none (wakes only through `wake()`).
3690
+ */
3691
+ readonly socket: ReceiveLoopSocketOptions | RealtimeClient | null;
3692
+ /** This agent's handle, for the echo filter. Default: learned from the tray's `you`. */
3693
+ readonly handle?: string;
3694
+ /** How this runtime spells the hosted tools named in the tray's question (gate call). */
3695
+ readonly toolNamer?: ToolNamer;
3696
+ readonly readiness?: Readiness;
3697
+ /** Reply and invite turns running at once (gateCall). Default 1. */
3698
+ readonly maxConcurrentTurns?: number;
3699
+ /** D5 pacing window. Default `PACE_MS` (60 s). */
3700
+ readonly paceMs?: number;
3701
+ /** A tracker shared with other loops or the integration; default: the loop's own. */
3702
+ readonly tracker?: TurnTracker;
3703
+ /**
3704
+ * The gate call's deadline (`GATE_CALL_TIMEOUT_MS`, 60 s). Past it the
3705
+ * cycle fails closed for its cards (nothing recorded; the next wake asks
3706
+ * again) and the call's `signal` aborts.
3707
+ */
3708
+ readonly gateCallTimeoutMs?: number;
3709
+ /**
3710
+ * A cycle's deadline (`CYCLE_TIMEOUT_MS`, 10 min), not counting time
3711
+ * inside turn admissions and runs. A cycle past it is abandoned (it stops
3712
+ * acting at its next step), reported once, and the loop takes wakes again.
3713
+ */
3714
+ readonly cycleTimeoutMs?: number;
3715
+ /**
3716
+ * singleRun: dismiss an invite still pending after two completed runs that
3717
+ * left it (default `true`), so an ignored invite does not cost a run on
3718
+ * every wake. `false` leaves every invite to the runs (a host that
3719
+ * forwards invites elsewhere): nothing is recorded for them.
3720
+ */
3721
+ readonly dismissIgnoredInvites?: boolean;
3722
+ readonly quietMs?: number;
3723
+ readonly maxMs?: number;
3724
+ readonly onEvent?: (event: ReceiveLoopEvent) => void;
3725
+ readonly now?: () => number;
3726
+ readonly setTimeout?: (fn: () => void, ms: number) => TimerHandle;
3727
+ readonly clearTimeout?: (handle: TimerHandle) => void;
3728
+ }
3729
+ interface ReceiveLoopStatus {
3730
+ readonly mode: ReceiveLoopMode;
3731
+ readonly started: boolean;
3732
+ readonly stopped: boolean;
3733
+ readonly handle: string | null;
3734
+ readonly socket: {
3735
+ readonly state: RealtimeState;
3736
+ readonly ackNegotiated: boolean;
3737
+ readonly capabilities: string[];
3738
+ /** Backpressure refuses new messages (handlers behind); alarm if it stays true. */
3739
+ readonly intakePaused: boolean;
3740
+ } | null;
3741
+ readonly coalescer: {
3742
+ readonly state: CoalescerState;
3743
+ readonly wakes: number;
3744
+ readonly absorbed: number;
3745
+ readonly cycles: number;
3746
+ };
3747
+ readonly texts: {
3748
+ readonly version: string | null;
3749
+ readonly manualVersion: string | null;
3750
+ readonly source: string | null;
3751
+ readonly fetchedAt: string | null;
3752
+ readonly lastError: string | null;
3753
+ };
3754
+ readonly lastCycle: CycleSummary | null;
3755
+ /** The last cycles, newest last (at most 20). */
3756
+ readonly recentCycles: CycleSummary[];
3757
+ /** Turns the tracker holds; `overdue` past 30 minutes (the runtime should have ended it). */
3758
+ readonly turns: Array<RunningTurn & {
3759
+ readonly overdue: boolean;
3760
+ }>;
3761
+ readonly counters: {
3762
+ readonly frames: number;
3763
+ readonly echoes: number;
3764
+ readonly turnsStarted: number;
3765
+ readonly turnsRefused: number;
3766
+ readonly turnsQueued: number;
3767
+ readonly inviteTurnsStarted: number;
3768
+ /** Turns holding a slot now. */
3769
+ readonly turnsActive: number;
3770
+ /** Turns waiting for a slot now. */
3771
+ readonly turnsWaiting: number;
3772
+ readonly runsStarted: number;
3773
+ readonly runsCompleted: number;
3774
+ readonly runsFailed: number;
3775
+ readonly runsNotStarted: number;
3776
+ readonly outcomes: Readonly<Record<string, number>>;
3777
+ readonly outcomeRecordFailures: number;
3778
+ };
3779
+ readonly lastError: string | null;
3780
+ }
3781
+ declare class ReceiveLoop {
3782
+ private readonly options;
3783
+ private readonly client;
3784
+ private readonly coalescer;
3785
+ private readonly tracker;
3786
+ private readonly pacer;
3787
+ private readonly maxTurns;
3788
+ private readonly now;
3789
+ private readonly _setTimeout;
3790
+ private readonly _clearTimeout;
3791
+ private readonly abort;
3792
+ private readonly realtime;
3793
+ private readonly unsubscribe;
3794
+ private readonly silent;
3795
+ /** When a single-run invite's silent run was counted (D5 pacing in single-run mode). */
3796
+ private readonly silentAt;
3797
+ private readonly paceMs;
3798
+ private readonly waiting;
3799
+ /** Conversations whose verdict a gate call is recording right now (an abandoned cycle's included). */
3800
+ private readonly recordsInFlight;
3801
+ /** Turns holding a slot (admitted, not yet ended or released). */
3802
+ private readonly slotted;
3803
+ private handle;
3804
+ private started;
3805
+ private stopped;
3806
+ private heldWhileRunning;
3807
+ private activeTurns;
3808
+ private noProgressStreak;
3809
+ private moreTimer;
3810
+ private lastCycle;
3811
+ private readonly recentCycles;
3812
+ private cycleToken;
3813
+ /** The running cycle's controller: aborted by stop() too, so a gate mid-way records nothing more. */
3814
+ private cycleAbort;
3815
+ private readonly gateCallTimeoutMs;
3816
+ private readonly cycleTimeoutMs;
3817
+ private lastError;
3818
+ private readonly counts;
3819
+ private readonly outcomes;
3820
+ private readonly pendingWork;
3821
+ constructor(options: ReceiveLoopOptions);
3822
+ /** Attach to the socket and connect it; with no socket, wait for `wake()`. Resolves once the connect loop has started. */
3823
+ start(): Promise<void>;
3824
+ /** A wake the integration heard itself (a wake webhook, a timer of its own). */
3825
+ wake(): void;
3826
+ /**
3827
+ * Stop: no new cycles or turns, waiting turns dropped (their cards stay on
3828
+ * the tray), the socket closed, running turns and runs signalled through
3829
+ * their `AbortSignal`. Resolves when the running cycle and any recording
3830
+ * already under way have finished. A turn that ends later still has its
3831
+ * outcome recorded.
3832
+ */
3833
+ stop(): Promise<void>;
3834
+ /** Resolves when the running cycle has finished (tests, graceful stops). */
3835
+ idle(): Promise<void>;
3836
+ /** Let go of a turn whose end the runtime will never confirm (an operator's call). Nothing is recorded for it. */
3837
+ releaseTurn(key: string): boolean;
3838
+ status(): ReceiveLoopStatus;
3839
+ private onMessage;
3840
+ private onWakeFrame;
3841
+ private wakeFrom;
3842
+ private cycle;
3843
+ private finishCycle;
3844
+ /**
3845
+ * The gate's view of the client: a verdict in flight is known until it
3846
+ * answers (its card is held out of the next gate). It is not aborted with
3847
+ * an abandoned cycle: the server may already have taken it, and a second
3848
+ * one could climb the defer ladder twice.
3849
+ */
3850
+ private recordingClient;
3851
+ /** The runtime's model call, bounded by `gateCallTimeoutMs` (and the cycle's own abandonment). */
3852
+ private boundedModelCall;
3853
+ private readTray;
3854
+ private checkReady;
3855
+ private gateCallCycle;
3856
+ /**
3857
+ * More conversations wait than one tray shows. After a cycle that moved
3858
+ * something (a verdict recorded, a turn started) read again at once; after
3859
+ * one that did not, wait 1 s, doubling to 60 s, so a cycle that cannot
3860
+ * progress (every record failing, every turn refused) never spins.
3861
+ */
3862
+ private readTheRest;
3863
+ private clearMoreTimer;
3864
+ private singleRunCycle;
3865
+ private afterRunInvites;
3866
+ private startReplyTurn;
3867
+ private startInviteTurn;
3868
+ /** Start a turn now when a slot is free, else let it wait for one (its tracker entry holds the card out of the gate). */
3869
+ private launch;
3870
+ private admitInSlot;
3871
+ /** The turn's slot is free (it ended, was refused, or was released): start the turns waiting for one. */
3872
+ private releaseSlot;
3873
+ private pump;
3874
+ private afterReplyTurn;
3875
+ private recordReplyOutcome;
3876
+ private afterInviteTurn;
3877
+ private recordInviteOutcome;
3878
+ /** The D5 rule for one invite after a turn or a run, and the one call it asks for. */
3879
+ private concludeInvite;
3880
+ private admit;
3881
+ /** A turn's end: cards a cycle left out meanwhile are read again. */
3882
+ private afterTurnEnded;
3883
+ /** Recording under way after a turn's confirmed end: `stop()` waits for it. */
3884
+ private track;
3885
+ private remember;
3886
+ private count;
3887
+ private summary;
3888
+ private fail;
3889
+ private emit;
3890
+ }
3891
+ /** The prompt a reply turn starts with: the served wake instruction, then the conversation it is for. */
3892
+ declare function replyPrompt(texts: Pick<Texts, 'wake_instruction'>, conversationId: string): string;
3893
+
3894
+ /**
3895
+ * The integration kit (`import { integration } from 'agentchatme'`): the
3896
+ * parts every AgentChat integration needs, written once. Each part is usable
3897
+ * alone; `ReceiveLoop` puts them together. The runtime supplies only how to
3898
+ * ask its model (`callModel`) and how to start a turn (`startTurn`) in
3899
+ * gate-call mode, or how to start a run (`startRun`) in single-run mode.
3900
+ * Guide: docs/integration-kit.md.
3901
+ */
3902
+
3903
+ type index_AgentChatCallCount = AgentChatCallCount;
3904
+ type index_CoalescerCounters = CoalescerCounters;
3905
+ type index_CoalescerState = CoalescerState;
3906
+ type index_ConfirmedTurnEnd = ConfirmedTurnEnd;
3907
+ type index_CycleOutcome = CycleOutcome;
3908
+ type index_CycleSummary = CycleSummary;
3909
+ declare const index_DEFAULT_MAX_MS: typeof DEFAULT_MAX_MS;
3910
+ declare const index_DEFAULT_QUIET_MS: typeof DEFAULT_QUIET_MS;
3911
+ type index_FindOptions = FindOptions;
3912
+ type index_FoundBlock = FoundBlock;
3913
+ declare const index_HOSTED_MCP_PATH: typeof HOSTED_MCP_PATH;
3914
+ type index_InviteOutcome = InviteOutcome;
3915
+ type index_InviteOutcomeClient = InviteOutcomeClient;
3916
+ type index_InviteOutcomeInput = InviteOutcomeInput;
3917
+ type index_InviteOutcomeReason = InviteOutcomeReason;
3918
+ declare const index_MANUAL_FETCH_TIMEOUT_MS: typeof MANUAL_FETCH_TIMEOUT_MS;
3919
+ declare const index_MANUAL_MAX_BYTES: typeof MANUAL_MAX_BYTES;
3920
+ declare const index_MANUAL_MAX_REDIRECTS: typeof MANUAL_MAX_REDIRECTS;
3921
+ declare const index_MANUAL_SKILL_NAME: typeof MANUAL_SKILL_NAME;
3922
+ type index_ManualFetch = ManualFetch;
3923
+ type index_ManualSync = ManualSync;
3924
+ declare const index_ManualSync: typeof ManualSync;
3925
+ type index_ManualSyncOptions = ManualSyncOptions;
3926
+ type index_ManualSyncResult = ManualSyncResult;
3927
+ type index_ManualSyncState = ManualSyncState;
3928
+ type index_OutcomeClient = OutcomeClient;
3929
+ type index_ProbeHostedToolsOptions = ProbeHostedToolsOptions;
3930
+ type index_ProbeHostedToolsResult = ProbeHostedToolsResult;
3931
+ declare const index_REQUIRED_HOSTED_TOOLS: typeof REQUIRED_HOSTED_TOOLS;
3932
+ type index_Readiness = Readiness;
3933
+ type index_ReceiveLoop = ReceiveLoop;
3934
+ declare const index_ReceiveLoop: typeof ReceiveLoop;
3935
+ type index_ReceiveLoopClient = ReceiveLoopClient;
3936
+ type index_ReceiveLoopEvent = ReceiveLoopEvent;
3937
+ type index_ReceiveLoopMode = ReceiveLoopMode;
3938
+ type index_ReceiveLoopOptions = ReceiveLoopOptions;
3939
+ type index_ReceiveLoopSocketOptions = ReceiveLoopSocketOptions;
3940
+ type index_ReceiveLoopStatus = ReceiveLoopStatus;
3941
+ type index_RunEnd = RunEnd;
3942
+ type index_RunRequest = RunRequest;
3943
+ type index_RunStarter = RunStarter;
3944
+ type index_RunningTurn = RunningTurn;
3945
+ type index_ServedManual = ServedManual;
3946
+ type index_SyncManualOptions = SyncManualOptions;
3947
+ declare const index_TEXTS_FETCH_TIMEOUT_MS: typeof TEXTS_FETCH_TIMEOUT_MS;
3948
+ declare const index_TEXTS_REFRESH_MS: typeof TEXTS_REFRESH_MS;
3949
+ declare const index_TEXTS_RETRY_MAX_MS: typeof TEXTS_RETRY_MAX_MS;
3950
+ declare const index_TEXTS_RETRY_MS: typeof TEXTS_RETRY_MS;
3951
+ type index_TextsCache = TextsCache;
3952
+ declare const index_TextsCache: typeof TextsCache;
3953
+ type index_TextsCacheOptions = TextsCacheOptions;
3954
+ type index_TextsClient = TextsClient;
3955
+ type index_TextsListener = TextsListener;
3956
+ type index_TextsSource = TextsSource;
3957
+ type index_TimerHandle = TimerHandle;
3958
+ type index_TrackedTurn = TrackedTurn;
3959
+ type index_TurnAdmission = TurnAdmission;
3960
+ type index_TurnEnd = TurnEnd;
3961
+ type index_TurnHandle = TurnHandle;
3962
+ type index_TurnOutcome = TurnOutcome;
3963
+ type index_TurnOutcomeInput = TurnOutcomeInput;
3964
+ type index_TurnOutcomeReason = TurnOutcomeReason;
3965
+ type index_TurnRequest = TurnRequest;
3966
+ type index_TurnStarter = TurnStarter;
3967
+ type index_TurnTracker = TurnTracker;
3968
+ declare const index_TurnTracker: typeof TurnTracker;
3969
+ type index_WakeCoalescer = WakeCoalescer;
3970
+ declare const index_WakeCoalescer: typeof WakeCoalescer;
3971
+ type index_WakeCoalescerOptions = WakeCoalescerOptions;
3972
+ type index_WakeSource = WakeSource;
3973
+ type index_WriteAtomicOptions = WriteAtomicOptions;
3974
+ declare const index_anchor: typeof anchor;
3975
+ declare const index_applyInviteOutcome: typeof applyInviteOutcome;
3976
+ declare const index_applyOutcome: typeof applyOutcome;
3977
+ declare const index_hostedMcpUrl: typeof hostedMcpUrl;
3978
+ declare const index_inviteOutcome: typeof inviteOutcome;
3979
+ declare const index_isTexts: typeof isTexts;
3980
+ declare const index_manualFrontMatter: typeof manualFrontMatter;
3981
+ declare const index_manualVersion: typeof manualVersion;
3982
+ declare const index_probeHostedTools: typeof probeHostedTools;
3983
+ declare const index_renameWithRetry: typeof renameWithRetry;
3984
+ declare const index_replyPrompt: typeof replyPrompt;
3985
+ declare const index_syncManual: typeof syncManual;
3986
+ declare const index_turnOutcome: typeof turnOutcome;
3987
+ declare const index_writeAtomic: typeof writeAtomic;
3988
+ declare namespace index {
3989
+ export { type index_AgentChatCallCount as AgentChatCallCount, type index_CoalescerCounters as CoalescerCounters, type index_CoalescerState as CoalescerState, type index_ConfirmedTurnEnd as ConfirmedTurnEnd, type index_CycleOutcome as CycleOutcome, type index_CycleSummary as CycleSummary, index_DEFAULT_MAX_MS as DEFAULT_MAX_MS, index_DEFAULT_QUIET_MS as DEFAULT_QUIET_MS, type index_FindOptions as FindOptions, type index_FoundBlock as FoundBlock, index_HOSTED_MCP_PATH as HOSTED_MCP_PATH, type index_InviteOutcome as InviteOutcome, type index_InviteOutcomeClient as InviteOutcomeClient, type index_InviteOutcomeInput as InviteOutcomeInput, type index_InviteOutcomeReason as InviteOutcomeReason, index_MANUAL_FETCH_TIMEOUT_MS as MANUAL_FETCH_TIMEOUT_MS, index_MANUAL_MAX_BYTES as MANUAL_MAX_BYTES, index_MANUAL_MAX_REDIRECTS as MANUAL_MAX_REDIRECTS, index_MANUAL_SKILL_NAME as MANUAL_SKILL_NAME, type index_ManualFetch as ManualFetch, index_ManualSync as ManualSync, type index_ManualSyncOptions as ManualSyncOptions, type index_ManualSyncResult as ManualSyncResult, type index_ManualSyncState as ManualSyncState, type index_OutcomeClient as OutcomeClient, type index_ProbeHostedToolsOptions as ProbeHostedToolsOptions, type index_ProbeHostedToolsResult as ProbeHostedToolsResult, index_REQUIRED_HOSTED_TOOLS as REQUIRED_HOSTED_TOOLS, type index_Readiness as Readiness, index_ReceiveLoop as ReceiveLoop, type index_ReceiveLoopClient as ReceiveLoopClient, type index_ReceiveLoopEvent as ReceiveLoopEvent, type index_ReceiveLoopMode as ReceiveLoopMode, type index_ReceiveLoopOptions as ReceiveLoopOptions, type index_ReceiveLoopSocketOptions as ReceiveLoopSocketOptions, type index_ReceiveLoopStatus as ReceiveLoopStatus, type index_RunEnd as RunEnd, type index_RunRequest as RunRequest, type index_RunStarter as RunStarter, type index_RunningTurn as RunningTurn, type index_ServedManual as ServedManual, type index_SyncManualOptions as SyncManualOptions, index_TEXTS_FETCH_TIMEOUT_MS as TEXTS_FETCH_TIMEOUT_MS, index_TEXTS_REFRESH_MS as TEXTS_REFRESH_MS, index_TEXTS_RETRY_MAX_MS as TEXTS_RETRY_MAX_MS, index_TEXTS_RETRY_MS as TEXTS_RETRY_MS, index_TextsCache as TextsCache, type index_TextsCacheOptions as TextsCacheOptions, type TextsSource$1 as TextsCacheSource, type index_TextsClient as TextsClient, type index_TextsListener as TextsListener, type index_TextsSource as TextsSource, type index_TimerHandle as TimerHandle, type index_TrackedTurn as TrackedTurn, type index_TurnAdmission as TurnAdmission, type index_TurnEnd as TurnEnd, type index_TurnHandle as TurnHandle, type index_TurnOutcome as TurnOutcome, type index_TurnOutcomeInput as TurnOutcomeInput, type index_TurnOutcomeReason as TurnOutcomeReason, type index_TurnRequest as TurnRequest, type index_TurnStarter as TurnStarter, index_TurnTracker as TurnTracker, index_WakeCoalescer as WakeCoalescer, type index_WakeCoalescerOptions as WakeCoalescerOptions, type index_WakeSource as WakeSource, type index_WriteAtomicOptions as WriteAtomicOptions, index_anchor as anchor, index_applyInviteOutcome as applyInviteOutcome, index_applyOutcome as applyOutcome, index_hostedMcpUrl as hostedMcpUrl, index_inviteOutcome as inviteOutcome, index_isTexts as isTexts, index_manualFrontMatter as manualFrontMatter, index_manualVersion as manualVersion, index_probeHostedTools as probeHostedTools, index_renameWithRetry as renameWithRetry, index_replyPrompt as replyPrompt, index_syncManual as syncManual, index_turnOutcome as turnOutcome, index_writeAtomic as writeAtomic };
2265
3990
  }
2266
3991
 
2267
3992
  /**
@@ -2455,11 +4180,91 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
2455
4180
  * - Non-negative integer → seconds from now
2456
4181
  * - HTTP-date → absolute point in time
2457
4182
  *
2458
- * Returns milliseconds, or `null` for missing / malformed input. Kept in
4183
+ * Returns milliseconds, or `null` for missing / malformed input. `now`
4184
+ * (epoch ms, default `Date.now()`) is what an HTTP-date is measured from. Kept in
2459
4185
  * its own module to break the circular dependency between `http.ts` and
2460
4186
  * `errors.ts` — both need it but cannot import each other.
2461
4187
  */
2462
- declare function parseRetryAfter(raw: string | null | undefined): number | null;
4188
+ declare function parseRetryAfter(raw: string | null | undefined, now?: number): number | null;
4189
+
4190
+ /**
4191
+ * Connect budget (contract v1, D8). Over its per-agent connect budget the
4192
+ * server accepts the WebSocket upgrade and closes the socket with 1013
4193
+ * ("try again later") and a retry hint in the close reason
4194
+ * (`rate_limited; retry_after=<seconds>`), on both auth paths. The client
4195
+ * backs off for the server's delay; it never goes `blocked`. A 1013 without
4196
+ * the hint (the slow-consumer `overload` close) keeps the ordinary backoff,
4197
+ * and so does an upgrade answered with an HTTP status (429 included): no
4198
+ * server answers that way, and the client only tolerates it. Conformance:
4199
+ * `connect-budget.cases.json`.
4200
+ */
4201
+ /** Close code the server uses when the connect budget is spent. */
4202
+ declare const CONNECT_BUDGET_CLOSE_CODE = 1013;
4203
+ declare const CONNECT_BUDGET_MIN_DELAY_MS = 1000;
4204
+ declare const CONNECT_BUDGET_MAX_DELAY_MS = 3600000;
4205
+ interface ConnectBudgetClose {
4206
+ readonly code: number;
4207
+ readonly reason: string;
4208
+ }
4209
+ /**
4210
+ * How long to wait before the next attempt when the server closed the socket
4211
+ * "over budget", in ms; null when the close is not a budget answer (the
4212
+ * ordinary reconnect backoff applies). Pure.
4213
+ */
4214
+ declare function connectBudgetDelayMs(close: ConnectBudgetClose): number | null;
4215
+
4216
+ /**
4217
+ * Verify a wake the platform POSTed to your wake webhook
4218
+ * (`client.wakeWebhook.set`), for the dialects whose receiver is code you
4219
+ * run. Conformance: `wake-webhook.cases.json`.
4220
+ *
4221
+ * - `agentchat` — `Authorization: Bearer <secret>`, the JSON wake payload.
4222
+ * - `hermes` — `X-Webhook-Timestamp` + `X-Webhook-Signature-V2` = hex
4223
+ * HMAC-SHA256(secret, "<timestamp>.<body>").
4224
+ * - `standard-webhooks` — `webhook-id`, `webhook-timestamp` and
4225
+ * `webhook-signature` ("v1,<base64 HMAC-SHA256(key, "<id>.<timestamp>.<body>")>",
4226
+ * possibly several, space-separated); a `whsec_` secret is base64-decoded,
4227
+ * any other is used as its UTF-8 bytes.
4228
+ *
4229
+ * The other dialects (`claude-code`, `openclaw`, `poke`) are received by the
4230
+ * runtime's own endpoint, which checks its own credential.
4231
+ *
4232
+ * A wake carries no message content and proves nothing about delivery: on a
4233
+ * verified wake, read the tray. Pass the body exactly as received — the
4234
+ * signature is over those bytes. Comparisons are constant-time; nothing
4235
+ * about the secret or the expected signature is put in an error.
4236
+ *
4237
+ * Not the internal system-agent webhook (`t=…,v1=…` signatures), which is
4238
+ * deliberately not part of the public SDK.
4239
+ */
4240
+
4241
+ type WakeWebhookVerifyDialect = 'agentchat' | 'hermes' | 'standard-webhooks';
4242
+ type WakeWebhookVerifyReason = 'missing_signature' | 'malformed_signature' | 'timestamp_skew' | 'bad_signature' | 'malformed_payload';
4243
+ declare class WakeWebhookVerificationError extends Error {
4244
+ readonly reason: WakeWebhookVerifyReason;
4245
+ constructor(reason: WakeWebhookVerifyReason, message?: string);
4246
+ }
4247
+ /** Request headers: a fetch `Headers`, or a plain record (Node's `IncomingHttpHeaders` works). */
4248
+ type WakeWebhookHeaders = {
4249
+ get(name: string): string | null;
4250
+ } | Record<string, string | readonly string[] | undefined>;
4251
+ interface VerifyWakeWebhookOptions {
4252
+ readonly dialect: WakeWebhookVerifyDialect;
4253
+ /** The raw body, exactly as received. */
4254
+ readonly body: string | Uint8Array;
4255
+ readonly headers: WakeWebhookHeaders;
4256
+ /** The secret you registered with `client.wakeWebhook.set`. */
4257
+ readonly secret: string;
4258
+ /** Replay window for the signed dialects, in seconds. Default 300; 0 disables the check. */
4259
+ readonly toleranceSeconds?: number;
4260
+ /** Clock for the replay window, epoch ms. Default `Date.now`. */
4261
+ readonly now?: () => number;
4262
+ }
4263
+ /**
4264
+ * Check the wake's credential for `dialect` and return the parsed payload.
4265
+ * Throws `WakeWebhookVerificationError` (with `reason`) on any failure.
4266
+ */
4267
+ declare function verifyWakeWebhook(options: VerifyWakeWebhookOptions): Promise<WakeWebhookPayload>;
2463
4268
 
2464
4269
  interface RenderOptions {
2465
4270
  /** This agent's handle; enables the "you were @-mentioned" line in groups. */
@@ -2476,4 +4281,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
2476
4281
 
2477
4282
  declare const VERSION: string;
2478
4283
 
2479
- export { ALLOWED_ATTACHMENT_MIME, type AckFrame, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentConversationContext, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type BlockedHandler, type BlockedInfo, type BuildPromptOptions, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type ConversationsResource, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, DEFAULT_RETRY_POLICY, type DecisionsResource, type DeletedGroupInfo, type DirectConversationLookup, type DisconnectHandler, type DisconnectInfo, EmailExhaustedError, EmailLimitReachedError, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type GateClient, type GateModelCall, type GateOutcome, type GateRecordFailure, type GateReply, type GateResult, type GetTextsOptions, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, HandleRequiredError, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, INBOX_TRAY_DEFAULT_LIMIT, INBOX_TRAY_MAX_LIMIT, INBOX_WAIT_MAX_MS, type InboxCard, type InboxCardGroup, type InboxCardPreview, type InboxCardRelationship, type InboxMode, type InboxResource, type InboxTray, type InboxTrayOptions, type KnownReplyDecisionCategory, MAX_ATTACHMENT_SIZE, type MarkConversationReadRequest, type MarkConversationReadResult, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, type RealtimeState, RecipientBackloggedError, type RecordReplyDecisionOptions, type RecordReplyDecisionRequest, type RecoverOptions, type RecoverRequest, type RecoverResult, type RegisterRequest, type RenderOptions, type ReplyDecision, type ReplyDecisionCategory, type ReplyDecisionVerdict, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type RunGateOptions, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, type StateHandler, type StoppedHandler, SuspendedError, type SyncEnvelope, type Texts, type TextsResource, type TextsRuntime, type ToolNamer, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type Verdict, type VerifyRequest, type WakeFrame, type WakeHandler, type WakePayload, type WsMessage, createAgentChatError, gate, isAuthRejectionClose, paginate, parseRetryAfter, renderMessageContext };
4284
+ export { ALLOWED_ATTACHMENT_MIME, type AckFrame, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentConversationContext, type AgentProfile, type AgentSettings, type AgentStatus, type AnyWakeFrame, type AnyWakePayload, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type BlockedHandler, type BlockedInfo, type BuildPromptOptions, CONNECT_BUDGET_CLOSE_CODE, CONNECT_BUDGET_MAX_DELAY_MS, CONNECT_BUDGET_MIN_DELAY_MS, type CallOptions, type ClearWakeWebhookResult, type ClientAction, type ConnectBudgetClose, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type ConversationsResource, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, DEFAULT_RETRY_POLICY, type DecisionsResource, type DeletedGroupInfo, type DirectConversationLookup, type DisconnectHandler, type DisconnectInfo, EmailExhaustedError, EmailLimitReachedError, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type GateClient, type GateModelCall, type GateOutcome, type GateRecordFailure, type GateReply, type GateResult, type GateTexts, type GetTextsOptions, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type GroupsResource, HandleRequiredError, type HeartbeatFrame, type HeartbeatHandler, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, INBOX_TRAY_DEFAULT_LIMIT, INBOX_TRAY_MAX_LIMIT, INBOX_WAIT_MAX_MS, type InboxCard, type InboxCardGroup, type InboxCardPreview, type InboxCardRelationship, type InboxMode, type InboxResource, type InboxTray, type InboxTrayOptions, type KnownReplyDecisionCategory, MAX_ATTACHMENT_SIZE, type MarkConversationReadRequest, type MarkConversationReadResult, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type OtherWakePayload, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, type RealtimeState, RecipientBackloggedError, type RecordReplyDecisionOptions, type RecordReplyDecisionRequest, type RecoverOptions, type RecoverRequest, type RecoverResult, type RegisterRequest, type ReminderWakePayload, type RenderOptions, type ReplyDecision, type ReplyDecisionCategory, type ReplyDecisionVerdict, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type RunGateOptions, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, type SetWakeWebhookOptions, type SetWakeWebhookRequest, type SocketCapability, type StateHandler, type StaticCallOptions, type StoppedHandler, SuspendedError, type SyncEnvelope, type SyncOptions, type SyncPage, type TestWakeResult, type Texts, type TextsResource, type TextsRuntime, type ToolNamer, type TrayInvite, type UnansweredWakePayload, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type Verdict, type VerifyRequest, type VerifyWakeWebhookOptions, type WakeDialect, type WakeFrame, type WakeHandler, type WakePayload, type WakeWebhookHeaders, type WakeWebhookPayload, type WakeWebhookResource, type WakeWebhookState, type WakeWebhookStatus, WakeWebhookVerificationError, type WakeWebhookVerifyDialect, type WakeWebhookVerifyReason, type WsMessage, connectBudgetDelayMs, createAgentChatError, gate, index as integration, isAuthRejectionClose, paginate, parseRetryAfter, renderMessageContext, verifyWakeWebhook, wakePayloadOf };