agentchatme 1.7.0 → 1.8.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
@@ -3529,9 +3529,10 @@ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: Invite
3529
3529
  /**
3530
3530
  * The identity block: the served identity line, fenced, in the file the
3531
3531
  * 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).
3532
+ * Pure string functions, and one that writes the file it is handed
3533
+ * (`follow`) — which file, and when to write it, is the integration's
3534
+ * business (a shared function that picked the file once stamped one agent's
3535
+ * handle into another agent's file).
3535
3536
  *
3536
3537
  * The words are the server's (`texts.identity_line`). This module adds the
3537
3538
  * fences and one handle line, so a block is recognised whatever the served
@@ -3556,6 +3557,21 @@ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: Invite
3556
3557
  * (Hermes); a wrong handle is read back rather than ignored (agent-core).
3557
3558
  * New: a start marker with no end before the next start is ignored instead
3558
3559
  * of fencing everything up to a later block.
3560
+ *
3561
+ * Whose block it is, before anything is written: `owner` (strict). A block
3562
+ * is AgentChat's when it carries a handle line, or when, without one, its
3563
+ * whole text is EXACTLY a text AgentChat served: the served identity line,
3564
+ * the served template filled in for a handle, or one of the identity lines
3565
+ * served before (`EARLIER_IDENTITY_LINES`). `find`'s `handle` reads unmarked
3566
+ * blocks loosely (the template's words anywhere in the block, the two older
3567
+ * wordings) and is for display only: a sentence of the user's that says
3568
+ * "I am @<handle>" reads as a claim there. `decide` (pure) and `follow` (the
3569
+ * file) bring this agent's block to the served line under that rule, and
3570
+ * never touch a block that is not plainly this agent's.
3571
+ *
3572
+ * `replace` and `remove` keep the text's line-ending style (a CRLF file stays
3573
+ * CRLF, the new block included) and, when a block is replaced or removed in
3574
+ * place, whether the text ends with a line break.
3559
3575
  */
3560
3576
 
3561
3577
  declare const START_MARKER = "<!-- agentchat:start -->";
