agentchatme 1.2.0 → 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/CHANGELOG.md +203 -2
- package/README.md +28 -9
- package/dist/index.cjs +2889 -110
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1896 -71
- package/dist/index.d.ts +1896 -71
- package/dist/index.js +2882 -111
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
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" (
|
|
412
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1535
|
-
|
|
1536
|
-
|
|
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
|
-
/**
|
|
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
|
|
1745
|
-
*
|
|
1746
|
-
*
|
|
1747
|
-
*
|
|
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,15 +2113,28 @@ 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. */
|
|
1790
2124
|
private blockedAnnounced;
|
|
1791
2125
|
private dedupSeen;
|
|
2126
|
+
private inFlight;
|
|
2127
|
+
private drainAdopted;
|
|
2128
|
+
private generation;
|
|
1792
2129
|
private restDrainOrigin;
|
|
1793
2130
|
private drainSettlements;
|
|
1794
2131
|
private drainInFlight;
|
|
1795
2132
|
private orderStates;
|
|
2133
|
+
private lanes;
|
|
2134
|
+
private queuedJobs;
|
|
2135
|
+
private shedding;
|
|
2136
|
+
private refetchPending;
|
|
2137
|
+
private drainAgain;
|
|
1796
2138
|
private disposed;
|
|
1797
2139
|
constructor(options: RealtimeOptions);
|
|
1798
2140
|
/**
|
|
@@ -1825,17 +2167,26 @@ declare class RealtimeClient {
|
|
|
1825
2167
|
* Correctness rules, in cursor order:
|
|
1826
2168
|
* - A row failing minimal validation stops the drain: the clean prefix
|
|
1827
2169
|
* before it is processed and acked; the cursor never crosses the row.
|
|
2170
|
+
* - A row whose message another copy is still handling on this connection
|
|
2171
|
+
* (the server's reconnect backlog brings the same rows) is not
|
|
2172
|
+
* dispatched again, and the drain never waits for that copy: the cursor
|
|
2173
|
+
* covers the row only if the copy already finished cleanly, otherwise
|
|
2174
|
+
* it stops there and the next drain covers it as a dedup hit.
|
|
1828
2175
|
* - A row whose handler threw is not acked — nor is anything after it
|
|
1829
2176
|
* (the ack cursor is at-or-before) — so the server re-offers it; the
|
|
1830
2177
|
* dedup cache suppresses re-dispatch of its acked predecessors.
|
|
1831
|
-
* - A row
|
|
1832
|
-
*
|
|
1833
|
-
*
|
|
1834
|
-
*
|
|
1835
|
-
*
|
|
2178
|
+
* - A row no handler has been handed yet is not acked: acks FREEZE at the
|
|
2179
|
+
* last settled row for the remainder of the drain. That is a row
|
|
2180
|
+
* parked in the out-of-order buffer (awaiting seq gap-fill), and also a
|
|
2181
|
+
* row that was parked when the socket closed: in the default mode the
|
|
2182
|
+
* close clears the ordering buffers (`resetOrderStates`) without
|
|
2183
|
+
* dispatching them, possibly while the drain is still awaiting an
|
|
2184
|
+
* earlier row's handler. Covering either would mark a message
|
|
2185
|
+
* delivered that no handler saw — acked-but-undispatched is exactly the
|
|
1836
2186
|
* loss the ack protocol exists to prevent. Reading continues so the
|
|
1837
2187
|
* in-session gap-fill still resolves; the frozen tail is re-offered on
|
|
1838
|
-
* the next drain and absorbed by
|
|
2188
|
+
* the next drain (or the server's reconnect backlog) and absorbed by
|
|
2189
|
+
* the dedup cache.
|
|
1839
2190
|
*
|
|
1840
2191
|
* Concurrent calls are coalesced (the second returns immediately). The
|
|
1841
2192
|
* server-side ack pointer only moves forward, so re-running after a
|
|
@@ -1844,7 +2195,6 @@ declare class RealtimeClient {
|
|
|
1844
2195
|
*/
|
|
1845
2196
|
drainOfflineEnvelopes(): Promise<void>;
|
|
1846
2197
|
private runDrain;
|
|
1847
|
-
private isBufferedInOrderState;
|
|
1848
2198
|
/**
|
|
1849
2199
|
* Clear the reconnect backoff once this connection proves itself.
|
|
1850
2200
|
*
|
|
@@ -1879,6 +2229,7 @@ declare class RealtimeClient {
|
|
|
1879
2229
|
* longer `this.ws`.
|
|
1880
2230
|
*/
|
|
1881
2231
|
private abandonSocket;
|
|
2232
|
+
/** `serverDelayMs`: the server said how long to wait (connect budget); it replaces the backoff step. */
|
|
1882
2233
|
private scheduleReconnect;
|
|
1883
2234
|
/**
|
|
1884
2235
|
* The server rejected the credential. `blocked` is not the end: a fresh
|
|
@@ -1902,6 +2253,8 @@ declare class RealtimeClient {
|
|
|
1902
2253
|
private longOutageCap;
|
|
1903
2254
|
/** Symmetric ±ratio jitter around `ms` — for the blocked retry, a range (10–15 min), not a cap. */
|
|
1904
2255
|
private jittered;
|
|
2256
|
+
/** Jitter in [ms, ms × (1 + ratio)]: `ms` is a floor (a server-given delay is never shortened). */
|
|
2257
|
+
private jitteredAbove;
|
|
1905
2258
|
/** Jitter in [ms × (1 − ratio), ms]: `ms` is a ceiling. Thundering-herd-safe across a fleet. */
|
|
1906
2259
|
private jitteredBelow;
|
|
1907
2260
|
private armHandshakeDeadline;
|
|
@@ -1929,6 +2282,7 @@ declare class RealtimeClient {
|
|
|
1929
2282
|
* are released.
|
|
1930
2283
|
*/
|
|
1931
2284
|
on(event: 'wake', handler: WakeHandler): () => void;
|
|
2285
|
+
on(event: 'heartbeat', handler: HeartbeatHandler): () => void;
|
|
1932
2286
|
on(event: 'state', handler: StateHandler): () => void;
|
|
1933
2287
|
on(event: 'blocked', handler: BlockedHandler): () => void;
|
|
1934
2288
|
on(event: 'stopped', handler: StoppedHandler): () => void;
|
|
@@ -1975,6 +2329,18 @@ declare class RealtimeClient {
|
|
|
1975
2329
|
* a legacy server (which marks envelopes delivered on push).
|
|
1976
2330
|
*/
|
|
1977
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>;
|
|
1978
2344
|
/**
|
|
1979
2345
|
* Close the socket, cancel every timer, and release all handlers. The
|
|
1980
2346
|
* only way into `stopped`, and the only way the client ever stops on
|
|
@@ -1996,6 +2362,10 @@ declare class RealtimeClient {
|
|
|
1996
2362
|
* acked. Resolves `false` when any handler threw or rejected: the
|
|
1997
2363
|
* message is NOT acked on any path and the server re-offers it.
|
|
1998
2364
|
*
|
|
2365
|
+
* A copy of a message whose first copy is still with the handlers is not
|
|
2366
|
+
* dispatched again: it resolves with the first copy's outcome (and, when
|
|
2367
|
+
* that succeeded, is acked like a dedup hit).
|
|
2368
|
+
*
|
|
1999
2369
|
* Ack routing: live frames (including server-pushed reconnect backlog
|
|
2000
2370
|
* and gap-fill rows) send a WS `{type:'ack'}` frame when ack-mode was
|
|
2001
2371
|
* negotiated; REST-drain rows are covered by the drain's sync/ack
|
|
@@ -2003,6 +2373,44 @@ declare class RealtimeClient {
|
|
|
2003
2373
|
* that cursor.
|
|
2004
2374
|
*/
|
|
2005
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;
|
|
2006
2414
|
/**
|
|
2007
2415
|
* Best-effort delivery ack for one processed message. No-op unless the
|
|
2008
2416
|
* server negotiated ack-mode on this connection. Send failures are
|
|
@@ -2013,6 +2421,32 @@ declare class RealtimeClient {
|
|
|
2013
2421
|
private sendAckFrame;
|
|
2014
2422
|
private dedupHit;
|
|
2015
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;
|
|
2016
2450
|
private extractMessageId;
|
|
2017
2451
|
private isMessageNew;
|
|
2018
2452
|
private isWake;
|
|
@@ -2044,28 +2478,37 @@ declare class RealtimeClient {
|
|
|
2044
2478
|
*
|
|
2045
2479
|
* Code we keep, brain we don't
|
|
2046
2480
|
* ────────────────────────────
|
|
2047
|
-
* Every word the model reads
|
|
2048
|
-
*
|
|
2049
|
-
*
|
|
2050
|
-
*
|
|
2051
|
-
*
|
|
2052
|
-
*
|
|
2053
|
-
*
|
|
2054
|
-
*
|
|
2055
|
-
*
|
|
2056
|
-
*
|
|
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.
|
|
2057
2496
|
*
|
|
2058
2497
|
* What gets recorded, and when
|
|
2059
2498
|
* ────────────────────────────
|
|
2060
2499
|
* `dismiss` and `defer` are recorded at once, each anchored to the card's
|
|
2061
2500
|
* `preview.message_id` (`last_message_id` when a card has no preview).
|
|
2062
2501
|
* `reply` is NOT recorded by `run`: recording it marks the conversation read
|
|
2063
|
-
* and takes it off the tray
|
|
2064
|
-
*
|
|
2065
|
-
*
|
|
2066
|
-
*
|
|
2067
|
-
*
|
|
2068
|
-
*
|
|
2502
|
+
* and takes it off the tray. Each reply comes back with a `record()` the
|
|
2503
|
+
* host calls at the END of a turn that completed — never before the turn,
|
|
2504
|
+
* never at its start. A completed turn that looked counts as read even
|
|
2505
|
+
* when it chose not to send. A crashed turn, or one that could not look
|
|
2506
|
+
* (the AgentChat tools were not available to it), records nothing: the
|
|
2507
|
+
* conversation stays on the tray and the next wake retries. Recording at
|
|
2508
|
+
* the start would mark the conversation read before the turn's own
|
|
2509
|
+
* `agentchat_inbox` call, which then sees an empty tray and parks for its
|
|
2510
|
+
* wait window; and a crashed turn would leave the peer blocked by the
|
|
2511
|
+
* cold-DM "one message until a reply" rule.
|
|
2069
2512
|
*
|
|
2070
2513
|
* Failure policy
|
|
2071
2514
|
* ──────────────
|
|
@@ -2103,6 +2546,16 @@ declare const BARE_TOOL_NAMER: ToolNamer;
|
|
|
2103
2546
|
* `mcpToolNamer('agentchat')('agentchat_decide')` → `mcp__agentchat__agentchat_decide`.
|
|
2104
2547
|
*/
|
|
2105
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;
|
|
2106
2559
|
/** One parsed answer for one card. Snake-case: it is data, shared with the conformance fixtures. */
|
|
2107
2560
|
interface Verdict {
|
|
2108
2561
|
conversation_id: string;
|
|
@@ -2110,8 +2563,17 @@ interface Verdict {
|
|
|
2110
2563
|
/** A category from the tray's list, or null when the model gave none or an unknown one. */
|
|
2111
2564
|
category: ReplyDecisionCategory | null;
|
|
2112
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'>;
|
|
2113
2568
|
interface BuildPromptOptions {
|
|
2114
|
-
/**
|
|
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. */
|
|
2115
2577
|
toolNamer?: ToolNamer;
|
|
2116
2578
|
}
|
|
2117
2579
|
/**
|
|
@@ -2132,9 +2594,11 @@ declare function anchorOf(card: InboxCard): string | undefined;
|
|
|
2132
2594
|
*/
|
|
2133
2595
|
declare function canonicalJson(value: unknown): string;
|
|
2134
2596
|
/**
|
|
2135
|
-
* Render the gate prompt for one tray:
|
|
2136
|
-
*
|
|
2137
|
-
*
|
|
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).
|
|
2138
2602
|
*
|
|
2139
2603
|
* Throws when the tray carries no question — judging without it is exactly
|
|
2140
2604
|
* the drift this design removes, so the gate fails closed instead.
|
|
@@ -2154,20 +2618,32 @@ declare function parseVerdicts(text: string | null | undefined, tray: InboxTray)
|
|
|
2154
2618
|
declare function normalizeDecision(value: unknown): ReplyDecisionVerdict | null;
|
|
2155
2619
|
/**
|
|
2156
2620
|
* The host's model call. Receives the rendered prompt, returns the model's
|
|
2157
|
-
* raw text.
|
|
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
|
|
2158
2623
|
* question names hosted tools, and a model that could call them would act
|
|
2159
2624
|
* instead of answering (no JSON → fail closed, or a tool call AND JSON →
|
|
2160
2625
|
* a verdict recorded twice).
|
|
2161
2626
|
*/
|
|
2162
|
-
type GateModelCall = (prompt: string
|
|
2627
|
+
type GateModelCall = (prompt: string, options?: {
|
|
2628
|
+
signal?: AbortSignal;
|
|
2629
|
+
}) => Promise<string>;
|
|
2163
2630
|
/** The one client surface the gate needs; `AgentChatClient` satisfies it. */
|
|
2164
2631
|
type GateClient = Pick<AgentChatClient, 'decisions'>;
|
|
2165
2632
|
interface RunGateOptions {
|
|
2166
2633
|
tray: InboxTray;
|
|
2167
2634
|
callModel: GateModelCall;
|
|
2168
2635
|
client: GateClient;
|
|
2636
|
+
/** The served texts (`gate_call_preamble`, `gate_call_answer_format`). Absent: the legacy wording (deprecated). */
|
|
2637
|
+
texts?: GateTexts | null;
|
|
2169
2638
|
/** How this runtime spells the hosted tools named inside the question. */
|
|
2170
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;
|
|
2171
2647
|
}
|
|
2172
2648
|
type GateOutcome =
|
|
2173
2649
|
/** The model answered; dismiss/defer verdicts were recorded, replies await `record()`. */
|
|
@@ -2188,18 +2664,19 @@ interface GateReply {
|
|
|
2188
2664
|
/** The category the model attached, if any. */
|
|
2189
2665
|
category: ReplyDecisionCategory | null;
|
|
2190
2666
|
/**
|
|
2191
|
-
* Record the `reply` verdict. Call it
|
|
2192
|
-
*
|
|
2193
|
-
*
|
|
2194
|
-
*
|
|
2195
|
-
*
|
|
2196
|
-
* call
|
|
2667
|
+
* Record the `reply` verdict. Call it at the END of a turn that completed
|
|
2668
|
+
* — never before the turn, never at its start (the turn's own
|
|
2669
|
+
* `agentchat_inbox` call would then find the conversation already read
|
|
2670
|
+
* and an empty tray). A completed turn that looked counts as read even
|
|
2671
|
+
* when it chose not to send. On a crash, or when the turn could not look,
|
|
2672
|
+
* do not call it: the conversation stays on the tray and the next wake
|
|
2673
|
+
* retries. Idempotent on success; a failed call may be retried.
|
|
2197
2674
|
*/
|
|
2198
2675
|
record(): Promise<ReplyDecision>;
|
|
2199
2676
|
}
|
|
2200
2677
|
interface GateResult {
|
|
2201
2678
|
outcome: GateOutcome;
|
|
2202
|
-
/** Conversations whose verdict is `reply`:
|
|
2679
|
+
/** Conversations whose verdict is `reply`: run a turn for each and call its `record()` once that turn has completed. */
|
|
2203
2680
|
reply: GateReply[];
|
|
2204
2681
|
/** Every usable verdict, in the model's order. */
|
|
2205
2682
|
verdicts: Verdict[];
|
|
@@ -2216,7 +2693,7 @@ interface GateResult {
|
|
|
2216
2693
|
* Decide every card on the tray. `dismiss` and `defer` are recorded here,
|
|
2217
2694
|
* sequentially (a tray holds at most 50 cards), each anchored with
|
|
2218
2695
|
* `anchorOf(card)`; `reply` verdicts come back as `GateReply` entries whose
|
|
2219
|
-
* `record()` the host calls once the turn
|
|
2696
|
+
* `record()` the host calls once the turn has completed. Never throws: model
|
|
2220
2697
|
* and network failures land in the result.
|
|
2221
2698
|
*/
|
|
2222
2699
|
declare function run(options: RunGateOptions): Promise<GateResult>;
|
|
@@ -2229,6 +2706,9 @@ type gate_GateOutcome = GateOutcome;
|
|
|
2229
2706
|
type gate_GateRecordFailure = GateRecordFailure;
|
|
2230
2707
|
type gate_GateReply = GateReply;
|
|
2231
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;
|
|
2232
2712
|
type gate_RunGateOptions = RunGateOptions;
|
|
2233
2713
|
type gate_ToolNamer = ToolNamer;
|
|
2234
2714
|
type gate_Verdict = Verdict;
|
|
@@ -2241,7 +2721,1272 @@ declare const gate_normalizeDecision: typeof normalizeDecision;
|
|
|
2241
2721
|
declare const gate_parseVerdicts: typeof parseVerdicts;
|
|
2242
2722
|
declare const gate_run: typeof run;
|
|
2243
2723
|
declare namespace gate {
|
|
2244
|
-
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 };
|
|
2245
3990
|
}
|
|
2246
3991
|
|
|
2247
3992
|
/**
|
|
@@ -2435,11 +4180,91 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
|
|
|
2435
4180
|
* - Non-negative integer → seconds from now
|
|
2436
4181
|
* - HTTP-date → absolute point in time
|
|
2437
4182
|
*
|
|
2438
|
-
* Returns milliseconds, or `null` for missing / malformed input.
|
|
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
|
|
2439
4185
|
* its own module to break the circular dependency between `http.ts` and
|
|
2440
4186
|
* `errors.ts` — both need it but cannot import each other.
|
|
2441
4187
|
*/
|
|
2442
|
-
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>;
|
|
2443
4268
|
|
|
2444
4269
|
interface RenderOptions {
|
|
2445
4270
|
/** This agent's handle; enables the "you were @-mentioned" line in groups. */
|
|
@@ -2456,4 +4281,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
|
|
|
2456
4281
|
|
|
2457
4282
|
declare const VERSION: string;
|
|
2458
4283
|
|
|
2459
|
-
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 };
|