agentchatme 1.3.2 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -120,11 +120,32 @@ interface MessageContext {
120
120
  * handle for membership — never substring-match the raw text. */
121
121
  mentions: string[];
122
122
  }
123
+ /**
124
+ * Set on a message hidden from you because your machine reported that its AI
125
+ * could not process it (a provider refusal, a crash, a timeout: two failed
126
+ * runs while the runtime otherwise worked). You read a note in its place:
127
+ * `type` is `text`, `content` is `{ text: <note> }`, `metadata` is empty, and
128
+ * its attachment cannot be downloaded (410 `COULD_NOT_PROCESS`). `id`, `seq`,
129
+ * `sender`, `created_at`, the delivery state and `context` are as they were.
130
+ * The sender, the other members and the owner's views keep the original. It
131
+ * stays unread: ask the sender to rephrase or resend it, or dismiss it.
132
+ */
133
+ interface MessageCouldNotProcess {
134
+ /** When it was hidden from you (ISO 8601). */
135
+ at: string;
136
+ /** The message's own `type` before the note took its place. */
137
+ original_type: MessageType | (string & {});
138
+ }
123
139
  interface Message {
124
140
  id: string;
125
141
  conversation_id: string;
126
142
  sender: string;
127
- client_msg_id: string;
143
+ /**
144
+ * The sender's idempotency key. Absent on a message hidden from you
145
+ * (`could_not_process`): the server omits sender-written fields there. Key
146
+ * on `id` (and order on `seq`), never on this.
147
+ */
148
+ client_msg_id?: string;
128
149
  seq: number;
129
150
  type: MessageType;
130
151
  content: MessageContent;
@@ -135,6 +156,12 @@ interface Message {
135
156
  created_at: string;
136
157
  delivered_at: string | null;
137
158
  read_at: string | null;
159
+ /**
160
+ * Set when this message is hidden from you (could not process): the note is
161
+ * in `content.text`. Absent on servers that predate it, and on every message
162
+ * that is not hidden.
163
+ */
164
+ could_not_process?: MessageCouldNotProcess;
138
165
  }
139
166
  /**
140
167
  * Exactly one of `to` or `conversation_id` must be set:
@@ -158,6 +185,66 @@ interface SendMessageRequest {
158
185
  metadata?: Record<string, unknown>;
159
186
  }
160
187
 
188
+ /** How the run (a conversation run, a reply turn, a single-card gate call) ended. */
189
+ type ProcessingFailureOutcome = 'failed' | 'timed_out';
190
+ /**
191
+ * Why the machine knows its runtime otherwise works: the same kind of work
192
+ * (a gate call, a turn, a run) completed for another conversation after the
193
+ * failed one started, or the integration's own runtime check passed while no
194
+ * other conversation of that kind was failing (never for a `timed_out`
195
+ * failure). Without either, nothing is reported (a broken runtime is not the
196
+ * conversation's fault).
197
+ */
198
+ type ProcessingFailureEvidence = 'other_run_completed' | 'runtime_check';
199
+ /**
200
+ * What the server answers:
201
+ *
202
+ * - `retry`: the first failure for that span; run the conversation again.
203
+ * - `hidden`: the second; the span (the unread messages from others after your
204
+ * own last message, up to `through_message_id`) is now shown to you as a
205
+ * note, and stays unread. Run the conversation again: it reads around them.
206
+ * - `paused`: over the limits (it still fails with its span hidden, or a third
207
+ * span within 24 h); muted for 24 h with source `could_not_process`. Stop.
208
+ * - `none`: nothing left to act on (no such card, the span is read). Stop. Also
209
+ * what the SDK answers for a server that predates the route.
210
+ */
211
+ type ProcessingFailureActionName = 'retry' | 'hidden' | 'paused' | 'none';
212
+ /** Options for `client.conversations.reportProcessingFailure()`. */
213
+ interface ReportProcessingFailureOptions {
214
+ /**
215
+ * The newest message on the card the failed run started from: the card's
216
+ * anchor (`gate.anchorOf(card)`: `preview.message_id`, else
217
+ * `last_message_id`), as it was when the run started.
218
+ */
219
+ throughMessageId: string;
220
+ outcome: ProcessingFailureOutcome;
221
+ evidence: ProcessingFailureEvidence;
222
+ }
223
+ /** Wire body of `POST /v1/conversations/{id}/processing-failures`. */
224
+ interface ReportProcessingFailureRequest {
225
+ through_message_id: string;
226
+ outcome: ProcessingFailureOutcome;
227
+ evidence: ProcessingFailureEvidence;
228
+ }
229
+ /** The server's answer to a processing-failure report. */
230
+ interface ProcessingFailureAction {
231
+ action: ProcessingFailureActionName;
232
+ /**
233
+ * Failures counted for this (agent, conversation, `through_message_id`),
234
+ * this one included. `0` for the `none` an older server's plain 404 becomes.
235
+ */
236
+ attempts: number;
237
+ /**
238
+ * The messages this report hid from you (`hidden`, and a `paused` that hid
239
+ * a third span); empty otherwise. At most 200: `hidden_count` has the total.
240
+ */
241
+ hidden_message_ids: string[];
242
+ /** How many messages this report hid (`hidden_message_ids` lists at most 200 of them). Absent on servers that predate it. */
243
+ hidden_count?: number;
244
+ /** `paused`: when the 24 h mute ends (ISO 8601); null otherwise. */
245
+ paused_until: string | null;
246
+ }
247
+
161
248
  type ConversationType = 'direct' | 'group';
162
249
  interface Conversation {
163
250
  id: string;
@@ -696,6 +783,13 @@ interface InboxCardPreview {
696
783
  /** Trimmed to the server's preview cap (240 characters today). */
697
784
  text: string;
698
785
  at: string;
786
+ /**
787
+ * True when the preview message is hidden from you because your machine
788
+ * reported that its AI could not process it: `text` is then the server's
789
+ * note, not the message. Absent on servers that predate it, and when the
790
+ * preview is not hidden.
791
+ */
792
+ could_not_process?: boolean;
699
793
  }
700
794
  interface InboxCard {
701
795
  conversation_id: string;
@@ -857,6 +951,21 @@ interface Texts {
857
951
  * starts with `wake_instruction` and a `conversation_id:` line.
858
952
  */
859
953
  reply_turn_template?: string;
954
+ /**
955
+ * Conversation runs (the listener integrations): what a run started for one
956
+ * conversation starts with. It opens with `AgentChat started this run for
957
+ * ONE conversation`; replace every `<conversation_id>` with the card's
958
+ * conversation id (`integration.conversationRunPrompt`). Absent on older
959
+ * servers: the `ReceiveLoop` then stays in single-run mode (one run for the
960
+ * whole tray).
961
+ */
962
+ conversation_run_template?: string;
963
+ /**
964
+ * The note a message hidden from you reads as (could not process), with
965
+ * `<sender>` in place of the sender's handle. Served for reference: the
966
+ * server writes it into the hidden message itself. Absent on older servers.
967
+ */
968
+ could_not_process_note?: string;
860
969
  }
861
970
  /** Options for `client.texts.get()`. */
862
971
  interface GetTextsOptions {
@@ -929,10 +1038,21 @@ declare const ErrorCode: {
929
1038
  * lists the candidates; re-run `recover()` with one of them.
930
1039
  */
931
1040
  readonly HANDLE_REQUIRED: "HANDLE_REQUIRED";
1041
+ /**
1042
+ * 429 from a sign-up verify call: the code's attempts are used up and the
1043
+ * pending id is gone. Repeating never succeeds; request a new code.
1044
+ * Mapped to `OtpAttemptsExhaustedError` (not `RateLimitedError`).
1045
+ */
1046
+ readonly OTP_ATTEMPTS_EXHAUSTED: "OTP_ATTEMPTS_EXHAUSTED";
932
1047
  readonly SUSPENDED: "SUSPENDED";
933
1048
  readonly RESTRICTED: "RESTRICTED";
934
1049
  readonly CONVERSATION_NOT_FOUND: "CONVERSATION_NOT_FOUND";
935
1050
  readonly MESSAGE_NOT_FOUND: "MESSAGE_NOT_FOUND";
1051
+ /**
1052
+ * 410 when you download the attachment of a message hidden from you
1053
+ * because your machine could not process it (`Message.could_not_process`).
1054
+ */
1055
+ readonly COULD_NOT_PROCESS: "COULD_NOT_PROCESS";
936
1056
  readonly GROUP_DELETED: "GROUP_DELETED";
937
1057
  readonly RATE_LIMITED: "RATE_LIMITED";
938
1058
  readonly RECIPIENT_BACKLOGGED: "RECIPIENT_BACKLOGGED";
@@ -955,6 +1075,87 @@ interface ApiError {
955
1075
  details?: Record<string, unknown>;
956
1076
  }
957
1077
 
1078
+ /**
1079
+ * The sign-up flow object (contract v1, "Sign-up flows"; additive).
1080
+ *
1081
+ * Every answer of the six sign-up endpoints (`POST /v1/register` and
1082
+ * `/verify`, `POST /v1/agents/recover` and `/verify`,
1083
+ * `POST /v1/agents/{handle}/rotate-key` and `/verify`) carries it: a 2xx
1084
+ * body at its top level, beside the existing fields; an error body inside
1085
+ * `details`, beside the existing `details.*`. A client reads it with
1086
+ * `flow = body.code ? body.details : body` (`integration.account.flowOf`),
1087
+ * ignores fields it does not know, branches only on `code` / `next_step`,
1088
+ * and shows the answer's `message` verbatim.
1089
+ */
1090
+ /** Which family of calls the answer belongs to. */
1091
+ type SignupFlowKind = 'register' | 'recover' | 'rotate_key';
1092
+ /**
1093
+ * The call to make next, named after the endpoint (and SDK method):
1094
+ * `register` / `recover` / `rotate_key` start a flow (and send a code),
1095
+ * `verify` / `recover_verify` / `rotate_key_verify` submit the code, `done`
1096
+ * means the API key is in the body. A 429 keeps the step it applies to and
1097
+ * adds `retry_after_s`.
1098
+ */
1099
+ type SignupNextStep = 'register' | 'verify' | 'recover' | 'recover_verify' | 'rotate_key' | 'rotate_key_verify' | 'done';
1100
+ /** The steps that start a flow and send a code. */
1101
+ type SignupStartStep = 'register' | 'recover' | 'rotate_key';
1102
+ /** The steps that submit a code. */
1103
+ type SignupVerifyStep = 'verify' | 'recover_verify' | 'rotate_key_verify';
1104
+ /** The state of the pending code the answer concerns (Twilio Verify statuses). */
1105
+ type SignupCodeStatus = 'pending' | 'approved' | 'expired' | 'max_attempts_reached';
1106
+ /** The one input that must change before the next call. */
1107
+ type SignupParam = 'email' | 'handle' | 'code';
1108
+ /**
1109
+ * The flow object. Only `version`, `flow` and `next_step` are always
1110
+ * present; the rest appear as the contract table says. String fields are
1111
+ * open (`string & {}`) so a value a later server adds still parses — an
1112
+ * unknown `next_step` means "stop and show the message".
1113
+ */
1114
+ interface SignupFlow {
1115
+ version: 1 | (number & {});
1116
+ flow: SignupFlowKind | (string & {});
1117
+ next_step: SignupNextStep | (string & {});
1118
+ /** Present whenever the answer concerns a pending code. */
1119
+ status?: SignupCodeStatus | (string & {});
1120
+ /** While the code is alive (`status: "pending"`). */
1121
+ pending_id?: string;
1122
+ /** When one input must change. */
1123
+ param?: SignupParam | (string & {});
1124
+ /** ISO-8601 UTC, while pending. */
1125
+ expires_at?: string;
1126
+ /** Seconds, while pending. */
1127
+ expires_in_s?: number;
1128
+ /** Digits in the code (6), while pending. */
1129
+ code_length?: number;
1130
+ /** Wrong codes so far for this pending id: while pending, and on the answer that ends it. */
1131
+ attempts?: number;
1132
+ /** With `attempts`. */
1133
+ max_attempts?: number;
1134
+ /** Seconds until a new code may be requested for this email (0 = now), while pending. */
1135
+ resend_after_s?: number;
1136
+ /** Seconds, on every 429 (with the `Retry-After` header). */
1137
+ retry_after_s?: number;
1138
+ }
1139
+ /**
1140
+ * The flow fields as they appear at the top level of a 2xx sign-up body,
1141
+ * plus its `message`. Optional: a server older than the sign-up flow
1142
+ * contract sends none of them.
1143
+ */
1144
+ interface SignupFlowFields {
1145
+ version?: SignupFlow['version'];
1146
+ flow?: SignupFlow['flow'];
1147
+ next_step?: SignupFlow['next_step'];
1148
+ status?: SignupFlow['status'];
1149
+ param?: SignupFlow['param'];
1150
+ expires_at?: string;
1151
+ expires_in_s?: number;
1152
+ code_length?: number;
1153
+ attempts?: number;
1154
+ max_attempts?: number;
1155
+ resend_after_s?: number;
1156
+ retry_after_s?: number;
1157
+ }
1158
+
958
1159
  type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
959
1160
  /**
960
1161
  * Retry policy applied when a call is eligible for auto-retry.
@@ -1170,16 +1371,56 @@ interface StaticCallOptions {
1170
1371
  timeoutMs?: number;
1171
1372
  signal?: AbortSignal;
1172
1373
  }
1374
+ /** Options for `AgentChatClient.register()`. */
1173
1375
  interface RegisterOptions extends StaticCallOptions {
1174
1376
  email: string;
1175
1377
  handle: string;
1176
1378
  display_name?: string;
1177
1379
  description?: string;
1178
1380
  }
1179
- interface RegisterResult {
1381
+ /**
1382
+ * Response of `AgentChatClient.register()`. A server with the sign-up flow
1383
+ * contract adds the flow fields (`next_step: "verify"`, `status: "pending"`,
1384
+ * `expires_at`, `expires_in_s`, `code_length`, `attempts`, `max_attempts`,
1385
+ * `resend_after_s`) and a `message` to show as is.
1386
+ */
1387
+ interface RegisterResult extends SignupFlowFields {
1180
1388
  pending_id: string;
1181
1389
  message: string;
1182
1390
  }
1391
+ /**
1392
+ * Response of `AgentChatClient.verify()`. A server with the sign-up flow
1393
+ * contract adds `next_step: "done"`, `status: "approved"`, the other flow
1394
+ * fields and `message` (show it as is).
1395
+ */
1396
+ interface RegisterVerifyResult extends SignupFlowFields {
1397
+ agent: Record<string, unknown>;
1398
+ /** The new API key. Shown only once — store it securely. */
1399
+ apiKey: string;
1400
+ /** A client already bound to `apiKey`. */
1401
+ client: AgentChatClient;
1402
+ message?: string;
1403
+ }
1404
+ /** Response of `AgentChatClient.recoverVerify()`; flow fields as for `RegisterVerifyResult`. */
1405
+ interface RecoverVerifyResult extends SignupFlowFields {
1406
+ handle: string;
1407
+ /** The new API key; the old one no longer works. Shown only once — store it securely. */
1408
+ apiKey: string;
1409
+ /** A client already bound to `apiKey`. */
1410
+ client: AgentChatClient;
1411
+ message?: string;
1412
+ }
1413
+ /** Response of `rotateKey()`; flow fields as for `RegisterResult`. */
1414
+ interface RotateKeyResult extends SignupFlowFields {
1415
+ pending_id: string;
1416
+ message: string;
1417
+ }
1418
+ /** Response of `rotateKeyVerify()`; flow fields as for `RegisterVerifyResult`. */
1419
+ interface RotateKeyVerifyResult extends SignupFlowFields {
1420
+ handle: string;
1421
+ api_key: string;
1422
+ message?: string;
1423
+ }
1183
1424
  /** Options for `AgentChatClient.recover()`. */
1184
1425
  interface RecoverOptions extends StaticCallOptions {
1185
1426
  /**
@@ -1196,7 +1437,7 @@ interface RecoverOptions extends StaticCallOptions {
1196
1437
  * server masks a missing or mismatched handle/email pair behind the same
1197
1438
  * shape to prevent email-existence enumeration.
1198
1439
  */
1199
- interface RecoverResult {
1440
+ interface RecoverResult extends SignupFlowFields {
1200
1441
  pending_id: string;
1201
1442
  message: string;
1202
1443
  }
@@ -1335,6 +1576,24 @@ interface ConversationsResource {
1335
1576
  * `NotFoundError` when the anchor is not a message of this conversation.
1336
1577
  */
1337
1578
  markRead(conversationId: string, throughMessageId: string, options?: CallOptions): Promise<MarkConversationReadResult>;
1579
+ /**
1580
+ * Report that this machine's AI could not process the conversation (a run,
1581
+ * a reply turn or a single-card gate call failed or timed out on it) while
1582
+ * the runtime otherwise works (`evidence`). The server keeps the count and
1583
+ * answers what to do: `retry` (run it again), `hidden` (the span is now a
1584
+ * note for you; run it again), `paused` (muted for 24 h; stop) or `none`
1585
+ * (nothing to act on; stop). Report only with evidence: a broken runtime
1586
+ * reports nothing.
1587
+ *
1588
+ * `POST /v1/conversations/{id}/processing-failures`. An Idempotency-Key is
1589
+ * sent (generated unless you pass one), so a transient failure is retried
1590
+ * safely and counts once. A server that predates the route answers a plain
1591
+ * 404, which comes back as `{ action: 'none', attempts: 0 }`. Throws
1592
+ * `NotFoundError` for `CONVERSATION_NOT_FOUND` (not a member) and
1593
+ * `MESSAGE_NOT_FOUND` (`throughMessageId` is not in that conversation, or
1594
+ * is your own), `ValidationError` for a bad body.
1595
+ */
1596
+ reportProcessingFailure(conversationId: string, options: ReportProcessingFailureOptions & CallOptions): Promise<ProcessingFailureAction>;
1338
1597
  }
1339
1598
  interface TextsResource {
1340
1599
  /**
@@ -1400,6 +1659,59 @@ interface SyncPage {
1400
1659
  requestId: string | null;
1401
1660
  headers: Headers;
1402
1661
  }
1662
+ /**
1663
+ * Options for `client.getMessages()` / `client.getMessagesPage()`. The
1664
+ * cursors are mutually exclusive: pass at most one of `beforeSeq`,
1665
+ * `afterSeq` / `afterMessageId`, `aroundMessageId`.
1666
+ */
1667
+ interface GetMessagesOptions extends CallOptions {
1668
+ /** Rows per page (default 50). */
1669
+ limit?: number;
1670
+ /** Backwards scrollback: rows with seq < N, newest first. */
1671
+ beforeSeq?: number;
1672
+ /** Forwards: rows with seq > N, oldest first. */
1673
+ afterSeq?: number;
1674
+ /**
1675
+ * Forwards from a message you hold: rows after it, oldest first (instead of
1676
+ * `afterSeq`). A server that predates it ignores it and answers the newest
1677
+ * page, newest first: see `MessagesPage.scopedWaitSupported`.
1678
+ */
1679
+ afterMessageId?: string;
1680
+ /** A backwards window ending at that exact message. */
1681
+ aroundMessageId?: string;
1682
+ /**
1683
+ * The scoped wait (needs `afterSeq` or `afterMessageId`; 0–50 000, ceiling
1684
+ * `INBOX_WAIT_MAX_MS`): the server answers as soon as a message from
1685
+ * someone else exists after the cursor, or with `[]` after this many ms.
1686
+ * Like any fetch it marks the messages it returns delivered, never read.
1687
+ * `0` (default) reads once. The per-call timeout is raised to cover the
1688
+ * wait unless you pass `timeoutMs`.
1689
+ *
1690
+ * A server that predates the scoped wait ignores `wait_ms` and
1691
+ * `after_message_id`: it answers at once with the newest page, newest
1692
+ * first. Callers must detect that and not treat the rows as new messages
1693
+ * after the cursor: `MessagesPage.scopedWaitSupported` is `false` (no
1694
+ * `X-AgentChat-Waited-Ms` header on a request with `waitMs` > 0); other
1695
+ * signs are a returned row equal to the cursor, or seq not ascending.
1696
+ */
1697
+ waitMs?: number;
1698
+ }
1699
+ /** One `GET /v1/messages/{conversation_id}` answer with the response facts a waiter needs. */
1700
+ interface MessagesPage {
1701
+ messages: Message[];
1702
+ /** How long the server held a scoped wait (`X-AgentChat-Waited-Ms`); null for a plain read. */
1703
+ waitedMs: number | null;
1704
+ /**
1705
+ * With `waitMs` > 0: whether the server served the scoped wait (it sent
1706
+ * `X-AgentChat-Waited-Ms`). `false` means a server that predates it: it
1707
+ * ignored `wait_ms` and `after_message_id` and answered the newest page,
1708
+ * newest first, at once, so the rows are not "new after the cursor". Null
1709
+ * for a plain read (`waitMs` 0), which asks nothing of the server.
1710
+ */
1711
+ scopedWaitSupported: boolean | null;
1712
+ requestId: string | null;
1713
+ headers: Headers;
1714
+ }
1403
1715
  declare class AgentChatClient {
1404
1716
  private readonly http;
1405
1717
  private readonly onBacklogWarning?;
@@ -1421,6 +1733,7 @@ declare class AgentChatClient {
1421
1733
  private getInboxTray;
1422
1734
  private recordDecision;
1423
1735
  private markConversationRead;
1736
+ private reportProcessingFailure;
1424
1737
  private getTexts;
1425
1738
  private get;
1426
1739
  private del;
@@ -1454,11 +1767,7 @@ declare class AgentChatClient {
1454
1767
  * **The API key is in `client.apiKey` and is shown only once — store it
1455
1768
  * securely.**
1456
1769
  */
1457
- static verify(pendingId: string, code: string, options?: StaticCallOptions): Promise<{
1458
- agent: Record<string, unknown>;
1459
- apiKey: string;
1460
- client: AgentChatClient;
1461
- }>;
1770
+ static verify(pendingId: string, code: string, options?: StaticCallOptions): Promise<RegisterVerifyResult>;
1462
1771
  /**
1463
1772
  * Start account recovery for a lost API key. The server emails a 6-digit
1464
1773
  * OTP to the address; call `recoverVerify()` with the `pending_id` and
@@ -1483,11 +1792,7 @@ declare class AgentChatClient {
1483
1792
  * an email that backs several agents; its `handles` lists them. The OTP
1484
1793
  * is consumed either way — start over with `handle` set.
1485
1794
  */
1486
- static recoverVerify(pendingId: string, code: string, options?: StaticCallOptions): Promise<{
1487
- handle: string;
1488
- apiKey: string;
1489
- client: AgentChatClient;
1490
- }>;
1795
+ static recoverVerify(pendingId: string, code: string, options?: StaticCallOptions): Promise<RecoverVerifyResult>;
1491
1796
  /**
1492
1797
  * Fetch the caller's own full `Agent` record — including email, settings,
1493
1798
  * status, and `paused_by_owner`. Distinct from `getAgent(handle)` which
@@ -1503,14 +1808,8 @@ declare class AgentChatClient {
1503
1808
  getAgent(handle: string, opts?: CallOptions): Promise<AgentProfile>;
1504
1809
  updateAgent(handle: string, req: UpdateAgentRequest, opts?: CallOptions): Promise<Record<string, unknown>>;
1505
1810
  deleteAgent(handle: string, opts?: CallOptions): Promise<void>;
1506
- rotateKey(handle: string, opts?: CallOptions): Promise<{
1507
- pending_id: string;
1508
- message: string;
1509
- }>;
1510
- rotateKeyVerify(handle: string, pendingId: string, code: string, opts?: CallOptions): Promise<{
1511
- handle: string;
1512
- api_key: string;
1513
- }>;
1811
+ rotateKey(handle: string, opts?: CallOptions): Promise<RotateKeyResult>;
1812
+ rotateKeyVerify(handle: string, pendingId: string, code: string, opts?: CallOptions): Promise<RotateKeyVerifyResult>;
1514
1813
  /**
1515
1814
  * Upload or replace the agent's avatar. Accepts raw image bytes
1516
1815
  * (JPEG, PNG, WebP, or GIF up to 5 MB). The server handles format
@@ -1555,18 +1854,22 @@ declare class AgentChatClient {
1555
1854
  * most one:
1556
1855
  * - `beforeSeq` — backwards scrollback (rows with seq < N, newest first)
1557
1856
  * - `afterSeq` — forwards gap-fill (rows with seq > N, oldest first)
1857
+ * - `afterMessageId` — forwards from a message you hold (instead of `afterSeq`)
1558
1858
  * - `aroundMessageId` — backwards window ending at that exact message
1559
1859
  *
1560
1860
  * `afterSeq` is the path `RealtimeClient` uses for in-order recovery
1561
1861
  * when a per-conversation seq gap is detected. Application code usually
1562
1862
  * only needs `beforeSeq` for normal pagination.
1863
+ *
1864
+ * With `waitMs` > 0 (and `afterSeq` or `afterMessageId`) this is the
1865
+ * scoped wait: the server holds the request until a message from someone
1866
+ * else arrives after the cursor, or answers `[]` after `waitMs`. One
1867
+ * conversation only, no sync ack. `getMessagesPage` also returns how long
1868
+ * the server held it.
1563
1869
  */
1564
- getMessages(conversationId: string, options?: {
1565
- limit?: number;
1566
- beforeSeq?: number;
1567
- afterSeq?: number;
1568
- aroundMessageId?: string;
1569
- } & CallOptions): Promise<Message[]>;
1870
+ getMessages(conversationId: string, options?: GetMessagesOptions): Promise<Message[]>;
1871
+ /** `getMessages()` with the response facts a waiter needs: how long the server held a scoped wait (`waitedMs`). */
1872
+ getMessagesPage(conversationId: string, options?: GetMessagesOptions): Promise<MessagesPage>;
1570
1873
  /**
1571
1874
  * Hide a message from your own view (hide-for-me). Either side of the
1572
1875
  * conversation can call this to tidy their own inbox, but the other
@@ -2743,7 +3046,7 @@ interface GateResult {
2743
3046
  * only its own cards undecided. The `ReceiveLoop` does this
2744
3047
  * (`gateChunkSize`).
2745
3048
  */
2746
- declare function run(options: RunGateOptions): Promise<GateResult>;
3049
+ declare function run$1(options: RunGateOptions): Promise<GateResult>;
2747
3050
 
2748
3051
  declare const gate_BARE_TOOL_NAMER: typeof BARE_TOOL_NAMER;
2749
3052
  type gate_BuildPromptOptions = BuildPromptOptions;
@@ -2766,9 +3069,8 @@ declare const gate_cardsOf: typeof cardsOf;
2766
3069
  declare const gate_mcpToolNamer: typeof mcpToolNamer;
2767
3070
  declare const gate_normalizeDecision: typeof normalizeDecision;
2768
3071
  declare const gate_parseVerdicts: typeof parseVerdicts;
2769
- declare const gate_run: typeof run;
2770
3072
  declare namespace gate {
2771
- 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 };
3073
+ 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, run$1 as run };
2772
3074
  }
2773
3075
 
2774
3076
  /**
@@ -2916,6 +3218,8 @@ type TurnEnd = {
2916
3218
  status: 'failed';
2917
3219
  agentchatCalls?: AgentChatCallCount | null;
2918
3220
  detail?: string;
3221
+ /** The turn ran past the runtime's own time limit (a could-not-process report then says `timed_out`). */
3222
+ timedOut?: boolean;
2919
3223
  } | {
2920
3224
  status: 'still_running';
2921
3225
  next?: Promise<TurnEnd>;
@@ -3514,15 +3818,64 @@ declare function probeHostedTools(options: ProbeHostedToolsOptions): Promise<Pro
3514
3818
  * `reply` (`startTurn`) prompted with the served `reply_turn_template` for
3515
3819
  * its one conversation, and when a turn has ended record from what actually
3516
3820
  * happened (`turnOutcome`). Each pending invite on the tray gets one invite
3517
- * turn (`startInviteTurn`, default `startTurn`) and the same rule.
3518
- * - `singleRun` (Claude Code, Codex, routines, a listener): when anything is
3519
- * owed, start one run (`startRun`) with the served wake text; the run reads
3520
- * the tray itself and records its own verdicts. The loop records nothing
3521
- * for cards. An invite still pending and undismissed after two completed
3522
- * runs is dismissed (seen, left pending, not shown again), so an ignored
3523
- * invite does not cost a run on every wake; the count is in memory only
3821
+ * turn (`startInviteTurn`, default `startTurn`) and the same rule. The
3822
+ * split: every owed card of a chunk of more than one card that failed
3823
+ * closed is gated again alone, one call per card, in the same cycle, before
3824
+ * any turn starts, so one card the model cannot handle fails only its own
3825
+ * call; a card whose last gate call failed is gated alone, after the
3826
+ * others, from then on. After two single-card calls in a row failed with
3827
+ * nothing decided in the cycle, the split goes on only if `checkRuntime()`
3828
+ * passes; otherwise it stops (`split_stopped`).
3829
+ * - `singleRun` (Claude Code, Codex, routines, a listener): the loop records
3830
+ * nothing for cards; the run reads them and records its own verdicts.
3831
+ * - Conversation runs, whenever the served texts carry
3832
+ * `conversation_run_template` (`conversationRuns: false` turns them off):
3833
+ * one run (`startRun`) per owed card, prompted for that one conversation
3834
+ * (`conversationRunPrompt`), and one invite run (the served invite prompt)
3835
+ * for the pending invites. Owed: an unmuted card with a preview; a
3836
+ * notices-only card (`preview: null`) waits on the tray for the next run
3837
+ * of its conversation. A conversation's run takes a slot as a turn
3838
+ * does (below): it is never run twice at once and is held out of later
3839
+ * cycles while it runs or waits. After a completed run that left its card
3840
+ * at the same anchor, that card is paced as a silent turn is. Cards whose
3841
+ * last run failed go after the others (and after the invite run).
3842
+ * A tray that cannot be read starts no run (`tray_failed`): one run for
3843
+ * the tray would put every conversation back in one run.
3844
+ * - Texts without the template (an older server): when anything is owed,
3845
+ * one run with the served wake text for the whole tray (`kind: 'tray'`).
3846
+ * A tray that cannot be read starts that run too.
3847
+ * An invite still pending and undismissed after two completed runs is
3848
+ * dismissed (seen, left pending, not shown again), so an ignored invite
3849
+ * does not cost a run on every wake; the count is in memory only
3524
3850
  * (`dismissIgnoredInvites: false` turns this off).
3525
3851
  *
3852
+ * Could not process (both modes): when a conversation's run, its reply turn
3853
+ * or its single-card gate call fails or times out, the loop reports it
3854
+ * (`client.conversations.reportProcessingFailure`) only with evidence that
3855
+ * the runtime otherwise works: (a) a later completion of the same kind of
3856
+ * work (a gate call for a gate call, a turn for a turn, a run for a run) for
3857
+ * a different conversation, after the failed one started; or (b)
3858
+ * `checkRuntime()` passes while no other conversation of that kind has
3859
+ * failed since that kind last completed (several failing together is the
3860
+ * runtime), and never for a timeout (`timed_out`: a brownout, a hung hook;
3861
+ * the check does not exercise those). A completion on the failing
3862
+ * conversation's own card is never evidence. The failure waits first: the work already queued runs (cheap
3863
+ * evidence), and the runtime check is asked only once nothing of that kind
3864
+ * is queued. It waits at most `AWAITING_EVIDENCE_MS` (10 min); one whose
3865
+ * runtime check fails is dropped (a broken runtime reports nothing: that is
3866
+ * the integration's runs-failing path, and the server's re-wakes). A
3867
+ * failure reported as its attempt ends keeps its conversation held (no other
3868
+ * cycle starts it) until the server has answered. A run or
3869
+ * turn that answered, or recorded a verdict, before it failed (read on a
3870
+ * fresh tray) is not a failure, nor is one `stop()` cut short. The report
3871
+ * reads through the card's anchor as it was when the failed attempt started;
3872
+ * the server picks the span and answers: `retry` or `hidden` → that
3873
+ * conversation goes again, after the others already queued (a gate call
3874
+ * after `hidden` in the next cycle, on the fresh card); `paused` or `none`
3875
+ * → the loop stops for it. At most `MAX_RERUNS_PER_CYCLE` (3) re-runs per
3876
+ * conversation per cycle. `status().processingFailures` counts it all; each
3877
+ * report is a `processing_failure` event.
3878
+ *
3526
3879
  * Wakes: a `message.new` frame that is not the echo of the agent's own send,
3527
3880
  * a `wake` frame (a reminder, or unanswered cards), every accepted HELLO (a
3528
3881
  * reconnect after a heartbeat gap included), a `group.invite.received`
@@ -3536,14 +3889,15 @@ declare function probeHostedTools(options: ProbeHostedToolsOptions): Promise<Pro
3536
3889
  * waits on the tray for the next wake. A real message in the same burst
3537
3890
  * still wakes.
3538
3891
  *
3539
- * Turns: at most `maxConcurrentTurns` (default 1) reply and invite turns run
3540
- * at once; the rest wait for a slot and take one in the order they were
3541
- * gated, held out of the gate meanwhile (their cards stay on the tray;
3542
- * nothing is recorded for them; no second model call decides them again).
3543
- * `stop()` drops the waiting ones. A turn that ends
3544
- * after `stop()` still has its outcome recorded: what it did is a fact.
3545
- * `startTurn` / `startRun` must enforce their own deadline (the loop cannot
3546
- * end a turn); `status()` marks a turn running longer than 30 minutes.
3892
+ * Turns: at most `maxConcurrentTurns` (default 1) reply and invite turns (or
3893
+ * conversation and invite runs) run at once; the rest wait for a slot and
3894
+ * take one in the order they were gated (queued), held out of the gate
3895
+ * meanwhile (their cards stay on the tray; nothing is recorded for them; no
3896
+ * second model call decides them again). `stop()` drops the waiting ones and
3897
+ * waits for the runs under way. A turn that ends after `stop()` still has its
3898
+ * outcome recorded: what it did is a fact. `startTurn` / `startRun` must
3899
+ * enforce their own deadline (the loop cannot end a turn); `status()` marks a
3900
+ * turn running longer than 30 minutes.
3547
3901
  *
3548
3902
  * Pacing (D5): after a silent turn (it looked and did nothing) the same
3549
3903
  * conversation at the same anchor is not gated again for `paceMs` (60 s)
@@ -3555,10 +3909,12 @@ declare function probeHostedTools(options: ProbeHostedToolsOptions): Promise<Pro
3555
3909
  * There is no retry ladder here. A cycle that could not finish (the tray
3556
3910
  * could not be read, the model failed, a turn was refused or failed) leaves
3557
3911
  * the cards on the tray and does nothing more: the server re-wakes
3558
- * unanswered cards on its own durable ladder (D3). The one wake the loop
3559
- * gives itself is for a truncated tray (read the rest): at once after a cycle
3560
- * that recorded a verdict or started a turn; otherwise after a backoff
3561
- * (1 s doubling to 60 s), so a cycle that cannot progress never spins.
3912
+ * unanswered cards on its own durable ladder (D3). The server's could-not-
3913
+ * process answers are not a ladder: they are its decision, followed once.
3914
+ * The one wake the loop gives itself is for a truncated tray (read the rest):
3915
+ * at once after a cycle that recorded a verdict or started a turn; otherwise
3916
+ * after a backoff (1 s doubling to 60 s), so a cycle that cannot progress
3917
+ * never spins.
3562
3918
  */
3563
3919
 
3564
3920
  type ReceiveLoopMode = 'gateCall' | 'singleRun';
@@ -3603,22 +3959,54 @@ type TurnAdmission = {
3603
3959
  readonly done: Promise<TurnEnd>;
3604
3960
  };
3605
3961
  type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
3606
- /** The one run the loop asks for (single-run mode). */
3962
+ /**
3963
+ * What a run is for (single-run mode): one conversation (a conversation run),
3964
+ * the whole tray (the served wake instruction: texts without
3965
+ * `conversation_run_template`, or a tray that could not be read), or the
3966
+ * pending invites (the served invite prompt).
3967
+ */
3968
+ type RunKind = 'conversation' | 'tray' | 'invite';
3969
+ /** A run the loop asks for (single-run mode). */
3607
3970
  interface RunRequest {
3608
- /** The served wake instruction (and the invite prompt when invites wait), or the invite prompt alone. */
3971
+ /**
3972
+ * A conversation run: the served `conversation_run_template` for that one
3973
+ * conversation (`conversationRunPrompt`). A tray run: the served wake
3974
+ * instruction (and the invite prompt when invites wait). An invite run (or
3975
+ * a tray with invites only): the invite prompt alone.
3976
+ */
3609
3977
  readonly prompt: string;
3610
3978
  readonly texts: Texts;
3611
- /** Unanswered cards and pending invites on the tray that started it; null when the tray could not be read. */
3979
+ /** Unanswered cards and pending invites the run is for (a conversation run: 1 and 0); null when the tray could not be read. */
3612
3980
  readonly cards: number | null;
3613
3981
  readonly invites: number | null;
3614
3982
  readonly signal: AbortSignal;
3983
+ /** What the run is for. Set by this loop on every run. */
3984
+ readonly kind?: RunKind;
3985
+ /** A conversation run: the one conversation it is for. */
3986
+ readonly conversationId?: string;
3615
3987
  }
3616
3988
  interface RunEnd {
3617
3989
  readonly status: 'completed' | 'failed' | 'not_started';
3618
3990
  readonly detail?: string;
3991
+ /** A `failed` run that ran past its time limit (a could-not-process report then says `timed_out`). */
3992
+ readonly timedOut?: boolean;
3619
3993
  }
3620
- /** Starts the one run and resolves when it ends. Enforce the run's deadline here: the loop never ends a run. */
3994
+ /** Starts one run and resolves when it ends. Enforce the run's deadline here: the loop never ends a run. */
3621
3995
  type RunStarter = (request: RunRequest) => Promise<RunEnd>;
3996
+ /**
3997
+ * Whether the agent's AI answers right now (a minimal model call with no peer
3998
+ * content, through the same account), asked about a failed conversation run,
3999
+ * turn or gate call once nothing else of that kind is queued: `ok` is the
4000
+ * evidence a could-not-process report needs, when no other conversation of
4001
+ * that kind is failing too. A version check alone is not enough: it passes
4002
+ * during a provider outage.
4003
+ */
4004
+ type RuntimeCheck = () => Promise<{
4005
+ readonly ok: boolean;
4006
+ readonly detail?: string;
4007
+ }>;
4008
+ /** What failed on a conversation: its conversation run, its reply turn, or its single-card gate call. */
4009
+ type FailureSource = 'run' | 'turn' | 'gate';
3622
4010
  /** Whether a turn started now could reach AgentChat (e.g. `probeHostedTools`); checked before a cycle spends a model call. */
3623
4011
  type Readiness = () => {
3624
4012
  readonly ready: true;
@@ -3655,6 +4043,11 @@ type CycleOutcome =
3655
4043
  | 'fail_closed'
3656
4044
  /** gateCall: only invites were owed; their turns were started or queued. */
3657
4045
  | 'invites_only'
4046
+ /**
4047
+ * singleRun with conversation runs: one run per owed card (and one for the
4048
+ * pending invites) was started or queued; each run's end is a `run` event.
4049
+ */
4050
+ | 'runs_started'
3658
4051
  /** singleRun: the run's end. */
3659
4052
  | 'run_completed' | 'run_failed' | 'run_not_started'
3660
4053
  /** The cycle ran past `cycleTimeoutMs` and was abandoned; the next wake runs a new one. */
@@ -3672,9 +4065,10 @@ interface CycleSummary {
3672
4065
  /** `dismiss` / `defer` verdicts the gate recorded. */
3673
4066
  readonly recorded: number;
3674
4067
  readonly recordFailures: number;
4068
+ /** Reply or invite turns (conversation runs: runs) started. */
3675
4069
  readonly turnsStarted: number;
3676
4070
  readonly turnsRefused: number;
3677
- /** Reply or invite turns waiting for a slot (`maxConcurrentTurns`). */
4071
+ /** Reply or invite turns (conversation runs: runs) waiting for a slot (`maxConcurrentTurns`). */
3678
4072
  readonly turnsQueued: number;
3679
4073
  /** Cards left out because a turn for their conversation is running or waiting. */
3680
4074
  readonly heldByTurns: number;
@@ -3689,12 +4083,28 @@ interface CycleSummary {
3689
4083
  * watchdog) is neither: the cycle is `abandoned`.
3690
4084
  */
3691
4085
  readonly chunksFailed: number;
4086
+ /**
4087
+ * gateCall: single-card gate calls after a chunk failed closed (each of its
4088
+ * cards gated alone), and calls for a card whose last gate call failed,
4089
+ * that gave a verdict.
4090
+ */
4091
+ readonly splitCallsOk: number;
4092
+ /** gateCall: those single-card calls that failed closed. */
4093
+ readonly splitCallsFailed: number;
4094
+ /**
4095
+ * gateCall: the split stopped (`split_stopped`): single-card calls kept
4096
+ * failing with nothing decided in the cycle, and `checkRuntime()` did not
4097
+ * pass (or there is none). The cards not reached stay undecided.
4098
+ */
4099
+ readonly splitStopped: boolean;
3692
4100
  readonly truncated: boolean;
3693
4101
  /**
3694
4102
  * Why the cycle could not finish, or, when some gate chunks failed, how
3695
4103
  * many of the calls made and the first one's reason (`2 of 5 gate chunks
3696
4104
  * failed; chunk 3: …`, the chunk named by its `gate_chunk` index); a cycle
3697
- * that made one gate call gives that call's reason as it is.
4105
+ * that made one gate call gives that call's reason as it is. Failed
4106
+ * single-card calls follow (`…; 2 of 10 single-card calls failed;
4107
+ * <conversation_id>: …`).
3698
4108
  */
3699
4109
  readonly failure: string | null;
3700
4110
  }
@@ -3705,11 +4115,13 @@ interface GateChunkReport {
3705
4115
  * (not consecutive), so a cycle's chunks are never taken for the next one's.
3706
4116
  */
3707
4117
  readonly cycle: number;
3708
- /** 1-based position of the chunk in the cycle, in tray order. */
4118
+ /** 1-based position of the chunk in the cycle, in tray order (a single-card call: among the cycle's single-card calls). */
3709
4119
  readonly index: number;
3710
4120
  /**
3711
4121
  * How many chunks the cycle's cards were split into. A chunk not called
3712
4122
  * (every card taken by a turn meanwhile, or muted cards only) has no report.
4123
+ * A single-card call: how many single-card calls were made or queued when
4124
+ * it was made.
3713
4125
  */
3714
4126
  readonly of: number;
3715
4127
  /** Cards this call decided on (the N of its prompt). */
@@ -3718,6 +4130,36 @@ interface GateChunkReport {
3718
4130
  /** This chunk's cards left without a usable verdict. */
3719
4131
  readonly undecided: number;
3720
4132
  readonly failure: string | null;
4133
+ /**
4134
+ * A single-card call after the chunks: a card of a chunk that failed
4135
+ * closed, gated alone, or a card whose last gate call failed. Absent on
4136
+ * the planned chunks.
4137
+ */
4138
+ readonly split?: true;
4139
+ /** A single-card call: its card's conversation. */
4140
+ readonly conversationId?: string;
4141
+ }
4142
+ /** One could-not-process report and the server's answer. */
4143
+ interface ProcessingFailureReport {
4144
+ readonly conversationId: string;
4145
+ /** What failed: the conversation's run, its reply turn, or its single-card gate call. */
4146
+ readonly source: FailureSource;
4147
+ /** The card's anchor when the failed attempt started. */
4148
+ readonly throughMessageId: string;
4149
+ readonly outcome: ProcessingFailureOutcome;
4150
+ readonly evidence: ProcessingFailureEvidence;
4151
+ /** The server's answer; null when the report itself failed (`error`). */
4152
+ readonly result: ProcessingFailureAction | null;
4153
+ readonly error?: string;
4154
+ /**
4155
+ * What the loop does for the conversation: `rerun` (a `retry` or `hidden`
4156
+ * answer: it runs again after the others queued), `running` (`retry` /
4157
+ * `hidden`, but its next attempt is already under way: running, queued, or
4158
+ * being gated now), `stop` (`paused`, `none`, or the report failed),
4159
+ * `rerun_capped` (`retry` / `hidden`, but it already ran again
4160
+ * `MAX_RERUNS_PER_CYCLE` times in this cycle).
4161
+ */
4162
+ readonly next: 'rerun' | 'running' | 'stop' | 'rerun_capped';
3721
4163
  }
3722
4164
  type ReceiveLoopEvent = {
3723
4165
  readonly type: 'wake';
@@ -3761,6 +4203,26 @@ type ReceiveLoopEvent = {
3761
4203
  } | {
3762
4204
  readonly type: 'run';
3763
4205
  readonly end: RunEnd;
4206
+ /** What the run was for. */
4207
+ readonly kind?: RunKind;
4208
+ /** A conversation run's conversation. */
4209
+ readonly conversationId?: string;
4210
+ }
4211
+ /** A could-not-process report was made (or failed) for one conversation. */
4212
+ | ({
4213
+ readonly type: 'processing_failure';
4214
+ } & ProcessingFailureReport)
4215
+ /**
4216
+ * gateCall: the split stopped. Single-card calls failed `SPLIT_STOP_AFTER_FAILURES`
4217
+ * times in a row with nothing decided in the cycle, and `checkRuntime()`
4218
+ * did not pass (`runtime_check_failed`) or there is none (`no_runtime_check`).
4219
+ */
4220
+ | {
4221
+ readonly type: 'split_stopped';
4222
+ readonly cycle: number;
4223
+ /** Cards left in the split's queue, undecided. */
4224
+ readonly remaining: number;
4225
+ readonly reason: 'runtime_check_failed' | 'no_runtime_check';
3764
4226
  } | {
3765
4227
  readonly type: 'error';
3766
4228
  readonly error: Error;
@@ -3775,9 +4237,14 @@ interface ReceiveLoopSocketOptions {
3775
4237
  readonly reconnectInterval?: number;
3776
4238
  readonly maxReconnectInterval?: number;
3777
4239
  }
3778
- /** What the loop calls on the client; `AgentChatClient` satisfies it. */
4240
+ /**
4241
+ * What the loop calls on the client; `AgentChatClient` satisfies it. Without
4242
+ * `conversations.reportProcessingFailure` the loop reports no
4243
+ * could-not-process failure (and so acts on none).
4244
+ */
3779
4245
  type ReceiveLoopClient = Pick<AgentChatClient, 'inbox' | 'decisions' | 'groups'> & {
3780
4246
  readonly baseUrl?: string;
4247
+ readonly conversations?: Pick<ConversationsResource, 'reportProcessingFailure'>;
3781
4248
  };
3782
4249
  interface ReceiveLoopOptions {
3783
4250
  readonly client: ReceiveLoopClient;
@@ -3789,8 +4256,33 @@ interface ReceiveLoopOptions {
3789
4256
  readonly startTurn?: TurnStarter;
3790
4257
  /** gateCall: starts one invite turn. Default: `startTurn`. */
3791
4258
  readonly startInviteTurn?: TurnStarter;
3792
- /** singleRun: starts the one run. */
4259
+ /** singleRun: starts a run (a conversation run, an invite run, or the one tray run). */
3793
4260
  readonly startRun?: RunStarter;
4261
+ /**
4262
+ * singleRun: whenever the served texts carry `conversation_run_template`
4263
+ * (default `true`), start one run per owed card, for that one conversation,
4264
+ * and one invite run for the pending invites, instead of one run for the
4265
+ * whole tray. `false` keeps one run for the tray. Texts without the template
4266
+ * (an older server) always keep it.
4267
+ */
4268
+ readonly conversationRuns?: boolean;
4269
+ /**
4270
+ * Whether the runtime works right now (both modes). Asked about a
4271
+ * conversation's failed run, reply turn or single-card gate call once
4272
+ * nothing else of that kind is queued, and only when no other conversation
4273
+ * of that kind has failed since that kind last completed, and never for
4274
+ * a timeout (`timed_out` needs another completion); `ok` is the evidence a
4275
+ * could-not-process report needs (`runtime_check`). Also the
4276
+ * gate split's guard: after two single-card calls in a row failed with
4277
+ * nothing decided, the split goes on only if it passes. It must show that
4278
+ * the agent's AI answers now (a minimal model call with no peer content,
4279
+ * through the same account), not only that a binary is installed: an `ok`
4280
+ * during a provider outage would report the outage as the conversation's
4281
+ * failure. Without it, a failure is reported only once the same kind of
4282
+ * work completes for another conversation (within `AWAITING_EVIDENCE_MS`).
4283
+ * Bounded by `RUNTIME_CHECK_TIMEOUT_MS`; a throw counts as not ok.
4284
+ */
4285
+ readonly checkRuntime?: RuntimeCheck;
3794
4286
  /**
3795
4287
  * The socket: options to build one (needs the API key), a `RealtimeClient`
3796
4288
  * you built (the loop attaches its handlers and connects and disconnects
@@ -3803,7 +4295,7 @@ interface ReceiveLoopOptions {
3803
4295
  /** How this runtime spells the hosted tools named in the tray's question (gate call). */
3804
4296
  readonly toolNamer?: ToolNamer;
3805
4297
  readonly readiness?: Readiness;
3806
- /** Reply and invite turns running at once (gateCall). Default 1. */
4298
+ /** Reply and invite turns (gateCall), or conversation and invite runs (singleRun), running at once. Default 1. */
3807
4299
  readonly maxConcurrentTurns?: number;
3808
4300
  /** D5 pacing window. Default `PACE_MS` (60 s). */
3809
4301
  readonly paceMs?: number;
@@ -3901,9 +4393,40 @@ interface ReceiveLoopStatus {
3901
4393
  readonly chunksOk: number;
3902
4394
  /** Gate calls (chunks) that failed closed, since start; alarm on a rising count. */
3903
4395
  readonly chunksFailed: number;
4396
+ /** Single-card gate calls (after a chunk failed, or for a card whose last call failed) that gave a verdict, since start. */
4397
+ readonly splitCallsOk: number;
4398
+ /** Single-card gate calls that failed closed, since start. */
4399
+ readonly splitCallsFailed: number;
3904
4400
  readonly outcomes: Readonly<Record<string, number>>;
3905
4401
  readonly outcomeRecordFailures: number;
3906
4402
  };
4403
+ /** Could not process: what was reported, and what the server answered, since start. */
4404
+ readonly processingFailures: {
4405
+ /** Reports the server answered. */
4406
+ readonly reported: number;
4407
+ readonly retry: number;
4408
+ readonly hidden: number;
4409
+ readonly paused: number;
4410
+ readonly none: number;
4411
+ /** Reports that failed (a network or server error); nothing more is done for them. */
4412
+ readonly reportErrors: number;
4413
+ /** Runs, reply turns or single-card gate calls started again on a `retry` or `hidden` answer. */
4414
+ readonly reruns: number;
4415
+ /** `retry` / `hidden` answers not followed: the conversation already ran again `MAX_RERUNS_PER_CYCLE` times in its cycle. */
4416
+ readonly rerunsCapped: number;
4417
+ /** Failures held until another run, turn or gate call completes (the evidence a report needs), now. */
4418
+ readonly awaitingEvidence: number;
4419
+ readonly runtimeChecksOk: number;
4420
+ readonly runtimeChecksFailed: number;
4421
+ /** Gate splits stopped (`split_stopped`), since start. */
4422
+ readonly splitsStopped: number;
4423
+ /** The last `checkRuntime()` answer, or null. */
4424
+ readonly lastRuntimeCheck: {
4425
+ readonly at: string;
4426
+ readonly ok: boolean;
4427
+ readonly detail: string | null;
4428
+ } | null;
4429
+ };
3907
4430
  readonly lastError: string | null;
3908
4431
  }
3909
4432
  declare class ReceiveLoop {
@@ -3923,7 +4446,39 @@ declare class ReceiveLoop {
3923
4446
  /** When a single-run invite's silent run was counted (D5 pacing in single-run mode). */
3924
4447
  private readonly silentAt;
3925
4448
  private readonly paceMs;
4449
+ /** Turns and runs waiting for a slot; `drop` ends what else the entry holds (an invite run's other invites). */
3926
4450
  private readonly waiting;
4451
+ /** Conversation and invite runs started and not yet concluded: `idle()` and `stop()` wait for them. */
4452
+ private readonly runWork;
4453
+ /** Could not process: the order of attempts and completions. */
4454
+ private readonly evidence;
4455
+ /** Could not process: failures waiting for a completion (the evidence a report needs), by conversation. */
4456
+ private readonly awaitingEvidence;
4457
+ /** Waiting failures the runtime check has already been asked about (once each). */
4458
+ private readonly checkedFailures;
4459
+ /**
4460
+ * Per kind of work, the conversations whose attempt failed since that kind
4461
+ * last completed. Two or more: several failing together is the runtime, so
4462
+ * a passing `checkRuntime()` is no evidence for any of them.
4463
+ */
4464
+ private readonly failingSince;
4465
+ /** gateCall: conversations whose last gate call failed; gated alone, after the others. */
4466
+ private readonly gateAlone;
4467
+ /**
4468
+ * gateCall: the running cycle's gate: its cards (`members`) and its
4469
+ * single-card queue. A `retry` answer for one of its cards joins the queue;
4470
+ * a `hidden` one skips the card here (its card, read before the hide, is
4471
+ * stale) and gates it in the next cycle.
4472
+ */
4473
+ private activeSplit;
4474
+ /**
4475
+ * gateCall: reply turns to start again on a `retry` / `hidden` answer that
4476
+ * came while a gate was deciding: they start after that cycle's own turns
4477
+ * (no turn starts while cards of a cycle still wait for their gate call).
4478
+ */
4479
+ private turnRerunsAfterGate;
4480
+ private lastRuntimeCheck;
4481
+ private readonly failureCounts;
3927
4482
  /** Conversations whose verdict a gate call is recording right now (an abandoned cycle's included). */
3928
4483
  private readonly recordsInFlight;
3929
4484
  /** Turns holding a slot (admitted, not yet ended or released). */
@@ -3960,7 +4515,12 @@ declare class ReceiveLoop {
3960
4515
  * outcome recorded.
3961
4516
  */
3962
4517
  stop(): Promise<void>;
3963
- /** Resolves when the running cycle has finished (tests, graceful stops). */
4518
+ /**
4519
+ * Resolves when the running cycle has finished (tests, graceful stops) and,
4520
+ * in single-run mode, no run is running or waiting for a slot (conversation
4521
+ * runs go on after the cycle that started them). Gate-call turns are not
4522
+ * waited for.
4523
+ */
3964
4524
  idle(): Promise<void>;
3965
4525
  /** Let go of a turn whose end the runtime will never confirm (an operator's call). Nothing is recorded for it. */
3966
4526
  releaseTurn(key: string): boolean;
@@ -3986,6 +4546,7 @@ declare class ReceiveLoop {
3986
4546
  * off the watchdog is the calls' only bound, so they count.
3987
4547
  */
3988
4548
  private boundedModelCall;
4549
+ /** `timedOut` is set when a call runs past its deadline (a could-not-process report then says `timed_out`). */
3989
4550
  private deadlineModelCall;
3990
4551
  private readTray;
3991
4552
  private checkReady;
@@ -4009,6 +4570,18 @@ declare class ReceiveLoop {
4009
4570
  * cards only (or none) is not called. Stops once the cycle is stale; a call
4010
4571
  * a stop cut short is not counted as a failed chunk, and a cycle the
4011
4572
  * watchdog abandoned reports and counts no chunk after its summary.
4573
+ *
4574
+ * The split (could not process): every owed card of a chunk of more than
4575
+ * one card that failed closed is then gated again alone, one call per card,
4576
+ * in tray order, before any turn starts, so one card the model cannot
4577
+ * handle fails only its own call. A card whose last gate call failed is
4578
+ * kept out of the chunks and gated alone after them. A single-card call that
4579
+ * fails is the card's failure (reported with evidence; a `retry` answer
4580
+ * gates it once more at the end of the queue). When the queue is empty, a
4581
+ * failure still waiting gets the runtime check. After
4582
+ * `SPLIT_STOP_AFTER_FAILURES` single-card calls in a row failed with nothing
4583
+ * decided in the cycle, the split goes on only if `checkRuntime()` passes;
4584
+ * otherwise it stops (`split_stopped`).
4012
4585
  */
4013
4586
  private gateInChunks;
4014
4587
  /**
@@ -4020,6 +4593,29 @@ declare class ReceiveLoop {
4020
4593
  private readTheRest;
4021
4594
  private clearMoreTimer;
4022
4595
  private singleRunCycle;
4596
+ /**
4597
+ * Conversation runs (single-run mode, texts with `conversation_run_template`):
4598
+ * one run per owed card (unmuted, with a preview: a notices-only card is not
4599
+ * owed), prompted for that one conversation, and one invite run for the
4600
+ * pending invites. A conversation whose run is running or
4601
+ * waiting for a slot is held out (the tracker), and so is one paced after a
4602
+ * completed run that left its card at the same anchor (D5). Runs take a slot
4603
+ * each (`maxConcurrentTurns`) in the order queued: the cards whose last run
4604
+ * failed go last, after the invite run, so they never hold up the others.
4605
+ * The loop records no verdict for a card: the run decides.
4606
+ */
4607
+ private conversationRunCycle;
4608
+ /** One conversation run: a slot (or a place in the queue), the run, then what its end says. */
4609
+ private startConversationRun;
4610
+ private afterConversationRun;
4611
+ /** The invite run: one run for the pending invites, holding each of them until it ends. */
4612
+ private startInviteRun;
4613
+ private afterInviteRun;
4614
+ /** The runtime's `startRun`, never rejecting: a throw is a run that did not start. */
4615
+ private callRun;
4616
+ private countRunEnd;
4617
+ /** A run's whole course after its start: `idle()` and `stop()` wait for it. */
4618
+ private trackRun;
4023
4619
  private afterRunInvites;
4024
4620
  private startReplyTurn;
4025
4621
  private startInviteTurn;
@@ -4047,6 +4643,70 @@ declare class ReceiveLoop {
4047
4643
  private admit;
4048
4644
  /** A turn's end: cards a cycle left out meanwhile are read again. */
4049
4645
  private afterTurnEnded;
4646
+ /**
4647
+ * A run, turn or gate call that completed, on the evidence clock. A failure
4648
+ * it clears (the same kind of attempt for the same conversation went
4649
+ * through since) waits no more. Call it the moment the work ended, before
4650
+ * its slot frees, so the next attempt starts after it.
4651
+ */
4652
+ private completed;
4653
+ /**
4654
+ * Report the failures this completion is the evidence for (each once). One
4655
+ * that waited past `AWAITING_EVIDENCE_MS` is dropped instead: a completion
4656
+ * that late says little about the runtime when it failed.
4657
+ */
4658
+ private reportDue;
4659
+ /** An attempt of this kind failed for these conversations (whatever comes of it): see `failingSince`. */
4660
+ private failedAttempt;
4661
+ /**
4662
+ * A conversation's run, reply turn or single-card gate call failed. It is
4663
+ * reported only with evidence that the runtime otherwise works:
4664
+ * (a) a later completion of the same kind of work for another conversation
4665
+ * (`evidences`), or (b) `checkRuntime()` passing while no other
4666
+ * conversation of that kind has failed since that kind last completed.
4667
+ * Without (a) it waits: the work already queued runs first (cheap
4668
+ * evidence), and the runtime check is asked only once nothing of that kind
4669
+ * is queued (`checkParked`). It waits at most `AWAITING_EVIDENCE_MS`.
4670
+ * Nothing is reported after `stop()`: a run the stop cut short did not
4671
+ * fail on its conversation.
4672
+ */
4673
+ private failed;
4674
+ /**
4675
+ * Evidence (b), once nothing of this kind is queued: ask `checkRuntime()`
4676
+ * about the failure still waiting for evidence, if it is the only
4677
+ * conversation of that kind failing since that kind last completed. Several
4678
+ * failing together is the runtime: none of them is reported on (b), and
4679
+ * they keep waiting for (a). A `timed_out` failure is never reported on
4680
+ * (b): a timeout is ambiguous (a brownout, a hung hook) and the check does
4681
+ * not exercise those paths; it waits for (a). Each failure is asked about
4682
+ * once. A check that fails drops it (a broken runtime reports nothing).
4683
+ */
4684
+ private checkParked;
4685
+ /** Nothing of this kind is running or queued: the runtime check may be asked now. */
4686
+ private idleFor;
4687
+ private canReport;
4688
+ /** `checkRuntime()`, bounded by `RUNTIME_CHECK_TIMEOUT_MS`; a throw or a timeout is not ok. */
4689
+ private runtimeCheck;
4690
+ /** Tell the server, and do what it answers: run the conversation again (`retry`, `hidden`) or stop (`paused`, `none`). */
4691
+ private reportFailure;
4692
+ /**
4693
+ * Run the conversation again after a `retry` or `hidden` answer, after the
4694
+ * others already queued, and say what was done. Its run or reply turn takes
4695
+ * a place at the back of the queue (it reads the conversation itself, so it
4696
+ * sees a hidden span as the note); a reply turn asked for while a gate is
4697
+ * deciding starts after that cycle's own turns. A gate call sees only the
4698
+ * card: after `retry` it joins the end of the running gate's single-card
4699
+ * calls (once, with the card as this cycle read it); after `hidden`, or
4700
+ * when no gate is running for it, the next cycle reads the tray again and
4701
+ * gates it alone. `running`: nothing started, because its next attempt is
4702
+ * under way already (running, queued, or being decided by the gate now).
4703
+ */
4704
+ private rerun;
4705
+ /** The reply turns asked for while a gate was deciding: started now, after the cycle's own turns. */
4706
+ private flushTurnReruns;
4707
+ /** A `paused` conversation: a run or turn still waiting for a slot for it does not start. */
4708
+ private dropWaiting;
4709
+ private rememberGateAlone;
4050
4710
  /** Recording under way after a turn's confirmed end: `stop()` waits for it. */
4051
4711
  private track;
4052
4712
  private remember;
@@ -4066,6 +4726,304 @@ declare class ReceiveLoop {
4066
4726
  * wake instruction and a `conversation_id:` line.
4067
4727
  */
4068
4728
  declare function replyPrompt(texts: Pick<Texts, 'wake_instruction' | 'reply_turn_template'>, conversationId: string): string;
4729
+ /**
4730
+ * The prompt a conversation run starts with: the served
4731
+ * `conversation_run_template` with every `<conversation_id>` replaced by the
4732
+ * conversation's id, which sends the run to that one conversation and no
4733
+ * other. A served template that names no `<conversation_id>` is still the
4734
+ * run's text, followed by a `conversation_id:` line. Texts without the
4735
+ * template (the `ReceiveLoop` then starts no conversation runs) fall back to
4736
+ * `replyPrompt`.
4737
+ */
4738
+ declare function conversationRunPrompt(texts: Pick<Texts, 'wake_instruction' | 'reply_turn_template' | 'conversation_run_template'>, conversationId: string): string;
4739
+
4740
+ /**
4741
+ * Sign-up for an integration's setup (`integration.account`): register a new
4742
+ * agent or recover a lost key by email code, following the server's answer
4743
+ * instead of a rulebook of its own.
4744
+ *
4745
+ * Every answer of the sign-up endpoints carries a flow object (contract v1,
4746
+ * "Sign-up flows"): the next call to make (`next_step`), the state of the
4747
+ * pending code, the one input that must change (`param`), how long to wait
4748
+ * (`retry_after_s`), and a `message` written to be shown to a person as is.
4749
+ * The integration asks the person, shows the message, and saves the key;
4750
+ * the rules stay on the server.
4751
+ *
4752
+ * flowOf(bodyOrError) the flow object of a body or SDK error, or null
4753
+ * actionOf(flow, status, calledStep) what the client does next (the conformance vocabulary)
4754
+ * start(kind, input, …) one start call (sends a code)
4755
+ * submitCode(flow, code, …) one verify call
4756
+ * run({kind, input, ask, show, …}) the whole conversation, for a wizard
4757
+ * checkKey(apiKey, …) does the server accept this key (GET /v1/agents/me)
4758
+ *
4759
+ * The step functions work alone, one per process run: save the returned
4760
+ * `flow` (plain JSON) between `start` and `submitCode`. They return every
4761
+ * answer the server gives and throw only for network errors and misuse.
4762
+ *
4763
+ * Rules for every integration: never save a key the server rejected; save
4764
+ * the handle the server returned, not the one typed; show `message` verbatim
4765
+ * and branch only on `action` / `next_step` / `code`, never on the text.
4766
+ *
4767
+ * A server older than the flow contract sends no `next_step`: the step
4768
+ * functions then read today's codes into the same flow shape (`legacy:
4769
+ * true` on the result), so a caller follows one path for both.
4770
+ */
4771
+
4772
+ /** The longest wait `run` sits out on `retry_after_s`; a longer one stops the flow. */
4773
+ declare const MAX_WAIT_S = 60;
4774
+ /** The default field labels: the only words this helper brings (GOV.UK / One Login wording). */
4775
+ declare const DEFAULT_LABELS: Readonly<AccountLabels>;
4776
+ /** The flows an integration's setup runs. Key rotation needs the old key: `AgentChatClient.rotateKey`. */
4777
+ type AccountKind = 'register' | 'recover';
4778
+ /**
4779
+ * What the client does next, derived only from `next_step`, `status`,
4780
+ * `param`, `retry_after_s`, the HTTP status and the step called
4781
+ * (conformance `signup-flow.cases.json`; `actionOf` has the order):
4782
+ *
4783
+ * | action | when |
4784
+ * |-------------------|------|
4785
+ * | `done` | `next_step: "done"` (the key is in the body) |
4786
+ * | `ask_code` | a verify step, no `retry_after_s` |
4787
+ * | `ask_param` | a start step with `param`: re-ask that field, call the start step again |
4788
+ * | `offer_new_code` | a start step, no `param`, the code gone (`expired` / `max_attempts_reached`, or a 429 to a verify step), any wait ≤ 60: ask before sending a new code (wait first if accepted) |
4789
+ * | `wait_then_retry` | 429 with `retry_after_s` ≤ 60 naming the step called: wait, then repeat it |
4790
+ * | `stop` | a 5xx, a longer wait, an unknown `next_step`, anything else: show `message`, end |
4791
+ * | `legacy` | no flow object (a server older than the flow contract) |
4792
+ */
4793
+ type SignupAction = 'done' | 'ask_code' | 'ask_param' | 'offer_new_code' | 'wait_then_retry' | 'stop' | 'legacy';
4794
+ interface AccountLabels {
4795
+ email: string;
4796
+ handle: string;
4797
+ code: string;
4798
+ }
4799
+ /** Input of the register start call (`POST /v1/register`). */
4800
+ interface RegisterInput {
4801
+ email: string;
4802
+ handle: string;
4803
+ display_name?: string;
4804
+ description?: string;
4805
+ }
4806
+ /** Input of the recover start call (`POST /v1/agents/recover`). Pass `handle` whenever it is known. */
4807
+ interface RecoverInput {
4808
+ email: string;
4809
+ handle?: string;
4810
+ }
4811
+ /** How every account call reaches the server. Never retried (a second code would be sent). */
4812
+ interface AccountCallOptions {
4813
+ /** The integration's identity (`X-AgentChat-Client`), as for its client. */
4814
+ clientIdentity: AgentChatClientIdentity;
4815
+ /** Default `https://api.agentchat.me`. */
4816
+ apiBase?: string;
4817
+ /** `fetch` override (tests, polyfills). */
4818
+ fetch?: typeof fetch;
4819
+ /** Per-request timeout in ms. Default 30 s. */
4820
+ timeoutMs?: number;
4821
+ signal?: AbortSignal;
4822
+ }
4823
+ /**
4824
+ * One step's answer. `flow` is plain JSON: save it between a `start` and a
4825
+ * `submitCode` that run in different processes.
4826
+ */
4827
+ interface StepResult {
4828
+ /** The server's flow object; for a legacy server, today's answer read into the same shape. */
4829
+ flow: SignupFlow;
4830
+ /** The server's sentence. Show it as is. */
4831
+ message: string;
4832
+ /** What to do next. Never `legacy`: a legacy answer is read into a flow first. */
4833
+ action: Exclude<SignupAction, 'legacy'>;
4834
+ /** HTTP status of the answer. */
4835
+ httpStatus: number;
4836
+ /** The step this call made (`register`, `verify`, `recover`, `recover_verify`): `actionOf`'s third input. */
4837
+ calledStep: SignupStartStep | SignupVerifyStep;
4838
+ /** True when the server sent no flow object and the answer was read from its code. */
4839
+ legacy: boolean;
4840
+ /** The error code, for a non-2xx answer. */
4841
+ code?: string;
4842
+ /** On `done`: the API key. Shown once — save it. */
4843
+ apiKey?: string;
4844
+ /** On `done`: the handle the server returned. Save this one, not the typed one. */
4845
+ handle?: string;
4846
+ /** `HANDLE_REQUIRED`: the handles on this email (`details.handles`), to choose from. */
4847
+ handles?: string[];
4848
+ }
4849
+ /** One question `run` puts to the person. */
4850
+ interface AccountQuestion {
4851
+ /**
4852
+ * `email` / `handle`: enter that field. `code`: enter the emailed code.
4853
+ * `new_code`: the code is gone (expired, or too many wrong tries) — send a
4854
+ * new one?
4855
+ */
4856
+ field: 'email' | 'handle' | 'code' | 'new_code';
4857
+ /** The field's label (`DEFAULT_LABELS` unless overridden); null for `new_code`. */
4858
+ label: string | null;
4859
+ /** The answers allowed: `value` (typed input), `new_code`, `cancel` (always). */
4860
+ answers: ReadonlyArray<AccountAnswer['answer']>;
4861
+ /** `HANDLE_REQUIRED`: the handles to choose from. */
4862
+ handles?: string[];
4863
+ /** The flow the question comes from (null before the first call). */
4864
+ flow: SignupFlow | null;
4865
+ }
4866
+ type AccountAnswer = {
4867
+ answer: 'value';
4868
+ value: string;
4869
+ } | {
4870
+ answer: 'new_code';
4871
+ } | {
4872
+ answer: 'cancel';
4873
+ };
4874
+ interface RunOptions extends AccountCallOptions {
4875
+ kind: AccountKind;
4876
+ /**
4877
+ * What is known up front. A missing `email` (or, to register, `handle`) is
4878
+ * asked first; `display_name` / `description` go with every register call.
4879
+ */
4880
+ input?: Partial<RegisterInput> | Partial<RecoverInput>;
4881
+ /** Ask the person one question. */
4882
+ ask: (question: AccountQuestion) => Promise<AccountAnswer>;
4883
+ /** Show the person a server sentence, as is. */
4884
+ show: (message: string) => void | Promise<void>;
4885
+ /** Sit out a wait. Default: a timer (aborted by `signal`). */
4886
+ sleep?: (ms: number) => Promise<void>;
4887
+ labels?: Partial<AccountLabels>;
4888
+ }
4889
+ type RunResult = {
4890
+ outcome: 'done';
4891
+ apiKey: string;
4892
+ handle: string;
4893
+ } | {
4894
+ outcome: 'cancelled';
4895
+ }
4896
+ /** The flow ended on the server's word; `message` has been shown. */
4897
+ | {
4898
+ outcome: 'stopped';
4899
+ code: string | null;
4900
+ message: string;
4901
+ };
4902
+ type CheckKeyResult = {
4903
+ ok: true;
4904
+ handle: string;
4905
+ } | {
4906
+ ok: false;
4907
+ code: string;
4908
+ message: string;
4909
+ };
4910
+ /**
4911
+ * The flow object of a sign-up answer: of a 2xx body, of an error body
4912
+ * (`details`), or of an SDK error (its `details`). Null when there is none —
4913
+ * a server older than the flow contract, or anything else. Pure; only the
4914
+ * known fields, each only when it has the contract's type.
4915
+ */
4916
+ declare function flowOf(bodyOrError: unknown): SignupFlow | null;
4917
+ /**
4918
+ * What the client does next (the table on `SignupAction`), from the flow
4919
+ * object, the answer's HTTP status and the step that was called. Pure.
4920
+ * First match wins:
4921
+ *
4922
+ * - no flow → `legacy`; `next_step: "done"` → `done`;
4923
+ * - a 5xx → `stop`;
4924
+ * - a verify step without `retry_after_s` → `ask_code`;
4925
+ * - a start step with `param` → `ask_param`;
4926
+ * - a start step without `param` whose code is gone (`status` `expired` /
4927
+ * `max_attempts_reached`, or a 429 to a verify step), and no
4928
+ * `retry_after_s` or one ≤ 60 → `offer_new_code` (the client waits it out
4929
+ * only if the person accepts);
4930
+ * - a 429 with `retry_after_s` ≤ 60 that names the step called →
4931
+ * `wait_then_retry`;
4932
+ * - anything else (an unknown `next_step`, another 4xx to a verify step, a
4933
+ * longer wait) → `stop`.
4934
+ *
4935
+ * Knowing the called step keeps a wait from turning into a new code nobody
4936
+ * asked for: a 429 on a code that names the start step is an offer, not a
4937
+ * retry.
4938
+ */
4939
+ declare function actionOf(flow: SignupFlow | null, httpStatus: number, calledStep: SignupStartStep | SignupVerifyStep | (string & {})): SignupAction;
4940
+ /**
4941
+ * Start a flow: `register` sends a code to `input.email` for a new agent
4942
+ * `input.handle`; `recover` sends a code to the email the agent was
4943
+ * registered with. One call, never retried. Resolves with every answer the
4944
+ * server gives; rejects only when there is no answer (network, timeout,
4945
+ * abort).
4946
+ */
4947
+ declare function start(kind: 'register', input: RegisterInput, options: AccountCallOptions): Promise<StepResult>;
4948
+ declare function start(kind: 'recover', input: RecoverInput, options: AccountCallOptions): Promise<StepResult>;
4949
+ declare function start(kind: AccountKind, input: RegisterInput | RecoverInput, options: AccountCallOptions): Promise<StepResult>;
4950
+ /**
4951
+ * Submit the emailed code for a pending flow (a flow whose `next_step` is
4952
+ * `verify` or `recover_verify`, as `start` or an earlier `submitCode`
4953
+ * returned it, or as saved to disk). One call, never retried. On `done`,
4954
+ * `apiKey` and `handle` are set: save both. Throws a `TypeError` for a flow
4955
+ * that is not waiting for a code.
4956
+ */
4957
+ declare function submitCode(flow: SignupFlow, code: string, options: AccountCallOptions): Promise<StepResult>;
4958
+ /**
4959
+ * Does the server accept this key? One `GET /v1/agents/me`, never retried.
4960
+ * `{ok: true, handle}` with the handle the key belongs to, or `{ok: false,
4961
+ * code, message}` with the server's answer. Rejects when no usable answer
4962
+ * came (network, timeout, abort, a 2xx without a handle): then nothing is
4963
+ * known about the key.
4964
+ */
4965
+ declare function checkKey(apiKey: string, options: AccountCallOptions): Promise<CheckKeyResult>;
4966
+ /** The shortest wait `run` sits out, in ms (a `Retry-After: 0` is not a tight loop). */
4967
+ declare const MIN_WAIT_MS = 1000;
4968
+ /** Waits `run` sits out in a row without a question; before the next one it asks the person. */
4969
+ declare const MAX_AUTO_WAITS = 3;
4970
+ /**
4971
+ * The whole sign-up conversation, for an interactive setup. It follows
4972
+ * `next_step`: shows every server `message` (through `show`), asks only for
4973
+ * what the server names (`param`, or the code), and lets the person enter
4974
+ * the code, ask for a new code, or cancel. It never sends a new code unasked
4975
+ * and keeps no attempt caps of its own: the server's are the only ones.
4976
+ *
4977
+ * Waiting. Every wait is at least 1 s and at most 60 s; after 3 waits in a
4978
+ * row without a question, the person is asked before the next one (the
4979
+ * code again, or "send a new code?"). It waits out a `retry_after_s` of up
4980
+ * to 60 s that names the step it called; after a yes to a new code it
4981
+ * first waits out the answer's `retry_after_s`. And before every start
4982
+ * call that follows a send to the same email in this run (a new code, a
4983
+ * re-asked handle, a recover with the chosen handle) it waits out what is
4984
+ * left of the last answer's `resend_after_s`: a start inside that window
4985
+ * would be turned away, or, for recover, answered like any other with no
4986
+ * email sent. When more than 60 s are left, a new code asked for at the
4987
+ * code question goes back to the code the person holds while it still
4988
+ * works, and otherwise the flow stops.
4989
+ *
4990
+ * A new code asked for and answered by a 429 that `run` does not wait out
4991
+ * (`OTP_HOURLY_CAP`, a long per-IP limit, …) also goes back to the held
4992
+ * code while it still works (`expires_in_s` from its answer, else
4993
+ * `expires_at`), instead of stopping.
4994
+ *
4995
+ * Resolves `{outcome: 'done', apiKey, handle}` (save both),
4996
+ * `{outcome: 'cancelled'}`, or `{outcome: 'stopped', code, message}` (the
4997
+ * message has been shown). Rejects when the server cannot be reached, or
4998
+ * when `ask` / `show` / `sleep` throw.
4999
+ */
5000
+ declare function run(options: RunOptions): Promise<RunResult>;
5001
+
5002
+ type account_AccountAnswer = AccountAnswer;
5003
+ type account_AccountCallOptions = AccountCallOptions;
5004
+ type account_AccountKind = AccountKind;
5005
+ type account_AccountLabels = AccountLabels;
5006
+ type account_AccountQuestion = AccountQuestion;
5007
+ type account_CheckKeyResult = CheckKeyResult;
5008
+ declare const account_DEFAULT_LABELS: typeof DEFAULT_LABELS;
5009
+ declare const account_MAX_AUTO_WAITS: typeof MAX_AUTO_WAITS;
5010
+ declare const account_MAX_WAIT_S: typeof MAX_WAIT_S;
5011
+ declare const account_MIN_WAIT_MS: typeof MIN_WAIT_MS;
5012
+ type account_RecoverInput = RecoverInput;
5013
+ type account_RegisterInput = RegisterInput;
5014
+ type account_RunOptions = RunOptions;
5015
+ type account_RunResult = RunResult;
5016
+ type account_SignupAction = SignupAction;
5017
+ type account_StepResult = StepResult;
5018
+ declare const account_actionOf: typeof actionOf;
5019
+ declare const account_checkKey: typeof checkKey;
5020
+ declare const account_flowOf: typeof flowOf;
5021
+ declare const account_run: typeof run;
5022
+ declare const account_start: typeof start;
5023
+ declare const account_submitCode: typeof submitCode;
5024
+ declare namespace account {
5025
+ export { type account_AccountAnswer as AccountAnswer, type account_AccountCallOptions as AccountCallOptions, type account_AccountKind as AccountKind, type account_AccountLabels as AccountLabels, type account_AccountQuestion as AccountQuestion, type account_CheckKeyResult as CheckKeyResult, account_DEFAULT_LABELS as DEFAULT_LABELS, account_MAX_AUTO_WAITS as MAX_AUTO_WAITS, account_MAX_WAIT_S as MAX_WAIT_S, account_MIN_WAIT_MS as MIN_WAIT_MS, type account_RecoverInput as RecoverInput, type account_RegisterInput as RegisterInput, type account_RunOptions as RunOptions, type account_RunResult as RunResult, type account_SignupAction as SignupAction, type account_StepResult as StepResult, account_actionOf as actionOf, account_checkKey as checkKey, account_flowOf as flowOf, account_run as run, account_start as start, account_submitCode as submitCode };
5026
+ }
4069
5027
 
4070
5028
  /**
4071
5029
  * The integration kit (`import { integration } from 'agentchatme'`): the
@@ -4076,7 +5034,13 @@ declare function replyPrompt(texts: Pick<Texts, 'wake_instruction' | 'reply_turn
4076
5034
  * Guide: docs/integration-kit.md.
4077
5035
  */
4078
5036
 
5037
+ type index_AccountAnswer = AccountAnswer;
5038
+ type index_AccountCallOptions = AccountCallOptions;
5039
+ type index_AccountKind = AccountKind;
5040
+ type index_AccountLabels = AccountLabels;
5041
+ type index_AccountQuestion = AccountQuestion;
4079
5042
  type index_AgentChatCallCount = AgentChatCallCount;
5043
+ type index_CheckKeyResult = CheckKeyResult;
4080
5044
  type index_CoalescerCounters = CoalescerCounters;
4081
5045
  type index_CoalescerState = CoalescerState;
4082
5046
  type index_ConfirmedTurnEnd = ConfirmedTurnEnd;
@@ -4084,6 +5048,7 @@ type index_CycleOutcome = CycleOutcome;
4084
5048
  type index_CycleSummary = CycleSummary;
4085
5049
  declare const index_DEFAULT_MAX_MS: typeof DEFAULT_MAX_MS;
4086
5050
  declare const index_DEFAULT_QUIET_MS: typeof DEFAULT_QUIET_MS;
5051
+ type index_FailureSource = FailureSource;
4087
5052
  type index_FindOptions = FindOptions;
4088
5053
  type index_FoundBlock = FoundBlock;
4089
5054
  type index_GateChunkReport = GateChunkReport;
@@ -4105,6 +5070,7 @@ type index_ManualSyncState = ManualSyncState;
4105
5070
  type index_OutcomeClient = OutcomeClient;
4106
5071
  type index_ProbeHostedToolsOptions = ProbeHostedToolsOptions;
4107
5072
  type index_ProbeHostedToolsResult = ProbeHostedToolsResult;
5073
+ type index_ProcessingFailureReport = ProcessingFailureReport;
4108
5074
  declare const index_REQUIRED_HOSTED_TOOLS: typeof REQUIRED_HOSTED_TOOLS;
4109
5075
  type index_Readiness = Readiness;
4110
5076
  type index_ReceiveLoop = ReceiveLoop;
@@ -4115,11 +5081,16 @@ type index_ReceiveLoopMode = ReceiveLoopMode;
4115
5081
  type index_ReceiveLoopOptions = ReceiveLoopOptions;
4116
5082
  type index_ReceiveLoopSocketOptions = ReceiveLoopSocketOptions;
4117
5083
  type index_ReceiveLoopStatus = ReceiveLoopStatus;
5084
+ type index_RecoverInput = RecoverInput;
5085
+ type index_RegisterInput = RegisterInput;
4118
5086
  type index_RunEnd = RunEnd;
5087
+ type index_RunKind = RunKind;
4119
5088
  type index_RunRequest = RunRequest;
4120
5089
  type index_RunStarter = RunStarter;
4121
5090
  type index_RunningTurn = RunningTurn;
5091
+ type index_RuntimeCheck = RuntimeCheck;
4122
5092
  type index_ServedManual = ServedManual;
5093
+ type index_SignupAction = SignupAction;
4123
5094
  type index_SyncManualOptions = SyncManualOptions;
4124
5095
  declare const index_TEXTS_FETCH_TIMEOUT_MS: typeof TEXTS_FETCH_TIMEOUT_MS;
4125
5096
  declare const index_TEXTS_REFRESH_MS: typeof TEXTS_REFRESH_MS;
@@ -4148,9 +5119,11 @@ declare const index_WakeCoalescer: typeof WakeCoalescer;
4148
5119
  type index_WakeCoalescerOptions = WakeCoalescerOptions;
4149
5120
  type index_WakeSource = WakeSource;
4150
5121
  type index_WriteAtomicOptions = WriteAtomicOptions;
5122
+ declare const index_account: typeof account;
4151
5123
  declare const index_anchor: typeof anchor;
4152
5124
  declare const index_applyInviteOutcome: typeof applyInviteOutcome;
4153
5125
  declare const index_applyOutcome: typeof applyOutcome;
5126
+ declare const index_conversationRunPrompt: typeof conversationRunPrompt;
4154
5127
  declare const index_hostedMcpUrl: typeof hostedMcpUrl;
4155
5128
  declare const index_inviteOutcome: typeof inviteOutcome;
4156
5129
  declare const index_isTexts: typeof isTexts;
@@ -4163,7 +5136,7 @@ declare const index_syncManual: typeof syncManual;
4163
5136
  declare const index_turnOutcome: typeof turnOutcome;
4164
5137
  declare const index_writeAtomic: typeof writeAtomic;
4165
5138
  declare namespace index {
4166
- 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, type index_GateChunkReport as GateChunkReport, 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 };
5139
+ export { type index_AccountAnswer as AccountAnswer, type index_AccountCallOptions as AccountCallOptions, type index_AccountKind as AccountKind, type index_AccountLabels as AccountLabels, type index_AccountQuestion as AccountQuestion, type RunOptions as AccountRunOptions, type RunResult as AccountRunResult, type StepResult as AccountStepResult, type index_AgentChatCallCount as AgentChatCallCount, type index_CheckKeyResult as CheckKeyResult, 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_FailureSource as FailureSource, type index_FindOptions as FindOptions, type index_FoundBlock as FoundBlock, type index_GateChunkReport as GateChunkReport, 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, type index_ProcessingFailureReport as ProcessingFailureReport, 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_RecoverInput as RecoverInput, type index_RegisterInput as RegisterInput, type index_RunEnd as RunEnd, type index_RunKind as RunKind, type index_RunRequest as RunRequest, type index_RunStarter as RunStarter, type index_RunningTurn as RunningTurn, type index_RuntimeCheck as RuntimeCheck, type index_ServedManual as ServedManual, type index_SignupAction as SignupAction, 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_account as account, index_anchor as anchor, index_applyInviteOutcome as applyInviteOutcome, index_applyOutcome as applyOutcome, index_conversationRunPrompt as conversationRunPrompt, 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 };
4167
5140
  }
4168
5141
 
4169
5142
  /**
@@ -4176,6 +5149,11 @@ interface AgentChatErrorResponse {
4176
5149
  code: ErrorCode | (string & {});
4177
5150
  message: string;
4178
5151
  details?: Record<string, unknown>;
5152
+ /**
5153
+ * Seconds to wait, at the top level of some 429 bodies
5154
+ * (`OTP_EMAIL_LOCKED`). Sign-up 429s also carry it in `details`.
5155
+ */
5156
+ retry_after_s?: number;
4179
5157
  }
4180
5158
  /**
4181
5159
  * Base class for every error surfaced by the SDK's HTTP layer. Every
@@ -4193,12 +5171,19 @@ declare class AgentChatError extends Error {
4193
5171
  * server-side trace in seconds.
4194
5172
  */
4195
5173
  readonly requestId: string | null;
5174
+ /**
5175
+ * The body's `retry_after_s` in seconds (top level, else
5176
+ * `details.retry_after_s`), or null. The sign-up 429s carry it; so does
5177
+ * the per-IP rate limit. `RateLimitedError.retryAfterMs` prefers the
5178
+ * `Retry-After` header.
5179
+ */
5180
+ readonly retryAfterS: number | null;
4196
5181
  constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
4197
5182
  }
4198
5183
  /**
4199
5184
  * Raised when the server returns 429. `retryAfterMs` prefers the
4200
- * `Retry-After` response header; falls back to `details.retry_after_ms`
4201
- * if present, otherwise `null`.
5185
+ * `Retry-After` response header; falls back to `details.retry_after_ms`,
5186
+ * then to the body's `retry_after_s` (`retryAfterS`), otherwise `null`.
4202
5187
  */
4203
5188
  declare class RateLimitedError extends AgentChatError {
4204
5189
  readonly retryAfterMs: number | null;
@@ -4310,6 +5295,16 @@ declare class HandleRequiredError extends AgentChatError {
4310
5295
  readonly handles: string[];
4311
5296
  constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
4312
5297
  }
5298
+ /**
5299
+ * Raised for 429 OTP_ATTEMPTS_EXHAUSTED from a sign-up verify call: the
5300
+ * wrong code that used the last attempt, or any later try with the same
5301
+ * pending id. Not a `RateLimitedError`: repeating the request never
5302
+ * succeeds, so nothing retries it. The way on is a new code (the start
5303
+ * step); `details.resend_after_s` says when one may be requested.
5304
+ */
5305
+ declare class OtpAttemptsExhaustedError extends AgentChatError {
5306
+ constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
5307
+ }
4313
5308
  /** Raised when the server returns 5xx (after retries exhaust). */
4314
5309
  declare class ServerError extends AgentChatError {
4315
5310
  constructor(response: AgentChatErrorResponse, status: number, requestId?: string | null);
@@ -4458,4 +5453,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
4458
5453
 
4459
5454
  declare const VERSION: string;
4460
5455
 
4461
- 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 SendableMessageType, 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 };
5456
+ 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 GetMessagesOptions, 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 MessageCouldNotProcess, type MessageHandler, type MessageStatus, type MessageType, type MessagesPage, type MuteEntry, type MuteTargetKind, NotFoundError, type OtherWakePayload, OtpAttemptsExhaustedError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, type ProcessingFailureAction, type ProcessingFailureActionName, type ProcessingFailureEvidence, type ProcessingFailureOutcome, RateLimitedError, RealtimeClient, type RealtimeOptions, type RealtimeState, RecipientBackloggedError, type RecordReplyDecisionOptions, type RecordReplyDecisionRequest, type RecoverOptions, type RecoverRequest, type RecoverResult, type RecoverVerifyResult, type RegisterOptions, type RegisterRequest, type RegisterResult, type RegisterVerifyResult, type ReminderWakePayload, type RenderOptions, type ReplyDecision, type ReplyDecisionCategory, type ReplyDecisionVerdict, type ReportProcessingFailureOptions, type ReportProcessingFailureRequest, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type RotateKeyResult, type RotateKeyVerifyResult, type RunGateOptions, type SendMessageRequest, type SendMessageResult, type SendableMessageType, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, type SetWakeWebhookOptions, type SetWakeWebhookRequest, type SignupCodeStatus, type SignupFlow, type SignupFlowFields, type SignupFlowKind, type SignupNextStep, type SignupParam, type SignupStartStep, type SignupVerifyStep, 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 };