@@ -3578,7 +3594,15 @@ interface FoundBlock {
3578
3594
  readonly start: number;
3579
3595
  /** Offset just past the end marker (before its line break). */
3580
3596
  readonly end: number;
3581
- /** The handle the block claims, lower-cased; null for a block in a shape not recognised (hand-edited). */
3597
+ /**
3598
+ * The handle the block names, lower-cased: its handle line's; without one
3599
+ * (`marked` false), read LOOSELY from its words: the served template's
3600
+ * words before `<handle>` anywhere in the block, or the two wordings earlier
3601
+ * releases wrote. Null when nothing reads. For display only when `marked`
3602
+ * is false: a sentence of the user's ("I am @x there …", even "I am asked
3603
+ * …") reads as a claim. Never decide from it whose block it is or whether
3604
+ * to write it: that is `owner` (strict), which `decide` and `follow` use.
3605
+ */
3582
3606
  readonly handle: string | null;
3583
3607
  /** The block carries a handle line. */
3584
3608
  readonly marked: boolean;
@@ -3588,7 +3612,7 @@ interface FoundBlock {
3588
3612
  readonly body: string;
3589
3613
  }
3590
3614
  interface FindOptions {
3591
- /** The served `identity_line_template`: recognises an unmarked block by its words. */
3615
+ /** The served `identity_line_template`: lets `handle` be read from an unmarked block's words (display only). */
3592
3616
  readonly template?: string | null;
3593
3617
  }
3594
3618
  /** The first current block, else the first legacy block, else null. */
@@ -3596,26 +3620,171 @@ declare function find(text: string, options?: FindOptions): FoundBlock | null;
3596
3620
  /**
3597
3621
  * `text` with `block` in place of the first block (current or legacy) and
3598
3622
  * every other block removed; appended after one blank line when there is
3599
- * none. Idempotent.
3623
+ * none. Idempotent. The text's line breaks are kept (`lineBreakOf`): a CRLF
3624
+ * text stays CRLF, the block's lines included. A block replaced in place
3625
+ * keeps whether the text ends with a line break; an appended one always ends
3626
+ * with one. A leading byte-order mark is kept.
3600
3627
  */
3601
3628
  declare function replace(text: string, block: string): string;
3602
- /** `text` without any block (current or legacy); unchanged when there is none. */
3629
+ /** `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
3630
  declare function remove(text: string): string;
3631
+ /**
3632
+ * The identity lines AgentChat served (or, before the texts were served, a
3633
+ * release wrote as the published line), word for word, `<handle>` for the
3634
+ * handle: what a block with no handle line is recognised by, exactly, once
3635
+ * the served template has moved on. Frozen history: only ever compared,
3636
+ * never written (the words a block gets are the served ones). When the
3637
+ * server's template changes, the outgoing one is appended here, in each tool
3638
+ * spelling it was served in.
3639
+ *
3640
+ * 1. served since 2026-11-04 to Claude Code, Codex and Hermes, which see
3641
+ * the inbox tool as `mcp__agentchat__agentchat_inbox`;
3642
+ * 2. the same line with the bare tool name: the published line releases
3643
+ * carried before the texts were served, and the line served to a
3644
+ * generic runtime (and to OpenClaw until 2026-11-08);
3645
+ * 3. the same line as OpenClaw places it, `agentchat__agentchat_inbox`
3646
+ * (served so since 2026-11-08; the plugin spelled it so before).
3647
+ */
3648
+ declare const EARLIER_IDENTITY_LINES: readonly string[];
3649
+ interface OwnerOptions {
3650
+ /** This agent's handle: a block whose text is exactly `identityLine` is its. */
3651
+ readonly handle?: string;
3652
+ /** The served identity line, as the integration places it; null when no texts are in hand. */
3653
+ readonly identityLine?: string | null;
3654
+ /** The served `identity_line_template`, spelled as the integration places it; null when not in hand. */
3655
+ readonly template?: string | null;
3656
+ }
3657
+ /**
3658
+ * Whose block `found` is, strictly: the handle of its handle line; without
3659
+ * one, the handle its whole text (line endings and the space around it
3660
+ * aside) is EXACTLY a served text for: `identityLine` (this agent's,
3661
+ * `handle`, when the line names it), `template` filled in for one handle, or
3662
+ * an entry of `EARLIER_IDENTITY_LINES` filled in. Null: not AgentChat's — a
3663
+ * block edited by hand, the user's, whatever handle its words mention. The
3664
+ * reading every decision to write must use (`find`'s `handle` is loose).
3665
+ */
3666
+ declare function owner(found: FoundBlock, options?: OwnerOptions): string | null;
3667
+ /**
3668
+ * - `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).
3669
+ * - `unchanged` — it already is the served block; nothing to write.
3670
+ * - `absent` — no file, or no AgentChat block in it; nothing is created.
3671
+ * - `setup_offer` — the block is one of the integration's own that is not an identity block (`isSetupOffer`); left as it is.
3672
+ * - `hand_edited` — the block is not AgentChat's (`owner` is null); left as it is.
3673
+ * - `other_agent` — the block is another agent's; left as it is.
3674
+ * - `several_blocks` — the text holds more than one AgentChat block (a write would remove the others); left as it is.
3675
+ * - `edited_meanwhile` — `follow` only: the file kept changing between the read and the write; left as it is.
3676
+ * - `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.
3677
+ */
3678
+ type FollowOutcome = 'updated' | 'unchanged' | 'absent' | 'setup_offer' | 'hand_edited' | 'other_agent' | 'several_blocks' | 'edited_meanwhile' | 'failed';
3679
+ interface DecideOptions {
3680
+ /** This agent's handle (a leading `@` and capitals are fine). */
3681
+ readonly handle: string;
3682
+ /** The served identity line (`texts.identity_line`), spelled as the integration places it. */
3683
+ readonly identityLine: string;
3684
+ /** The served `identity_line_template`, spelled the same way; null when not in hand. */
3685
+ readonly template?: string | null;
3686
+ /**
3687
+ * Whether a block's body (between the fences, CRLF read as LF, trimmed) is
3688
+ * one of the integration's own blocks that is not an identity block — the
3689
+ * setup offer an installed but unregistered agent is shown, its declined
3690
+ * variant. Such a block is `setup_offer`, left as it is. Without it, the
3691
+ * same block (no handle line, not a served text) is `hand_edited`: left as
3692
+ * it is all the same.
3693
+ */
3694
+ readonly isSetupOffer?: (body: string) => boolean;
3695
+ }
3696
+ interface Decision {
3697
+ readonly outcome: Exclude<FollowOutcome, 'edited_meanwhile'>;
3698
+ /** 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. */
3699
+ readonly claimed: string | null;
3700
+ /**
3701
+ * Display only, never a reason to write: for `hand_edited`, the handle
3702
+ * `find`'s loose reading takes from the block's words when they name it as
3703
+ * `@handle` (it may be this agent's); null otherwise. For a `status` line
3704
+ * such as "the block names @x, not @y".
3705
+ */
3706
+ readonly named: string | null;
3707
+ /** For `updated`, the whole text with the served block in place of this agent's (the rest as it was); null otherwise. */
3708
+ readonly next: string | null;
3709
+ /** What it is, in words, for a log line ("the file" where `follow` names the path). */
3710
+ readonly detail: string;
3711
+ }
3712
+ /**
3713
+ * What to do with the identity block in `text` (a file's text, its
3714
+ * byte-order mark set aside) so that this agent's block holds the served
3715
+ * line. Pure: reads nothing, writes nothing. Only `updated` has a `next`,
3716
+ * and only for a block that is this agent's (`owner`), alone in the text,
3717
+ * and not already the served block. Never creates a block. Never throws.
3718
+ */
3719
+ declare function decide(text: string, options: DecideOptions): Decision;
3720
+ interface FollowOptions extends DecideOptions {
3721
+ /**
3722
+ * Test seam: called at the last moment of each write, with the new text
3723
+ * written and flushed beside the file, before the file is read again for
3724
+ * the rename.
3725
+ */
3726
+ readonly beforeWrite?: () => void | Promise<void>;
3727
+ }
3728
+ interface FollowResult {
3729
+ readonly outcome: FollowOutcome;
3730
+ /** The path as given. */
3731
+ readonly path: string;
3732
+ /** As `Decision.claimed`; null when the file could not be read. */
3733
+ readonly claimed: string | null;
3734
+ /** As `Decision.named`: display only. */
3735
+ readonly named: string | null;
3736
+ /** What happened, in words, naming the path, for the log and a status line. */
3737
+ readonly detail: string;
3738
+ }
3739
+ /** Decisions in all (the first, and the ones made again after the file changed under it) before `follow` leaves the file for now. */
3740
+ declare const FOLLOW_ATTEMPTS = 3;
3741
+ /**
3742
+ * Bring this agent's identity block in the file at `path` to the served
3743
+ * line: read the file, `decide`, and write `next` back atomically. Never
3744
+ * creates the file or a block, never writes a block that is not this
3745
+ * agent's, and never throws: every outcome, a failure included, is a result.
3746
+ *
3747
+ * The file is kept as an in-place write would keep it: the block replaced
3748
+ * where it stands, the user's text around it byte for byte (the blank lines
3749
+ * next to it become exactly one), its line breaks and whether it ends with
3750
+ * one, a byte-order mark, the permission bits, a symlink (the file it points
3751
+ * to is the one replaced), under root the owner. A file that is not UTF-8 is
3752
+ * not read or written (decoding it would destroy its bytes); a file the user
3753
+ * made read-only is refused. The new text is written and flushed to a temp
3754
+ * file beside the file; right before the rename the file is read again, and
3755
+ * if it changed (or is gone) nothing is written and the decision is made
3756
+ * again on what is there now, `FOLLOW_ATTEMPTS` times at most. What is left
3757
+ * is the instant between that last read and the rename: no lock that editors
3758
+ * honour exists, so that is as small as the window gets. Not kept: the other
3759
+ * names of a hard-linked file, extended attributes and ACLs.
3760
+ */
3761
+ declare function follow(path: string, options: FollowOptions): Promise<FollowResult>;
3604
3762
 
3763
+ type anchor_DecideOptions = DecideOptions;
3764
+ type anchor_Decision = Decision;
3765
+ declare const anchor_EARLIER_IDENTITY_LINES: typeof EARLIER_IDENTITY_LINES;
3605
3766
  declare const anchor_END_MARKER: typeof END_MARKER;
3767
+ declare const anchor_FOLLOW_ATTEMPTS: typeof FOLLOW_ATTEMPTS;
3606
3768
  type anchor_FindOptions = FindOptions;
3769
+ type anchor_FollowOptions = FollowOptions;
3770
+ type anchor_FollowOutcome = FollowOutcome;
3771
+ type anchor_FollowResult = FollowResult;
3607
3772
  type anchor_FoundBlock = FoundBlock;
3608
3773
  declare const anchor_LEGACY_END_MARKER: typeof LEGACY_END_MARKER;
3609
3774
  declare const anchor_LEGACY_START_MARKER: typeof LEGACY_START_MARKER;
3775
+ type anchor_OwnerOptions = OwnerOptions;
3610
3776
  declare const anchor_START_MARKER: typeof START_MARKER;
3777
+ declare const anchor_decide: typeof decide;
3611
3778
  declare const anchor_find: typeof find;
3779
+ declare const anchor_follow: typeof follow;
3612
3780
  declare const anchor_handleLine: typeof handleLine;
3613
3781
  declare const anchor_normalizeHandle: typeof normalizeHandle;
3782
+ declare const anchor_owner: typeof owner;
3614
3783
  declare const anchor_remove: typeof remove;
3615
3784
  declare const anchor_render: typeof render;
3616
3785
  declare const anchor_replace: typeof replace;
3617
3786
  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 };
