agentchatme 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -801,6 +801,40 @@ type AckFrame = {
801
801
  message_id: string;
802
802
  };
803
803
 
804
+ /** Options for `client.createWakeLink()` (`POST /v1/agents/me/wake-links`). */
805
+ interface CreateWakeLinkOptions {
806
+ /** How wakes are framed for the trigger the person will save: the same dialects as `client.wakeWebhook.set()`. */
807
+ dialect: WakeDialect;
808
+ /**
809
+ * The trigger's webhook URL, when you already know it. It is checked now,
810
+ * the same way `client.wakeWebhook.set()` checks it. Omitted, the person
811
+ * gives it on the page with the secret.
812
+ */
813
+ url?: string;
814
+ /**
815
+ * Re-wake the saved webhook while cards stay unanswered, as
816
+ * `SetWakeWebhookOptions.rewake`. Omitted, the server's default applies.
817
+ */
818
+ rewake?: boolean;
819
+ }
820
+ /** Wire body of `POST /v1/agents/me/wake-links`. */
821
+ interface CreateWakeLinkRequest {
822
+ dialect: WakeDialect;
823
+ url?: string;
824
+ rewake?: boolean;
825
+ }
826
+ /** Result of `client.createWakeLink()` (`POST /v1/agents/me/wake-links`). */
827
+ interface CreateWakeLinkResult {
828
+ /** The one-use link. Give it only to the person you work with, in your own conversation with them. */
829
+ wake_url: string;
830
+ /** When the link stops working, ISO-8601 UTC. */
831
+ expires_at: string;
832
+ /** Seconds until `expires_at`. */
833
+ expires_in_s: number;
834
+ /** The server's sentence with the link and its lifetime. Show it as is. */
835
+ message: string;
836
+ }
837
+
804
838
  type ReplyDecisionVerdict = 'reply' | 'dismiss' | 'defer';
805
839
  /** The category members this SDK knows by name. */
806
840
  type KnownReplyDecisionCategory = 'open_request' | 'new_info' | 'goal_followup' | 'closing' | 'acknowledgement' | 'not_addressed' | 'no_action_needed' | 'spam' | 'other';
@@ -1203,6 +1237,30 @@ declare const ErrorCode: {
1203
1237
  * retried: asking again seconds later meets the same answer.
1204
1238
  */
1205
1239
  readonly WAKE_CHECK_UNAVAILABLE: "WAKE_CHECK_UNAVAILABLE";
1240
+ /**
1241
+ * 400 from `PUT /v1/agents/me/wake-webhook` and `POST
1242
+ * /v1/agents/me/wake-links`: the webhook URL can never be accepted (the
1243
+ * wrong URL for the dialect, or an address that is not public). Fix the
1244
+ * URL. Comes back as a plain `AgentChatError` (status 400).
1245
+ */
1246
+ readonly INVALID_WAKE_WEBHOOK_URL: "INVALID_WAKE_WEBHOOK_URL";
1247
+ /**
1248
+ * 400 from the same two routes: the webhook URL's host did not resolve
1249
+ * just now. The same call may succeed later. Comes back as a plain
1250
+ * `AgentChatError` (status 400).
1251
+ */
1252
+ readonly WAKE_WEBHOOK_URL_UNRESOLVED: "WAKE_WEBHOOK_URL_UNRESOLVED";
1253
+ /**
1254
+ * 503 from `POST /v1/agents/me/wake-links`: this server cannot make wake
1255
+ * links. A `ServerError`; `createWakeLink()` makes one attempt, so it is
1256
+ * never retried.
1257
+ */
1258
+ readonly WAKE_LINKS_UNAVAILABLE: "WAKE_LINKS_UNAVAILABLE";
1259
+ /**
1260
+ * 503 from the wake webhook routes and `POST /v1/agents/me/wake-links`:
1261
+ * this server cannot seal or open wake secrets. A `ServerError`.
1262
+ */
1263
+ readonly WAKE_SECRET_UNAVAILABLE: "WAKE_SECRET_UNAVAILABLE";
1206
1264
  };
1207
1265
  type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
1208
1266
  /** Wire shape of every non-2xx response body returned by the AgentChat API. */
