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/CHANGELOG.md +75 -0
- package/dist/index.cjs +432 -126
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +213 -14
- package/dist/index.d.ts +213 -14
- package/dist/index.js +432 -126
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
3533
|
-
*
|
|
3534
|
-
*
|
|
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
|
-
/**
|
|
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`:
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
3992
|
-
*
|
|
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
|
|
3533
|
-
*
|
|
3534
|
-
*
|
|
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
|
-
/**
|
|
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`:
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
3992
|
-
*
|
|
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;
|