3787
+ 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
3788
  }
3620
3789
 
3621
3790
  /**
@@ -3809,8 +3978,8 @@ declare class TextsCache {
3809
3978
  }
3810
3979
 
3811
3980
  /**
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
3981
+ * The few file operations the kit needs (the texts cache, the manual, the
3982
+ * identity block's follow), for Node, Bun and Deno. `node:` modules are imported lazily, on first use, so
3814
3983
  * the SDK still loads in a browser or an edge runtime that never asks for a
3815
3984
  * file.
3816
3985
  *
@@ -3962,6 +4131,17 @@ interface ManualSyncOptions {
3962
4131
  * write that failed), it is tried again on its own after 5 min, doubling to
3963
4132
  * 1 h (±20 %), until one is current: the texts may not change again for a
3964
4133
  * day or more. A texts change syncs at once and starts the backoff over.
4134
+ *
4135
+ * Each retry first asks the texts source to refresh (a `TextsCache`'s own
4136
+ * `refresh()`, coalesced with a fetch in flight), so a retry does not keep
4137
+ * syncing against an announcement the server has since replaced: when the
4138
+ * texts changed, the change syncs; when not, the retry syncs against the
4139
+ * texts in hand. A download that was the manual but not the announced one
4140
+ * (another version, other bytes) asks for that refresh at once, without
4141
+ * waiting for the next step; the body is still refused. While the texts
4142
+ * cache is failing (`lastError` set) no refresh is asked for: its own timer
4143
+ * retries on its own backoff. A source without `refresh()` is not refreshed.
4144
+ *
3965
4145
  * Calls are serialised; `stop()` cancels a pending retry and aborts a
3966
4146
  * download in flight.
3967
4147
  */