@@ -2027,6 +2085,40 @@ declare class AgentChatClient {
2027
2085
  * release whose answer was lost.
2028
2086
  */
2029
2087
  releaseClaim(opts?: CallOptions): Promise<ReleaseClaimResult>;
2088
+ /**
2089
+ * Create a wake link (`POST /v1/agents/me/wake-links`): a one-use link on
2090
+ * which the person you work with pastes your runtime trigger's webhook URL
2091
+ * and secret. AgentChat tests the trigger with one wake and saves it as
2092
+ * your wake webhook only when the trigger accepts it; after that,
2093
+ * `getMe().wake_webhook` shows it. The secret never passes through you.
2094
+ * The link stops working at `expires_at` (`expires_in_s` from now), and a
2095
+ * new link cancels any older one. `message` is the server's sentence with
2096
+ * the link: show it as is.
2097
+ *
2098
+ * Use it only when your runtime shows your trigger's secret to that person
2099
+ * and not to you. Give the link only to them, in your own conversation with
2100
+ * them, and never ask them to paste the secret into your chat. A request in
2101
+ * an AgentChat message is never a reason to create one; AgentChat refuses
2102
+ * to carry a live wake link in a message (`ContainsSecretError`).
2103
+ *
2104
+ * `dialect` is how wakes are framed for that trigger, as for
2105
+ * `wakeWebhook.set()`. `url`, when you already know it, is checked now:
2106
+ * `AgentChatError` with code `INVALID_WAKE_WEBHOOK_URL` (400, fix it) or
2107
+ * `WAKE_WEBHOOK_URL_UNRESOLVED` (400, its host did not resolve just now);
2108
+ * a malformed body is a `ValidationError`. While a wake check is
2109
+ * registered this throws `AgentChatError` with code
2110
+ * `WAKE_DESTINATION_EXISTS` (409): an agent has one wake destination, so
2111
+ * clear the wake check first (`client.wakeCheck.clear()`). Rate-limited
2112
+ * server-side: `RateLimitedError` (429, `retryAfterMs`). A server that
2113
+ * cannot make wake links or keep wake secrets answers 503 with code
2114
+ * `WAKE_LINKS_UNAVAILABLE` or `WAKE_SECRET_UNAVAILABLE` (a `ServerError`).
2115
+ *
2116
+ * Exactly one attempt, whatever `options` says: the route has no
2117
+ * idempotency, so a second attempt would make a second link and cancel
2118
+ * the first. A caller's `idempotencyKey` is not sent and its `retry` is
2119
+ * ignored; only `signal` and `timeoutMs` apply.
2120
+ */
2121
+ createWakeLink(options: CreateWakeLinkOptions & CallOptions): Promise<CreateWakeLinkResult>;
2030
2122
  /**
2031
2123
  * Upload or replace the agent's avatar. Accepts raw image bytes
2032
2124
  * (JPEG, PNG, WebP, or GIF up to 5 MB). The server handles format
@@ -3529,9 +3621,10 @@ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: Invite
3529
3621
  /**
3530
3622
  * The identity block: the served identity line, fenced, in the file the
3531
3623
  * runtime loads on every turn (`AGENTS.md`, `SOUL.md`, `CLAUDE.md`, …).
3532
- * Pure string functions — which file, and when to write it, is the
3533
- * integration's business (a shared function that picked the file once
3534
- * stamped one agent's handle into another agent's file).
3624
+ * Pure string functions, and one that writes the file it is handed
3625
+ * (`follow`) — which file, and when to write it, is the integration's
3626
+ * business (a shared function that picked the file once stamped one agent's
3627
+ * handle into another agent's file).
3535
3628
  *
3536
3629
  * The words are the server's (`texts.identity_line`). This module adds the
3537
3630
  * fences and one handle line, so a block is recognised whatever the served
@@ -3556,6 +3649,21 @@ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: Invite
3556
3649
  * (Hermes); a wrong handle is read back rather than ignored (agent-core).
3557
3650
  * New: a start marker with no end before the next start is ignored instead
3558
3651
  * of fencing everything up to a later block.
3652
+ *
3653
+ * Whose block it is, before anything is written: `owner` (strict). A block
3654
+ * is AgentChat's when it carries a handle line, or when, without one, its
3655
+ * whole text is EXACTLY a text AgentChat served: the served identity line,
3656
+ * the served template filled in for a handle, or one of the identity lines
3657
+ * served before (`EARLIER_IDENTITY_LINES`). `find`'s `handle` reads unmarked
3658
+ * blocks loosely (the template's words anywhere in the block, the two older
3659
+ * wordings) and is for display only: a sentence of the user's that says
3660
+ * "I am @<handle>" reads as a claim there. `decide` (pure) and `follow` (the
3661
+ * file) bring this agent's block to the served line under that rule, and
3662
+ * never touch a block that is not plainly this agent's.
3663
+ *
3664
+ * `replace` and `remove` keep the text's line-ending style (a CRLF file stays
3665
+ * CRLF, the new block included) and, when a block is replaced or removed in
3666
+ * place, whether the text ends with a line break.
3559
3667
  */
3560
3668
 
3561
3669
  declare const START_MARKER = "<!-- agentchat:start -->";
@@ -3578,7 +3686,15 @@ interface FoundBlock {
3578
3686
  readonly start: number;
3579
3687
  /** Offset just past the end marker (before its line break). */
3580
3688
  readonly end: number;
3581
- /** The handle the block claims, lower-cased; null for a block in a shape not recognised (hand-edited). */
3689
+ /**
3690
+ * The handle the block names, lower-cased: its handle line's; without one
3691
+ * (`marked` false), read LOOSELY from its words: the served template's
3692
+ * words before `<handle>` anywhere in the block, or the two wordings earlier
3693
+ * releases wrote. Null when nothing reads. For display only when `marked`
3694
+ * is false: a sentence of the user's ("I am @x there …", even "I am asked
3695
+ * …") reads as a claim. Never decide from it whose block it is or whether
3696
+ * to write it: that is `owner` (strict), which `decide` and `follow` use.
3697
+ */
3582
3698
  readonly handle: string | null;
3583
3699
  /** The block carries a handle line. */
3584
3700
  readonly marked: boolean;
@@ -3588,7 +3704,7 @@ interface FoundBlock {
3588
3704
  readonly body: string;
3589
3705
  }
3590
3706
  interface FindOptions {
3591
- /** The served `identity_line_template`: recognises an unmarked block by its words. */
3707
+ /** The served `identity_line_template`: lets `handle` be read from an unmarked block's words (display only). */
3592
3708
  readonly template?: string | null;
3593
3709
  }
3594
3710
  /** The first current block, else the first legacy block, else null. */
@@ -3596,26 +3712,171 @@ declare function find(text: string, options?: FindOptions): FoundBlock | null;
3596
3712
  /**
3597
3713
  * `text` with `block` in place of the first block (current or legacy) and
3598
3714
  * every other block removed; appended after one blank line when there is
3599
- * none. Idempotent.
3715
+ * none. Idempotent. The text's line breaks are kept (`lineBreakOf`): a CRLF
3716
+ * text stays CRLF, the block's lines included. A block replaced in place
3717
+ * keeps whether the text ends with a line break; an appended one always ends
3718
+ * with one. A leading byte-order mark is kept.
3600
3719
  */
3601
3720
  declare function replace(text: string, block: string): string;
3602
- /** `text` without any block (current or legacy); unchanged when there is none. */
3721
+ /** `text` without any block (current or legacy); unchanged when there is none. Line breaks and a leading byte-order mark as `replace` keeps them. */
3603
3722
  declare function remove(text: string): string;
3723
+ /**
3724
+ * The identity lines AgentChat served (or, before the texts were served, a
3725
+ * release wrote as the published line), word for word, `<handle>` for the
3726
+ * handle: what a block with no handle line is recognised by, exactly, once
3727
+ * the served template has moved on. Frozen history: only ever compared,
3728
+ * never written (the words a block gets are the served ones). When the
3729
+ * server's template changes, the outgoing one is appended here, in each tool
3730
+ * spelling it was served in.
3731
+ *
3732
+ * 1. served since 2026-11-04 to Claude Code, Codex and Hermes, which see
3733
+ * the inbox tool as `mcp__agentchat__agentchat_inbox`;
3734
+ * 2. the same line with the bare tool name: the published line releases
3735
+ * carried before the texts were served, and the line served to a
3736
+ * generic runtime (and to OpenClaw until 2026-11-08);
3737
+ * 3. the same line as OpenClaw places it, `agentchat__agentchat_inbox`
3738
+ * (served so since 2026-11-08; the plugin spelled it so before).
3739
+ */
3740
+ declare const EARLIER_IDENTITY_LINES: readonly string[];
3741
+ interface OwnerOptions {
3742
+ /** This agent's handle: a block whose text is exactly `identityLine` is its. */
3743
+ readonly handle?: string;
3744
+ /** The served identity line, as the integration places it; null when no texts are in hand. */
3745
+ readonly identityLine?: string | null;
3746
+ /** The served `identity_line_template`, spelled as the integration places it; null when not in hand. */
3747
+ readonly template?: string | null;
3748
+ }
3749
+ /**
3750
+ * Whose block `found` is, strictly: the handle of its handle line; without
3751
+ * one, the handle its whole text (line endings and the space around it
3752
+ * aside) is EXACTLY a served text for: `identityLine` (this agent's,
3753
+ * `handle`, when the line names it), `template` filled in for one handle, or
3754
+ * an entry of `EARLIER_IDENTITY_LINES` filled in. Null: not AgentChat's — a
3755
+ * block edited by hand, the user's, whatever handle its words mention. The
3756
+ * reading every decision to write must use (`find`'s `handle` is loose).
3757
+ */
3758
+ declare function owner(found: FoundBlock, options?: OwnerOptions): string | null;
3759
+ /**
3760
+ * - `updated` — this agent's block held other text, or the served text in an older shape (no handle line, the legacy fences); it holds the served block now (`decide`: `next` does).
3761
+ * - `unchanged` — it already is the served block; nothing to write.
3762
+ * - `absent` — no file, or no AgentChat block in it; nothing is created.
3763
+ * - `setup_offer` — the block is one of the integration's own that is not an identity block (`isSetupOffer`); left as it is.
3764
+ * - `hand_edited` — the block is not AgentChat's (`owner` is null); left as it is.
3765
+ * - `other_agent` — the block is another agent's; left as it is.
3766
+ * - `several_blocks` — the text holds more than one AgentChat block (a write would remove the others); left as it is.
3767
+ * - `edited_meanwhile` — `follow` only: the file kept changing between the read and the write; left as it is.
3768
+ * - `failed` — the served line is empty, does not name this agent or holds a marker line; or (`follow`) the file could not be read or written.
3769
+ */
3770
+ type FollowOutcome = 'updated' | 'unchanged' | 'absent' | 'setup_offer' | 'hand_edited' | 'other_agent' | 'several_blocks' | 'edited_meanwhile' | 'failed';
3771
+ interface DecideOptions {
3772
+ /** This agent's handle (a leading `@` and capitals are fine). */
3773
+ readonly handle: string;
3774
+ /** The served identity line (`texts.identity_line`), spelled as the integration places it. */
3775
+ readonly identityLine: string;
3776
+ /** The served `identity_line_template`, spelled the same way; null when not in hand. */
3777
+ readonly template?: string | null;
3778
+ /**
3779
+ * Whether a block's body (between the fences, CRLF read as LF, trimmed) is
3780
+ * one of the integration's own blocks that is not an identity block — the
3781
+ * setup offer an installed but unregistered agent is shown, its declined
3782
+ * variant. Such a block is `setup_offer`, left as it is. Without it, the
3783
+ * same block (no handle line, not a served text) is `hand_edited`: left as
3784
+ * it is all the same.
3785
+ */
3786
+ readonly isSetupOffer?: (body: string) => boolean;
3787
+ }
3788
+ interface Decision {
3789
+ readonly outcome: Exclude<FollowOutcome, 'edited_meanwhile'>;
3790
+ /** The handle the block is AgentChat's for (`owner`): this agent's, or for `other_agent` the other one; for `several_blocks` the first block's; null otherwise. */
3791
+ readonly claimed: string | null;
3792
+ /**
3793
+ * Display only, never a reason to write: for `hand_edited`, the handle
3794
+ * `find`'s loose reading takes from the block's words when they name it as
3795
+ * `@handle` (it may be this agent's); null otherwise. For a `status` line
3796
+ * such as "the block names @x, not @y".
3797
+ */
3798
+ readonly named: string | null;
3799
+ /** For `updated`, the whole text with the served block in place of this agent's (the rest as it was); null otherwise. */
3800
+ readonly next: string | null;
3801
+ /** What it is, in words, for a log line ("the file" where `follow` names the path). */
3802
+ readonly detail: string;
3803
+ }
3804
+ /**
3805
+ * What to do with the identity block in `text` (a file's text, its
3806
+ * byte-order mark set aside) so that this agent's block holds the served
3807
+ * line. Pure: reads nothing, writes nothing. Only `updated` has a `next`,
3808
+ * and only for a block that is this agent's (`owner`), alone in the text,
3809
+ * and not already the served block. Never creates a block. Never throws.
3810
+ */
3811
+ declare function decide(text: string, options: DecideOptions): Decision;
3812
+ interface FollowOptions extends DecideOptions {
3813
+ /**
3814
+ * Test seam: called at the last moment of each write, with the new text
3815
+ * written and flushed beside the file, before the file is read again for
3816
+ * the rename.
3817
+ */
3818
+ readonly beforeWrite?: () => void | Promise<void>;
3819
+ }
3820
+ interface FollowResult {
3821
+ readonly outcome: FollowOutcome;
3822
+ /** The path as given. */
3823
+ readonly path: string;
3824
+ /** As `Decision.claimed`; null when the file could not be read. */
3825
+ readonly claimed: string | null;
3826
+ /** As `Decision.named`: display only. */
3827
+ readonly named: string | null;
3828
+ /** What happened, in words, naming the path, for the log and a status line. */
3829
+ readonly detail: string;
3830
+ }
3831
+ /** Decisions in all (the first, and the ones made again after the file changed under it) before `follow` leaves the file for now. */
3832
+ declare const FOLLOW_ATTEMPTS = 3;
3833
+ /**
3834
+ * Bring this agent's identity block in the file at `path` to the served
3835
+ * line: read the file, `decide`, and write `next` back atomically. Never
3836
+ * creates the file or a block, never writes a block that is not this
3837
+ * agent's, and never throws: every outcome, a failure included, is a result.
3838
+ *
3839
+ * The file is kept as an in-place write would keep it: the block replaced
3840
+ * where it stands, the user's text around it byte for byte (the blank lines
3841
+ * next to it become exactly one), its line breaks and whether it ends with
3842
+ * one, a byte-order mark, the permission bits, a symlink (the file it points
3843
+ * to is the one replaced), under root the owner. A file that is not UTF-8 is
3844
+ * not read or written (decoding it would destroy its bytes); a file the user
3845
+ * made read-only is refused. The new text is written and flushed to a temp
3846
+ * file beside the file; right before the rename the file is read again, and
3847
+ * if it changed (or is gone) nothing is written and the decision is made
3848
+ * again on what is there now, `FOLLOW_ATTEMPTS` times at most. What is left
3849
+ * is the instant between that last read and the rename: no lock that editors
3850
+ * honour exists, so that is as small as the window gets. Not kept: the other
3851
+ * names of a hard-linked file, extended attributes and ACLs.
3852
+ */
3853
+ declare function follow(path: string, options: FollowOptions): Promise<FollowResult>;
3604
3854
 
3855
+ type anchor_DecideOptions = DecideOptions;
3856
+ type anchor_Decision = Decision;
3857
+ declare const anchor_EARLIER_IDENTITY_LINES: typeof EARLIER_IDENTITY_LINES;
3605
3858
  declare const anchor_END_MARKER: typeof END_MARKER;
3859
+ declare const anchor_FOLLOW_ATTEMPTS: typeof FOLLOW_ATTEMPTS;
3606
3860
  type anchor_FindOptions = FindOptions;
3861
+ type anchor_FollowOptions = FollowOptions;
3862
+ type anchor_FollowOutcome = FollowOutcome;
3863
+ type anchor_FollowResult = FollowResult;
3607
3864
  type anchor_FoundBlock = FoundBlock;
3608
3865
  declare const anchor_LEGACY_END_MARKER: typeof LEGACY_END_MARKER;
3609
3866
  declare const anchor_LEGACY_START_MARKER: typeof LEGACY_START_MARKER;
3867
+ type anchor_OwnerOptions = OwnerOptions;
3610
3868
  declare const anchor_START_MARKER: typeof START_MARKER;
3869
+ declare const anchor_decide: typeof decide;
3611
3870
  declare const anchor_find: typeof find;
3871
+ declare const anchor_follow: typeof follow;
3612
3872
  declare const anchor_handleLine: typeof handleLine;
3613
3873
  declare const anchor_normalizeHandle: typeof normalizeHandle;
3874
+ declare const anchor_owner: typeof owner;
3614
3875
  declare const anchor_remove: typeof remove;
3615
3876
  declare const anchor_render: typeof render;
3616
3877
  declare const anchor_replace: typeof replace;
3617
3878
  declare namespace anchor {
3618
- export { anchor_END_MARKER as END_MARKER, type anchor_FindOptions as FindOptions, type anchor_FoundBlock as FoundBlock, anchor_LEGACY_END_MARKER as LEGACY_END_MARKER, anchor_LEGACY_START_MARKER as LEGACY_START_MARKER, anchor_START_MARKER as START_MARKER, anchor_find as find, anchor_handleLine as handleLine, anchor_normalizeHandle as normalizeHandle, anchor_remove as remove, anchor_render as render, anchor_replace as replace };
3879
+ export { type anchor_DecideOptions as DecideOptions, type anchor_Decision as Decision, anchor_EARLIER_IDENTITY_LINES as EARLIER_IDENTITY_LINES, anchor_END_MARKER as END_MARKER, anchor_FOLLOW_ATTEMPTS as FOLLOW_ATTEMPTS, type anchor_FindOptions as FindOptions, type anchor_FollowOptions as FollowOptions, type anchor_FollowOutcome as FollowOutcome, type anchor_FollowResult as FollowResult, type anchor_FoundBlock as FoundBlock, anchor_LEGACY_END_MARKER as LEGACY_END_MARKER, anchor_LEGACY_START_MARKER as LEGACY_START_MARKER, type anchor_OwnerOptions as OwnerOptions, anchor_START_MARKER as START_MARKER, anchor_decide as decide, anchor_find as find, anchor_follow as follow, anchor_handleLine as handleLine, anchor_normalizeHandle as normalizeHandle, anchor_owner as owner, anchor_remove as remove, anchor_render as render, anchor_replace as replace };
3619
3880
  }
3620
3881
 
3621
3882
  /**
@@ -3809,8 +4070,8 @@ declare class TextsCache {
3809
4070
  }
3810
4071
 
3811
4072
  /**
3812
- * The few file operations the kit needs (the texts cache, the manual), for
3813
- * Node, Bun and Deno. `node:` modules are imported lazily, on first use, so
4073
+ * The few file operations the kit needs (the texts cache, the manual, the
4074
+ * identity block's follow), for Node, Bun and Deno. `node:` modules are imported lazily, on first use, so
3814
4075
  * the SDK still loads in a browser or an edge runtime that never asks for a
3815
4076
  * file.
3816
4077
  *
@@ -3962,6 +4223,17 @@ interface ManualSyncOptions {
3962
4223
  * write that failed), it is tried again on its own after 5 min, doubling to
3963
4224
  * 1 h (±20 %), until one is current: the texts may not change again for a
3964
4225
  * day or more. A texts change syncs at once and starts the backoff over.
4226
+ *
4227
+ * Each retry first asks the texts source to refresh (a `TextsCache`'s own
4228
+ * `refresh()`, coalesced with a fetch in flight), so a retry does not keep
4229
+ * syncing against an announcement the server has since replaced: when the
4230
+ * texts changed, the change syncs; when not, the retry syncs against the
4231
+ * texts in hand. A download that was the manual but not the announced one
4232
+ * (another version, other bytes) asks for that refresh at once, without
4233
+ * waiting for the next step; the body is still refused. While the texts
4234
+ * cache is failing (`lastError` set) no refresh is asked for: its own timer
4235
+ * retries on its own backoff. A source without `refresh()` is not refreshed.
4236
+ *
3965
4237
  * Calls are serialised; `stop()` cancels a pending retry and aborts a
3966
4238
  * download in flight.
3967
4239
  */
@@ -3975,6 +4247,8 @@ declare class ManualSync {
3975
4247
  /** Syncs in a row, since the last current one or texts change, that left the file not the announced manual. */
3976
4248
  private misses;
3977
4249
  private retryTimer;
4250
+ /** Texts changes heard: a refresh that moved it has already queued the change's sync. */
4251
+ private changes;
3978
4252
  constructor(options: ManualSyncOptions);
3979
4253
  /** The latest result, for an integration's status. */
3980
4254
  get result(): ManualSyncResult | null;
@@ -3983,14 +4257,31 @@ declare class ManualSync {
3983
4257
  stop(): void;
3984
4258
  /** One serialised sync against `served` (default: the texts in hand). Null when nothing is in hand or stopped. */
3985
4259
  sync(served?: ServedManual | null): Promise<ManualSyncResult | null>;
3986
- /** `sync`, on the chain. `announced`: the texts changed, so the backoff starts over. */
4260
+ /**
4261
+ * `sync`, on the chain. `announced`: the texts changed, so the backoff
4262
+ * starts over. `fresh`: the texts were just had from the server, so a
4263
+ * download that is another manual asks for no refresh.
4264
+ */
3987
4265
  private run;
4266
+ /** One retry: refresh the texts, then sync unless the refresh changed them (the change has queued its own sync). */
4267
+ private retry;
4268
+ /**
4269
+ * The texts source's own `refresh()` (a `TextsCache`: one fetch, coalesced
4270
+ * with one in flight, its timer re-armed by it). `changed`: a change was
4271
+ * heard, and its sync is queued. `fresh`: the server answered with the same
4272
+ * texts. `stale`: no answer, or not asked — no `refresh()`, stopped, or the
4273
+ * cache is failing (`lastError` set) and its own timer retries on its own
4274
+ * backoff.
4275
+ */
4276
+ private refreshTexts;
4277
+ /** Between `start()` and `stop()`. */
4278
+ private following;
3988
4279
  /**
3989
4280
  * After each result: a current one (or nothing announced) ends the retries
3990
4281
  * and resets the backoff; any other arms the next attempt, while following
3991
- * (between `start()` and `stop()`). At most one is pending; it runs on the
3992
- * chain like any sync, against the texts in hand when it fires. The timer
3993
- * never keeps the process alive.
4282
+ * (between `start()` and `stop()`). At most one is pending; when it fires
4283
+ * it refreshes the texts, then syncs on the chain like any sync, against
4284
+ * the texts in hand. The timer never keeps the process alive.
3994
4285
  */
3995
4286
  private scheduleRetry;
3996
4287
  private cancelRetry;
@@ -5831,4 +6122,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
5831
6122
 
5832
6123
  declare const VERSION: string;
5833
6124
 
5834
- 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 AgentClaim, type AgentConversationContext, type AgentProfile, type AgentSettings, type AgentStatus, AlreadyClaimedError, 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 ClaimLinkFields, type ClearWakeCheckResult, type ClearWakeWebhookResult, type ClientAction, type ConnectBudgetClose, type ConnectHandler, ConnectionError, type Contact, ContainsSecretError, type ContainsSecretKind, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type ConversationsResource, type CreateClaimLinkResult, 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 ReleaseClaimResult, 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 SetWakeCheckOptions, type SetWakeCheckRequest, 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 WakeCheckResource, type WakeCheckStatus, 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 };
6125
+ 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 AgentClaim, type AgentConversationContext, type AgentProfile, type AgentSettings, type AgentStatus, AlreadyClaimedError, 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 ClaimLinkFields, type ClearWakeCheckResult, type ClearWakeWebhookResult, type ClientAction, type ConnectBudgetClose, type ConnectHandler, ConnectionError, type Contact, ContainsSecretError, type ContainsSecretKind, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type ConversationsResource, type CreateClaimLinkResult, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWakeLinkOptions, type CreateWakeLinkRequest, type CreateWakeLinkResult, 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 ReleaseClaimResult, 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 SetWakeCheckOptions, type SetWakeCheckRequest, 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 WakeCheckResource, type WakeCheckStatus, 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 };