@@ -3975,6 +4155,8 @@ declare class ManualSync {
3975
4155
  /** Syncs in a row, since the last current one or texts change, that left the file not the announced manual. */
3976
4156
  private misses;
3977
4157
  private retryTimer;
4158
+ /** Texts changes heard: a refresh that moved it has already queued the change's sync. */
4159
+ private changes;
3978
4160
  constructor(options: ManualSyncOptions);
3979
4161
  /** The latest result, for an integration's status. */
3980
4162
  get result(): ManualSyncResult | null;
@@ -3983,14 +4165,31 @@ declare class ManualSync {
3983
4165
  stop(): void;
3984
4166
  /** One serialised sync against `served` (default: the texts in hand). Null when nothing is in hand or stopped. */
3985
4167
  sync(served?: ServedManual | null): Promise<ManualSyncResult | null>;
3986
- /** `sync`, on the chain. `announced`: the texts changed, so the backoff starts over. */
4168
+ /**
4169
+ * `sync`, on the chain. `announced`: the texts changed, so the backoff
4170
+ * starts over. `fresh`: the texts were just had from the server, so a
4171
+ * download that is another manual asks for no refresh.
4172
+ */
3987
4173
  private run;
4174
+ /** One retry: refresh the texts, then sync unless the refresh changed them (the change has queued its own sync). */
4175
+ private retry;
4176
+ /**
4177
+ * The texts source's own `refresh()` (a `TextsCache`: one fetch, coalesced
4178
+ * with one in flight, its timer re-armed by it). `changed`: a change was
4179
+ * heard, and its sync is queued. `fresh`: the server answered with the same
4180
+ * texts. `stale`: no answer, or not asked — no `refresh()`, stopped, or the
4181
+ * cache is failing (`lastError` set) and its own timer retries on its own
4182
+ * backoff.
4183
+ */
4184
+ private refreshTexts;
4185
+ /** Between `start()` and `stop()`. */
4186
+ private following;
3988
4187
  /**
3989
4188
  * After each result: a current one (or nothing announced) ends the retries
3990
4189
  * 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.
4190
+ * (between `start()` and `stop()`). At most one is pending; when it fires
4191
+ * it refreshes the texts, then syncs on the chain like any sync, against
4192
+ * the texts in hand. The timer never keeps the process alive.
3994
4193
  */
3995
4194
  private scheduleRetry;
3996
4195
  private cancelRetry;
package/dist/index.d.ts CHANGED
@@ -3529,9 +3529,10 @@ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: Invite
3529
3529
  /**
3530
3530
  * The identity block: the served identity line, fenced, in the file the
3531
3531
  * 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).
3532
+ * Pure string functions, and one that writes the file it is handed
3533
+ * (`follow`) — which file, and when to write it, is the integration's
3534
+ * business (a shared function that picked the file once stamped one agent's
3535
+ * handle into another agent's file).
3535
3536
  *
3536
3537
  * The words are the server's (`texts.identity_line`). This module adds the
3537
3538
  * fences and one handle line, so a block is recognised whatever the served
@@ -3556,6 +3557,21 @@ declare function applyInviteOutcome(client: InviteOutcomeClient, outcome: Invite
3556
3557
  * (Hermes); a wrong handle is read back rather than ignored (agent-core).
3557
3558
  * New: a start marker with no end before the next start is ignored instead
3558
3559
  * of fencing everything up to a later block.
3560
+ *
3561
+ * Whose block it is, before anything is written: `owner` (strict). A block
3562
+ * is AgentChat's when it carries a handle line, or when, without one, its
3563
+ * whole text is EXACTLY a text AgentChat served: the served identity line,
3564
+ * the served template filled in for a handle, or one of the identity lines
3565
+ * served before (`EARLIER_IDENTITY_LINES`). `find`'s `handle` reads unmarked
3566
+ * blocks loosely (the template's words anywhere in the block, the two older
3567
+ * wordings) and is for display only: a sentence of the user's that says
3568
+ * "I am @<handle>" reads as a claim there. `decide` (pure) and `follow` (the
3569
+ * file) bring this agent's block to the served line under that rule, and
3570
+ * never touch a block that is not plainly this agent's.
3571
+ *
3572
+ * `replace` and `remove` keep the text's line-ending style (a CRLF file stays
3573
+ * CRLF, the new block included) and, when a block is replaced or removed in
3574
+ * place, whether the text ends with a line break.
3559
3575
  */
3560
3576
 
3561
3577
  declare const START_MARKER = "<!-- agentchat:start -->";
@@ -3578,7 +3594,15 @@ interface FoundBlock {
3578
3594
  readonly start: number;
3579
3595
  /** Offset just past the end marker (before its line break). */
3580
3596
  readonly end: number;
3581
- /** The handle the block claims, lower-cased; null for a block in a shape not recognised (hand-edited). */
3597
+ /**
3598
+ * The handle the block names, lower-cased: its handle line's; without one
3599
+ * (`marked` false), read LOOSELY from its words: the served template's
3600
+ * words before `<handle>` anywhere in the block, or the two wordings earlier
3601
+ * releases wrote. Null when nothing reads. For display only when `marked`
3602
+ * is false: a sentence of the user's ("I am @x there …", even "I am asked
3603
+ * …") reads as a claim. Never decide from it whose block it is or whether
3604
+ * to write it: that is `owner` (strict), which `decide` and `follow` use.
3605
+ */
3582
3606
  readonly handle: string | null;
3583
3607
  /** The block carries a handle line. */
3584
3608
  readonly marked: boolean;
@@ -3588,7 +3612,7 @@ interface FoundBlock {
3588
3612
  readonly body: string;
3589
3613
  }
3590
3614
  interface FindOptions {
3591
- /** The served `identity_line_template`: recognises an unmarked block by its words. */
3615
+ /** The served `identity_line_template`: lets `handle` be read from an unmarked block's words (display only). */
3592
3616
  readonly template?: string | null;
3593
3617
  }
3594
3618
  /** The first current block, else the first legacy block, else null. */
@@ -3596,26 +3620,171 @@ declare function find(text: string, options?: FindOptions): FoundBlock | null;
3596
3620
  /**
3597
3621
  * `text` with `block` in place of the first block (current or legacy) and
3598
3622
  * every other block removed; appended after one blank line when there is
3599
- * none. Idempotent.
3623
+ * none. Idempotent. The text's line breaks are kept (`lineBreakOf`): a CRLF
3624
+ * text stays CRLF, the block's lines included. A block replaced in place
3625
+ * keeps whether the text ends with a line break; an appended one always ends
3626
+ * with one. A leading byte-order mark is kept.
3600
3627
  */
3601
3628
  declare function replace(text: string, block: string): string;
3602
- /** `text` without any block (current or legacy); unchanged when there is none. */
3629
+ /** `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
3630
  declare function remove(text: string): string;
3631
+ /**
3632
+ * The identity lines AgentChat served (or, before the texts were served, a
3633
+ * release wrote as the published line), word for word, `<handle>` for the
3634
+ * handle: what a block with no handle line is recognised by, exactly, once
3635
+ * the served template has moved on. Frozen history: only ever compared,
3636
+ * never written (the words a block gets are the served ones). When the
3637
+ * server's template changes, the outgoing one is appended here, in each tool
3638
+ * spelling it was served in.
3639
+ *
3640
+ * 1. served since 2026-11-04 to Claude Code, Codex and Hermes, which see
3641
+ * the inbox tool as `mcp__agentchat__agentchat_inbox`;
3642
+ * 2. the same line with the bare tool name: the published line releases
3643
+ * carried before the texts were served, and the line served to a
3644
+ * generic runtime (and to OpenClaw until 2026-11-08);
3645
+ * 3. the same line as OpenClaw places it, `agentchat__agentchat_inbox`
3646
+ * (served so since 2026-11-08; the plugin spelled it so before).
3647
+ */
3648
+ declare const EARLIER_IDENTITY_LINES: readonly string[];
3649
+ interface OwnerOptions {
3650
+ /** This agent's handle: a block whose text is exactly `identityLine` is its. */
3651
+ readonly handle?: string;
3652
+ /** The served identity line, as the integration places it; null when no texts are in hand. */
3653
+ readonly identityLine?: string | null;
3654
+ /** The served `identity_line_template`, spelled as the integration places it; null when not in hand. */
3655
+ readonly template?: string | null;
3656
+ }
3657
+ /**
3658
+ * Whose block `found` is, strictly: the handle of its handle line; without
3659
+ * one, the handle its whole text (line endings and the space around it
3660
+ * aside) is EXACTLY a served text for: `identityLine` (this agent's,
3661
+ * `handle`, when the line names it), `template` filled in for one handle, or
3662
+ * an entry of `EARLIER_IDENTITY_LINES` filled in. Null: not AgentChat's — a
3663
+ * block edited by hand, the user's, whatever handle its words mention. The
3664
+ * reading every decision to write must use (`find`'s `handle` is loose).
3665
+ */
3666
+ declare function owner(found: FoundBlock, options?: OwnerOptions): string | null;
3667
+ /**
3668
+ * - `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).
3669
+ * - `unchanged` — it already is the served block; nothing to write.
3670
+ * - `absent` — no file, or no AgentChat block in it; nothing is created.
3671
+ * - `setup_offer` — the block is one of the integration's own that is not an identity block (`isSetupOffer`); left as it is.
3672
+ * - `hand_edited` — the block is not AgentChat's (`owner` is null); left as it is.
3673
+ * - `other_agent` — the block is another agent's; left as it is.
3674
+ * - `several_blocks` — the text holds more than one AgentChat block (a write would remove the others); left as it is.
3675
+ * - `edited_meanwhile` — `follow` only: the file kept changing between the read and the write; left as it is.
3676
+ * - `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.
3677
+ */
3678
+ type FollowOutcome = 'updated' | 'unchanged' | 'absent' | 'setup_offer' | 'hand_edited' | 'other_agent' | 'several_blocks' | 'edited_meanwhile' | 'failed';
3679
+ interface DecideOptions {
3680
+ /** This agent's handle (a leading `@` and capitals are fine). */
3681
+ readonly handle: string;
3682
+ /** The served identity line (`texts.identity_line`), spelled as the integration places it. */
3683
+ readonly identityLine: string;
3684
+ /** The served `identity_line_template`, spelled the same way; null when not in hand. */
3685
+ readonly template?: string | null;
3686
+ /**
3687
+ * Whether a block's body (between the fences, CRLF read as LF, trimmed) is
3688
+ * one of the integration's own blocks that is not an identity block — the
3689
+ * setup offer an installed but unregistered agent is shown, its declined
3690
+ * variant. Such a block is `setup_offer`, left as it is. Without it, the
3691
+ * same block (no handle line, not a served text) is `hand_edited`: left as
3692
+ * it is all the same.
3693
+ */
3694
+ readonly isSetupOffer?: (body: string) => boolean;
3695
+ }
3696
+ interface Decision {
3697
+ readonly outcome: Exclude<FollowOutcome, 'edited_meanwhile'>;
3698
+ /** 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. */
3699
+ readonly claimed: string | null;
3700
+ /**
3701
+ * Display only, never a reason to write: for `hand_edited`, the handle
3702
+ * `find`'s loose reading takes from the block's words when they name it as
3703
+ * `@handle` (it may be this agent's); null otherwise. For a `status` line
3704
+ * such as "the block names @x, not @y".
3705
+ */
3706
+ readonly named: string | null;
3707
+ /** For `updated`, the whole text with the served block in place of this agent's (the rest as it was); null otherwise. */
3708
+ readonly next: string | null;
3709
+ /** What it is, in words, for a log line ("the file" where `follow` names the path). */
3710
+ readonly detail: string;
3711
+ }
3712
+ /**
3713
+ * What to do with the identity block in `text` (a file's text, its
3714
+ * byte-order mark set aside) so that this agent's block holds the served
3715
+ * line. Pure: reads nothing, writes nothing. Only `updated` has a `next`,
3716
+ * and only for a block that is this agent's (`owner`), alone in the text,
3717
+ * and not already the served block. Never creates a block. Never throws.
3718
+ */
3719
+ declare function decide(text: string, options: DecideOptions): Decision;
3720
+ interface FollowOptions extends DecideOptions {
3721
+ /**
3722
+ * Test seam: called at the last moment of each write, with the new text
3723
+ * written and flushed beside the file, before the file is read again for
3724
+ * the rename.
3725
+ */
3726
+ readonly beforeWrite?: () => void | Promise<void>;
3727
+ }
3728
+ interface FollowResult {
3729
+ readonly outcome: FollowOutcome;
3730
+ /** The path as given. */
3731
+ readonly path: string;
3732
+ /** As `Decision.claimed`; null when the file could not be read. */
3733
+ readonly claimed: string | null;
3734
+ /** As `Decision.named`: display only. */
3735
+ readonly named: string | null;
3736
+ /** What happened, in words, naming the path, for the log and a status line. */
3737
+ readonly detail: string;
3738
+ }
3739
+ /** Decisions in all (the first, and the ones made again after the file changed under it) before `follow` leaves the file for now. */
3740
+ declare const FOLLOW_ATTEMPTS = 3;
3741
+ /**
3742
+ * Bring this agent's identity block in the file at `path` to the served
3743
+ * line: read the file, `decide`, and write `next` back atomically. Never
3744
+ * creates the file or a block, never writes a block that is not this
3745
+ * agent's, and never throws: every outcome, a failure included, is a result.
3746
+ *
3747
+ * The file is kept as an in-place write would keep it: the block replaced
3748
+ * where it stands, the user's text around it byte for byte (the blank lines
3749
+ * next to it become exactly one), its line breaks and whether it ends with
3750
+ * one, a byte-order mark, the permission bits, a symlink (the file it points
3751
+ * to is the one replaced), under root the owner. A file that is not UTF-8 is
3752
+ * not read or written (decoding it would destroy its bytes); a file the user
3753
+ * made read-only is refused. The new text is written and flushed to a temp
3754
+ * file beside the file; right before the rename the file is read again, and
3755
+ * if it changed (or is gone) nothing is written and the decision is made
3756
+ * again on what is there now, `FOLLOW_ATTEMPTS` times at most. What is left
3757
+ * is the instant between that last read and the rename: no lock that editors
3758
+ * honour exists, so that is as small as the window gets. Not kept: the other
3759
+ * names of a hard-linked file, extended attributes and ACLs.
3760
+ */
3761
+ declare function follow(path: string, options: FollowOptions): Promise<FollowResult>;
3604
3762
 
3763
+ type anchor_DecideOptions = DecideOptions;
3764
+ type anchor_Decision = Decision;
3765
+ declare const anchor_EARLIER_IDENTITY_LINES: typeof EARLIER_IDENTITY_LINES;
3605
3766
  declare const anchor_END_MARKER: typeof END_MARKER;
3767
+ declare const anchor_FOLLOW_ATTEMPTS: typeof FOLLOW_ATTEMPTS;
3606
3768
  type anchor_FindOptions = FindOptions;
3769
+ type anchor_FollowOptions = FollowOptions;
3770
+ type anchor_FollowOutcome = FollowOutcome;
3771
+ type anchor_FollowResult = FollowResult;
3607
3772
  type anchor_FoundBlock = FoundBlock;
3608
3773
  declare const anchor_LEGACY_END_MARKER: typeof LEGACY_END_MARKER;
3609
3774
  declare const anchor_LEGACY_START_MARKER: typeof LEGACY_START_MARKER;
3775
+ type anchor_OwnerOptions = OwnerOptions;
3610
3776
  declare const anchor_START_MARKER: typeof START_MARKER;
3777
+ declare const anchor_decide: typeof decide;
3611
3778
  declare const anchor_find: typeof find;
3779
+ declare const anchor_follow: typeof follow;
3612
3780
  declare const anchor_handleLine: typeof handleLine;
3613
3781
  declare const anchor_normalizeHandle: typeof normalizeHandle;
3782
+ declare const anchor_owner: typeof owner;
3614
3783
  declare const anchor_remove: typeof remove;
3615
3784
  declare const anchor_render: typeof render;
3616
3785
  declare const anchor_replace: typeof replace;
3617
3786
  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 };
3787
+ 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
3788
  }
3620
3789
 
3621
3790
  /**
@@ -3809,8 +3978,8 @@ declare class TextsCache {
3809
3978
  }
3810
3979
 
3811
3980
  /**
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
3981
+ * The few file operations the kit needs (the texts cache, the manual, the
3982
+ * identity block's follow), for Node, Bun and Deno. `node:` modules are imported lazily, on first use, so
3814
3983
  * the SDK still loads in a browser or an edge runtime that never asks for a
3815
3984
  * file.
3816
3985
  *
@@ -3962,6 +4131,17 @@ interface ManualSyncOptions {
3962
4131
  * write that failed), it is tried again on its own after 5 min, doubling to
3963
4132
  * 1 h (±20 %), until one is current: the texts may not change again for a
3964
4133
  * day or more. A texts change syncs at once and starts the backoff over.
4134
+ *
4135
+ * Each retry first asks the texts source to refresh (a `TextsCache`'s own
4136
+ * `refresh()`, coalesced with a fetch in flight), so a retry does not keep
4137
+ * syncing against an announcement the server has since replaced: when the
4138
+ * texts changed, the change syncs; when not, the retry syncs against the
4139
+ * texts in hand. A download that was the manual but not the announced one
4140
+ * (another version, other bytes) asks for that refresh at once, without
4141
+ * waiting for the next step; the body is still refused. While the texts
4142
+ * cache is failing (`lastError` set) no refresh is asked for: its own timer
4143
+ * retries on its own backoff. A source without `refresh()` is not refreshed.
4144
+ *
3965
4145
  * Calls are serialised; `stop()` cancels a pending retry and aborts a
3966
4146
  * download in flight.
3967
4147
  */
@@ -3975,6 +4155,8 @@ declare class ManualSync {
3975
4155
  /** Syncs in a row, since the last current one or texts change, that left the file not the announced manual. */
3976
4156
  private misses;
3977
4157
  private retryTimer;
4158
+ /** Texts changes heard: a refresh that moved it has already queued the change's sync. */
4159
+ private changes;
3978
4160
  constructor(options: ManualSyncOptions);
3979
4161
  /** The latest result, for an integration's status. */
3980
4162
  get result(): ManualSyncResult | null;
@@ -3983,14 +4165,31 @@ declare class ManualSync {
3983
4165
  stop(): void;
3984
4166
  /** One serialised sync against `served` (default: the texts in hand). Null when nothing is in hand or stopped. */
3985
4167
  sync(served?: ServedManual | null): Promise<ManualSyncResult | null>;
3986
- /** `sync`, on the chain. `announced`: the texts changed, so the backoff starts over. */
4168
+ /**
4169
+ * `sync`, on the chain. `announced`: the texts changed, so the backoff
4170
+ * starts over. `fresh`: the texts were just had from the server, so a
4171
+ * download that is another manual asks for no refresh.
4172
+ */
3987
4173
  private run;
4174
+ /** One retry: refresh the texts, then sync unless the refresh changed them (the change has queued its own sync). */
4175
+ private retry;
4176
+ /**
4177
+ * The texts source's own `refresh()` (a `TextsCache`: one fetch, coalesced
4178
+ * with one in flight, its timer re-armed by it). `changed`: a change was
4179
+ * heard, and its sync is queued. `fresh`: the server answered with the same
4180
+ * texts. `stale`: no answer, or not asked — no `refresh()`, stopped, or the
4181
+ * cache is failing (`lastError` set) and its own timer retries on its own
4182
+ * backoff.
4183
+ */
4184
+ private refreshTexts;
4185
+ /** Between `start()` and `stop()`. */
4186
+ private following;
3988
4187
  /**
3989
4188
  * After each result: a current one (or nothing announced) ends the retries
3990
4189
  * 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.
4190
+ * (between `start()` and `stop()`). At most one is pending; when it fires
4191
+ * it refreshes the texts, then syncs on the chain like any sync, against
4192
+ * the texts in hand. The timer never keeps the process alive.
3994
4193
  */
3995
4194
  private scheduleRetry;
3996
4195
  private cancelRetry;