@agentchatme/openclaw 0.9.2 → 0.10.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
@@ -1,108 +1,543 @@
1
- import { L as Logger } from './setup-entry-sXnwmV8K.cjs';
2
- export { A as AgentInvoker, a as AgentInvokerOptions, b as AgentchatChannelConfig, c as AgentchatResolvedAccount, C as CreateMetricsOptions, d as CycleOutcome, e as CycleResult, G as GroupInvite, I as IntegrationSocket, f as IntegrationSocketOptions, g as InviteLedger, M as MetricsRecorder, h as MetricsSnapshot, P as PromFactory, i as PromRegistryLike, S as SocketBlocked, j as SocketDisconnect, k as SocketHandlers, l as SocketHealth, m as SocketState, W as WakeSource, n as agentchatChannelEntry, o as agentchatPlugin, p as agentchatSetupEntry, o as agentchatSetupPlugin, q as createInMemoryMetrics, r as createMetrics, s as createNoopMetrics, n as default, t as groupInviteFromRecord, u as parseChannelConfig, v as realtimeOptionsFor } from './setup-entry-sXnwmV8K.cjs';
1
+ import { L as Logger, M as MetricsRecorder } from './setup-entry-C9aFZx3n.cjs';
2
+ export { A as AgentchatChannelConfig, a as AgentchatResolvedAccount, C as CreateMetricsOptions, I as IntegrationSocket, b as IntegrationSocketOptions, c as MetricsSnapshot, P as PromFactory, d as PromRegistryLike, S as SocketBlocked, e as SocketDisconnect, f as SocketHandlers, g as SocketHealth, h as SocketState, i as agentchatChannelEntry, j as agentchatPlugin, k as agentchatSetupEntry, j as agentchatSetupPlugin, l as createInMemoryMetrics, m as createMetrics, n as createNoopMetrics, i as default, p as parseChannelConfig, r as realtimeOptionsFor } from './setup-entry-C9aFZx3n.cjs';
3
3
  export { hasAgentChatConfiguredState } from './configured-state.cjs';
4
- import { AgentChatClient, Texts, ToolNamer } from 'agentchatme';
4
+ import { integration, InboxCard, TrayInvite, RealtimeClient, GateModelCall, Texts, AgentChatClient, ToolNamer } from 'agentchatme';
5
5
  import 'openclaw/plugin-sdk/channel-core';
6
6
  import 'zod';
7
7
 
8
8
  /**
9
- * The served texts: fetched from AgentChat, never bundled.
10
- *
11
- * Every text an agent sees is written once, in AgentChat's experience layer,
12
- * and served as data (`GET /v1/texts?runtime=openclaw`): the wake
13
- * instruction a turn starts with, the invite prompt, the identity line that
14
- * goes into the workspace `AGENTS.md`, and where the manual is. This module
15
- * fetches them at channel start and every 24 hours, keeps the last copy in
16
- * the plugin's state dir, and hands them out spelled for OpenClaw (the hosted
17
- * tools as `agentchat__<tool>`, see `./turn.ts`).
18
- *
19
- * When the server is unreachable at start the last cached copy is used; with
20
- * nothing cached the channel still starts (the socket connects, the gate can
21
- * run) and logs once — turns wait for the first successful fetch, which is
22
- * retried every few minutes until it lands.
9
+ * A turn's run, as OpenClaw reports it: admitted, watched until OpenClaw
10
+ * confirms it ended, and what AgentChat calls it made.
11
+ *
12
+ * Why the watch never gives up on a timeout
13
+ * ─────────────────────────────────────────
14
+ * `runtime.subagent.waitForRun({ runId, timeoutMs })` bounds the WAIT, not
15
+ * the run: "timeoutMs bounds the wait call; it does not cancel the run"
16
+ * (docs.openclaw.ai/plugins/sdk-runtime/background-work). A `timeout`
17
+ * status therefore says one of two things — the wait elapsed while the run
18
+ * goes on, or the run hit its own deadline (`agents.defaults.timeoutSeconds`,
19
+ * 48 h by default) and is over. Treating the first as an end would let the
20
+ * conversation be gated again and a second turn answer it while the first
21
+ * is still running. So the watch waits again until OpenClaw says the run
22
+ * is over, with OpenClaw's own rule for telling the two apart
23
+ * (`isTerminalAgentWaitTimeout` and the `untilTerminal` loop in
24
+ * github.com/openclaw/openclaw `src/agents/run-wait.ts`):
25
+ *
26
+ * - `ok`, `error` → ended
27
+ * - `pending` → running (a normal non-terminal observation)
28
+ * - `timeout` with `pendingError` → running (a failed attempt may still recover)
29
+ * - `timeout` with `endedAt`, `stopReason` or `livenessState` → ended (the run's own deadline)
30
+ * - `timeout` that is a hard timeout → ended: a `timeoutPhase` of
31
+ * preflight / provider / tool_execution / post_turn, or `providerStarted`
32
+ * without a restart stop (`resolveAgentRunTerminalFacts`)
33
+ * - `timeout` with an `error` → ended
34
+ * - any other `timeout` → running (the wait elapsed)
35
+ *
36
+ * On OpenClaw main a wait that elapses comes back bare — `{ runId, status:
37
+ * 'timeout' }`, no snapshot (`src/gateway/agent-turn/agent-wait.ts`) — a
38
+ * queued run as `pending` with `timeoutPhase: 'queue'`, and a gateway
39
+ * lifecycle reset as `timeout` with `timeoutPhase: 'gateway_draining'`. A
40
+ * bare `timeout` carries none of the metadata keys, so it is read by the
41
+ * timing rule below: one that took the whole wait is asked again.
42
+ *
43
+ * Older OpenClaw lines (2026.6 and 2026.7, e.g. 2026.6.10 and 2026.7.35)
44
+ * hand a plugin only `{ status, error }` (the wait metadata is dropped on the
45
+ * way out). There a terminal timeout
46
+ * is told apart by when it arrives: the gateway answers from the run's
47
+ * terminal record as soon as there is one, while an elapsed wait (and a
48
+ * failed attempt that may still recover) is answered when the wait's own
49
+ * timer fires. A `timeout` that comes back in under half the requested
50
+ * wait is an end; one that took the whole wait is asked again — if the run
51
+ * did end meanwhile, the next wait is answered at once from that record.
52
+ *
53
+ * Nothing here cancels a run: the plugin runtime has no abort for a
54
+ * subagent run, and OpenClaw's own run deadline is what bounds a run that
55
+ * never finishes. The watch stops early only when the plugin runtime is
56
+ * gone (the gateway is shutting down or the plugin was unloaded) — then
57
+ * there is nothing left to ask, and nothing left in this process to start
58
+ * a second turn either.
23
59
  */
24
60
 
25
- type TextsClient = Pick<AgentChatClient, 'texts'>;
26
- type TextsSourceKind = 'server' | 'cache';
27
- interface LoadedTexts {
28
- /** Spelled for OpenClaw. */
29
- readonly texts: Texts;
30
- readonly source: TextsSourceKind;
31
- readonly fetchedAt: string;
61
+ /** How a run ended, as OpenClaw confirmed it. `timeout` is the run's own deadline, never an elapsed wait. */
62
+ type RunEndStatus = 'ok' | 'error' | 'timeout';
63
+ /** AgentChat tool calls a run made, read from its transcript. */
64
+ interface AgentChatCalls {
65
+ /** AgentChat tool results in the transcript. */
66
+ readonly made: number;
67
+ /** Of those, the ones that came back as errors. */
68
+ readonly failed: number;
32
69
  }
33
- interface LoadTextsParams {
34
- readonly client: TextsClient;
35
- readonly accountId: string;
36
- readonly stateDir?: string | undefined;
37
- readonly now?: () => number;
38
- readonly log?: Logger | undefined;
39
- readonly timeoutMs?: number;
70
+
71
+ /**
72
+ * Where the integration meets OpenClaw's agent runtime.
73
+ *
74
+ * Two things only, both on the `PluginRuntime` OpenClaw hands a channel entry
75
+ * through `defineChannelPluginEntry({ setRuntime })`:
76
+ *
77
+ * 1. **The gate call** — `runtime.llm.complete({ messages, maxTokens,
78
+ * temperature, purpose })` runs one tool-free completion on the agent's
79
+ * own configured model and credentials (`LlmCompleteParams`,
80
+ * `plugin-sdk/types`; docs.openclaw.ai/plugins/sdk-runtime/models). The
81
+ * prompt is the SDK's rendering of the server's question and cards
82
+ * (`gate.buildPrompt`); nothing of ours is added. No tools are passed:
83
+ * the gate is a triage, and the integration records the verdicts. Without
84
+ * an `agentId` OpenClaw uses the ambient default agent; passing one is an
85
+ * OVERRIDE that OpenClaw 2026.10.9 rejects with
86
+ * `LLM_COMPLETION_NOT_AUTHORIZED` unless the operator set
87
+ * `plugins.entries.agentchat.llm.allowAgentIdOverride: true`. The
88
+ * integration therefore passes `agentId` only when the account is
89
+ * genuinely routed to a non-default agent (`agentIdOverride`), and the
90
+ * wizard / doctor write the opt-in in that case.
91
+ *
92
+ * 2. **The turn** — `runtime.subagent.run({ sessionKey, message, lane,
93
+ * deliver: false })` admits one agent run with the prompt as its message
94
+ * and no delivery of its final text (`SubagentRunParams`;
95
+ * docs.openclaw.ai/plugins/sdk-runtime/background-work — the same shape
96
+ * OpenClaw's own background features use with `deliver: false`). The
97
+ * turn's output is never routed anywhere: the agent's only way to say
98
+ * something on AgentChat is the hosted `agentchat__agentchat_send_message`
99
+ * tool during the turn. Admission and the run's end are reported
100
+ * separately (`TurnAdmission`): `done` resolves only once OpenClaw
101
+ * confirms the run is over (`./run.ts` — a `waitForRun` timeout bounds
102
+ * the wait, never the run, so it is asked again), with the AgentChat
103
+ * calls the run made read from its transcript when OpenClaw allows it.
104
+ *
105
+ * The agent id is resolved the way OpenClaw routes inbound for this channel
106
+ * (`channelRuntime.routing.resolveAgentRoute`), so the integration wakes the
107
+ * agent the operator bound to the account; `main` when nothing is bound.
108
+ */
109
+
110
+ interface TurnRequest {
111
+ readonly sessionKey: string;
112
+ readonly prompt: string;
113
+ readonly lane: string;
40
114
  }
41
115
  /**
42
- * Server first; the cache when the server cannot be reached. A server
43
- * success refreshes the cache (a cache write failure is logged, never
44
- * fatal). `null` when neither is available. Never throws.
116
+ * How an admitted turn's run ended, once OpenClaw confirmed it. `status`:
117
+ * `ok` / `error` / `timeout` (the run's own deadline — never an elapsed
118
+ * wait), or `gone` when the plugin runtime disappeared before an end was
119
+ * confirmed (the gateway is going down; nothing in this process starts
120
+ * another turn after it).
45
121
  */
46
- declare function loadTexts(params: LoadTextsParams): Promise<LoadedTexts | null>;
122
+ interface TurnOutcome {
123
+ readonly ran: boolean;
124
+ readonly runId?: string;
125
+ readonly status?: RunEndStatus | 'gone';
126
+ readonly error?: string;
127
+ /** AgentChat tool calls the run made, from its transcript; null when OpenClaw did not let the plugin read it (unknown, never zero). */
128
+ readonly agentchatCalls?: AgentChatCalls | null;
129
+ /** From admission to the confirmed end. */
130
+ readonly elapsedMs?: number;
131
+ }
47
132
  /**
48
- * The identity line for the key's own agent, spelled for OpenClaw — for the
49
- * placement paths that run outside the gateway (wizard, `channels add`,
50
- * `doctor --fix`, re-enable). Server, then cache; `null` when neither.
133
+ * What starting a turn reports: refused (OpenClaw did not admit
134
+ * the run — no runtime, a thrown `subagent.run`), or admitted with the
135
+ * promise of its end. `done` never rejects and resolves only when OpenClaw
136
+ * confirmed the end (or the runtime is gone).
51
137
  */
52
- declare function loadIdentityLine(params: LoadTextsParams): Promise<string | null>;
53
- interface TextsStoreOptions {
54
- readonly client: TextsClient;
55
- readonly accountId: string;
56
- readonly logger: Logger;
57
- readonly stateDir?: string | undefined;
58
- readonly refreshMs?: number;
59
- readonly retryMs?: number;
60
- readonly fetchTimeoutMs?: number;
61
- readonly now?: () => number;
62
- readonly setTimeout?: (fn: () => void, ms: number) => NodeJS.Timeout;
63
- readonly clearTimeout?: (handle: NodeJS.Timeout) => void;
138
+ type TurnAdmission = {
139
+ readonly ran: false;
140
+ readonly error: string;
141
+ } | {
142
+ readonly ran: true;
143
+ readonly runId: string;
144
+ readonly sessionKey: string;
145
+ readonly done: Promise<TurnOutcome>;
146
+ };
147
+ /** Starts one agent turn. Injectable so the loop wiring is testable without OpenClaw. */
148
+ type TurnStarter = (request: TurnRequest) => Promise<TurnAdmission>;
149
+ /** Whether a turn started now can look at AgentChat at all; `reason` is the operator line when it cannot. */
150
+ type TurnReadiness = {
151
+ readonly ready: true;
152
+ } | {
153
+ readonly ready: false;
154
+ readonly reason: string;
155
+ };
156
+
157
+ /**
158
+ * The after-turn recording for a turn the kit's loop no longer watches.
159
+ *
160
+ * Normally the kit's receive loop records what a turn did once its run ends
161
+ * (contract v1, D5: `turnOutcome` / `applyOutcome` on a fresh tray). Two
162
+ * kinds of turn end outside that watch, and this applies the same rule to
163
+ * them:
164
+ *
165
+ * - a turn handed off after 30 minutes (`AccountTurns.handOff`): the kit
166
+ * let go of it to free its slot, so without this an answer sent at
167
+ * minute 35 would record nothing and the card would be gated again;
168
+ * - a turn a gateway restart ended, read again on the next start, and a
169
+ * run OpenClaw's restart resume started in that turn's session
170
+ * (`AccountTurns.adopt`).
171
+ *
172
+ * The kit's per-anchor memory of earlier silent turns is the loop's own, so
173
+ * a silent end here counts as the first (`silentBefore` 0): nothing is
174
+ * recorded and the card is gated again — never a dismiss on a count this
175
+ * side cannot know.
176
+ */
177
+
178
+ /** Records what a turn did, from a fresh tray. Never rejects. */
179
+ type AfterTurnRecorder = (record: RunRecord, end: integration.TurnEnd) => Promise<void>;
180
+
181
+ /**
182
+ * The turns in flight, on disk: `<state>/agentchat/<accountId>/turns.json`.
183
+ *
184
+ * Why it exists: a gateway restart ends every run with the process, and
185
+ * OpenClaw (current main) may then continue a plugin's turn session on its
186
+ * own. A plugin run started with no requester is registered under the
187
+ * agent's main session (`registerPluginSubagentRunFromGateway`,
188
+ * `src/gateway/server-methods/agent-subagent-registration.ts`), restart
189
+ * resume walks a live subagent session up to that root
190
+ * (`resolveRootSubagentRequester`) and wakes it with "send a fresh
191
+ * instruction to the same retained child session when appropriate"
192
+ * (`src/gateway/session-restart-resume.ts`). So after a restart the agent
193
+ * may run our turn's session again while the new receive loop would gate
194
+ * the same card and start a second turn. The new process knows neither the
195
+ * old run nor its conversation, and a third-party plugin has no public API
196
+ * that lists live runs (`readSessionFacts` is for bundled / trusted
197
+ * official plugins only). So the turns in flight are written here, and the
198
+ * next start holds their conversations for a while (`AccountTurns.adopt`).
199
+ *
200
+ * What is written: the run id, the turn's session key, what it held (the
201
+ * conversation or invite id and the message the gate read through), and the
202
+ * few card fields the after-turn rule compares — never message text.
203
+ * Written atomically (temp file + rename) on every change; an entry whose
204
+ * run ended stays `KEEP_ENDED_MS` longer, because a restart ends a run
205
+ * before it ends the process. Never throws: a file that cannot be written
206
+ * costs only the defense, and one that cannot be read is treated as empty.
207
+ */
208
+
209
+ /** The card fields the after-turn rule reads (`turnOutcome`): no message text. */
210
+ type StoredCard = Pick<InboxCard, 'conversation_id'> & {
211
+ readonly last_message_id?: string | null;
212
+ readonly your_last_message_at?: string | null;
213
+ readonly you_owe_reply?: boolean;
214
+ readonly your_last_decision?: InboxCard['your_last_decision'] | null;
215
+ };
216
+ interface StoredTurn {
217
+ readonly runId: string;
218
+ readonly kind: 'reply' | 'invite';
219
+ /** The conversation id (reply) or the invite id. */
220
+ readonly id: string;
221
+ readonly anchor: string | null;
222
+ readonly sessionKey: string;
223
+ /** Local clock, ms. */
224
+ readonly startedAt: number;
225
+ /** When the first turn of this chain started (a turn continued after a restart keeps it): stored turns age out by it. */
226
+ readonly firstStartedAt?: number;
227
+ readonly category?: string | null;
228
+ readonly card?: StoredCard;
229
+ }
230
+ declare class TurnStore {
231
+ readonly file: string;
232
+ constructor(accountId: string, stateDir?: string);
233
+ /** What the last process left. Empty when there is no file or it cannot be read. */
234
+ load(): StoredTurn[];
235
+ /** Replace the file with `turns` (removed when empty). Returns false when the write failed. */
236
+ write(turns: readonly StoredTurn[]): boolean;
237
+ }
238
+
239
+ /**
240
+ * The account's turns, kept for the life of the gateway process — not of one
241
+ * receive loop.
242
+ *
243
+ * A turn holds its conversation (or invite) until OpenClaw confirms its run
244
+ * ended (`./run.ts`): while it runs, the card stays on the tray (nothing is
245
+ * recorded before the turn ends), and gating it again would start a second
246
+ * turn that answers the same message twice. The kit's `TurnTracker` is what
247
+ * holds it, and there is one per account, handed to every loop for the
248
+ * account: OpenClaw restarts an account's channel task on a config change
249
+ * while the run started under the old loop goes on in OpenClaw's lane, so the
250
+ * next loop leaves that card alone until the run ends (the old loop still
251
+ * records what the run did). When a run that held a card ends, the account's
252
+ * live loop is woken, so a message that arrived meanwhile is gated at once.
253
+ *
254
+ * A run OpenClaw never reports as ended must not freeze the account. After
255
+ * `TURN_OVERDUE_MS` the turn is handed off, once: the kit's slot is released
256
+ * and new turns move to a fresh OpenClaw lane (OpenClaw runs a lane's runs
257
+ * one after another, so they would otherwise queue behind the hung run) —
258
+ * other conversations get turns again — while this module keeps the
259
+ * conversation held until OpenClaw reports that run ended, and then applies
260
+ * the after-turn rule itself (`./after-turn.ts`: the kit no longer watches
261
+ * it). At most `MAX_HUNG_TURNS` are held that way; beyond that, readiness
262
+ * says not-ready (no gate calls) and status and doctor say why. An operator
263
+ * can let one go: `openclaw agentchat release <conversation_id>`.
264
+ *
265
+ * Every hold here is keyed by run id. A run that was handed off or let go of
266
+ * is never handed off again — whatever later "still running" reports say —
267
+ * so a release sticks; and a run whose kit hold was released while OpenClaw
268
+ * was still admitting it starts out let go of. Either way the old run can
269
+ * never release a newer turn's hold on the same conversation.
270
+ *
271
+ * Gate off (single-run mode) one run reads the whole tray, so two would
272
+ * answer the same cards: past `TURN_OVERDUE_MS` the cycle waiting on the run
273
+ * is let go of (the loop is not stuck in it), but no new run starts while the
274
+ * handed-off one lives — readiness says not-ready, status and doctor say why,
275
+ * and `openclaw agentchat release <run id> --force` frees it.
276
+ *
277
+ * A gateway restart ends every run with the process, and OpenClaw (current
278
+ * main) may continue a plugin's turn session afterwards: a plugin run with
279
+ * no requester is registered under the agent's main session
280
+ * (`src/gateway/server-methods/agent-subagent-registration.ts`), restart
281
+ * resume walks a live subagent session up to that root — the "subagent"
282
+ * skip applies to the root, which is the main session, not ours
283
+ * (`src/gateway/session-restart-resume.ts`, `restartResumeSkipReason`) — and
284
+ * wakes it with "send a fresh instruction to the same retained child
285
+ * session when appropriate". Tested live: on 2026.11.5-beta.1 a restart
286
+ * during a turn resumed `agent:<id>:main` with the restart text, its context
287
+ * listing the AgentChat turn sessions; 2026.10.9 aborted the run and resumed
288
+ * nothing. So the turns in flight are written to disk (`./turn-store.ts`)
289
+ * and the next start adopts them (`adopt`): each conversation is held for
290
+ * `RESTART_HOLD_MS`, and the after-turn rule is applied to what the ended run
291
+ * did at once and again when the hold expires (an answer it — or the resumed
292
+ * main session — sent records `reply`, so the card is not gated again). A
293
+ * run OpenClaw starts in that turn's session during the hold — seen through
294
+ * the `model_call_started` hook, the public way a plugin sees runs it did not
295
+ * start — keeps the conversation held as a turn of its own: past
296
+ * `TURN_OVERDUE_MS` it is handed off and counts toward `MAX_HUNG_TURNS`, and
297
+ * when it ends it gets the after-turn rule. A stored turn first started more
298
+ * than `STORED_TURN_MAX_AGE_MS` ago is dropped, so a restart storm cannot
299
+ * re-adopt it forever. Not covered (accepted): a continuation that starts
300
+ * after the hold, when the conversation may have been gated again; the wake
301
+ * text AgentChat serves for OpenClaw is to tell the agent not to resume an
302
+ * AgentChat turn after a restart (a server change). A plugin reload waits for the runs (OpenClaw drains a plugin's
303
+ * admitted work first, and every turn holds it until it ends).
304
+ */
305
+
306
+ /** Hung turns held at once before the account stops gating (each holds one conversation). */
307
+ declare const MAX_HUNG_TURNS = 2;
308
+ /** reply: a conversation; invite: a group invite; run: the one run of a gate-off cycle. */
309
+ type TurnKind = 'reply' | 'invite' | 'run';
310
+ /** One OpenClaw run started for the account. */
311
+ interface RunRecord {
312
+ readonly runId: string;
313
+ readonly kind: TurnKind;
314
+ /** The conversation id (reply), the invite id (invite), or the run id (a gate-off run). */
315
+ readonly id: string;
316
+ /** The message the gate's verdict read through (reply turns). */
317
+ readonly anchor: string | null;
318
+ readonly sessionKey: string;
319
+ /** Local clock, ms. */
320
+ readonly startedAt: number;
321
+ /** The loop that started it. */
322
+ readonly owner: string;
323
+ /** reply: the card the gate decided on and its category — what the after-turn rule compares. */
324
+ readonly card?: InboxCard;
325
+ readonly category?: string | null;
326
+ /** invite: the invite the turn was for. */
327
+ readonly invite?: TrayInvite;
328
+ /** When the first turn of this chain started: a turn continued after a restart keeps its original's (stored turns age out by it). */
329
+ readonly firstStartedAt?: number;
330
+ }
331
+ type ReleaseResult = {
332
+ readonly released: true;
333
+ readonly what: 'hung' | 'running' | 'restart';
334
+ readonly key: string;
335
+ readonly runId: string | null;
336
+ } | {
337
+ readonly released: false;
338
+ readonly reason: string;
339
+ };
340
+ /** Watches a run this process did not start until OpenClaw reports it ended; null when it cannot say. */
341
+ type RunWatcher = (record: RunRecord) => Promise<integration.TurnEnd | null>;
342
+ /** The AgentChat calls an ended run made, from its transcript; null when unknown. */
343
+ type CallReader = (sessionKey: string, runId: string) => Promise<integration.AgentChatCallCount | null>;
344
+ interface TurnsWiring {
345
+ /** Applies the after-turn rule to a turn that ended outside the kit's watch. */
346
+ readonly recorder?: AfterTurnRecorder;
347
+ /** Where the turns in flight are written (the restart defense). */
348
+ readonly store?: TurnStore;
349
+ readonly watch?: RunWatcher;
350
+ readonly readCalls?: CallReader;
351
+ readonly logger?: Logger;
64
352
  }
65
353
  /**
66
- * The texts for one running account: loaded at start, refreshed on a timer,
67
- * available synchronously to the invoker. `ensure()` is what a cycle calls
68
- * when it needs them: the current copy, or one load attempt right now.
354
+ * kit: the kit's loop holds it. watch: a run OpenClaw started in an adopted
355
+ * turn's session, held here. hung: handed off, held here. released: let go
356
+ * of; it holds nothing.
69
357
  */
70
- declare class TextsStore {
71
- private readonly client;
72
- private readonly accountId;
73
- private readonly logger;
74
- private readonly stateDir;
75
- private readonly refreshMs;
76
- private readonly retryMs;
77
- private readonly fetchTimeoutMs;
358
+ type RunState = 'kit' | 'watch' | 'hung' | 'released';
359
+ /** A turn OpenClaw is admitting: whether its kit hold was released meanwhile. */
360
+ interface Admission {
361
+ readonly key: string;
362
+ released: boolean;
363
+ }
364
+ declare class AccountTurns {
365
+ /** The kit's tracker for the account, shared by every loop for it. */
366
+ readonly tracker: integration.TurnTracker;
367
+ private readonly entries;
368
+ /** Turns the last process left in flight, by session key. */
369
+ private readonly adopted;
370
+ /** Turns OpenClaw is admitting right now. */
371
+ private readonly admitting;
372
+ /** Ended runs still written to the store (`KEEP_ENDED_MS`). */
373
+ private readonly kept;
374
+ private keptTimer;
375
+ private live;
376
+ private wiring;
377
+ /** Which OpenClaw lane new turns go to; moves on at every hand-off (a hung run blocks its lane). */
378
+ private lane;
78
379
  private readonly now;
79
- private readonly _setTimeout;
80
- private readonly _clearTimeout;
81
- private loaded;
82
- private timer;
83
- private inFlight;
84
- private stopped;
85
- private missingAnnounced;
86
- private readonly listeners;
87
- loads: number;
88
- serverLoads: number;
89
- constructor(options: TextsStoreOptions);
90
- /** The texts spelled for OpenClaw, or null until the first copy exists. */
91
- get current(): Texts | null;
92
- get source(): TextsSourceKind | null;
93
- get fetchedAt(): string | null;
94
- /** Called with every copy that arrives from the server (not with a cached one). */
95
- onServerCopy(listener: (texts: Texts, source: TextsSourceKind) => void): () => void;
96
- /** First load (server, then cache), then the timer. Resolves after the first attempt; never throws. */
97
- start(): Promise<Texts | null>;
98
- /** The current copy, or one load attempt now (coalesced with any in flight). */
99
- ensure(): Promise<Texts | null>;
100
- /** Force a refresh (tests, operators). Coalesced. */
101
- refresh(): Promise<Texts | null>;
102
- stop(): void;
103
- private load;
104
- private arm;
380
+ constructor(options?: {
381
+ now?: () => number;
382
+ });
383
+ /** The account's after-turn recorder, store and run watcher (each account start; the latest wins). */
384
+ configure(wiring: TurnsWiring): void;
385
+ /** The loop now receiving for the account; a held run that ends wakes it. `run` = the loop's own async context (default: as called). */
386
+ setLive(owner: string, wake: () => void, run?: <T>(fn: () => T) => T): void;
387
+ clearLive(owner: string): void;
388
+ /** A turn is about to be admitted by OpenClaw: watch whether its kit hold is released meanwhile. */
389
+ admission(kind: 'reply' | 'invite', id: string): Admission;
390
+ /** OpenClaw refused the turn: nothing to watch. */
391
+ admitted(admission: Admission): void;
392
+ /**
393
+ * A run OpenClaw admitted. `letGo` (gate-off runs): ends the cycle waiting
394
+ * on it when it is handed off or released. `admission`: a turn whose kit
395
+ * hold was released during admission starts out let go of.
396
+ */
397
+ started(record: RunRecord, options?: {
398
+ letGo?: () => void;
399
+ admission?: Admission;
400
+ }): void;
401
+ run(runId: string): RunRecord | undefined;
402
+ /** Where the run stands (`null`: not a run of this account, or ended). */
403
+ stateOf(runId: string): RunState | null;
404
+ /** Every run OpenClaw has not reported ended that still holds something, oldest first. */
405
+ runningRuns(): RunRecord[];
406
+ hungRuns(): RunRecord[];
407
+ get hungCount(): number;
408
+ /** The handed-off gate-off run still going, if any: no new run starts while it lives. */
409
+ hungSingleRun(): RunRecord | null;
410
+ /** Conversations (and invites) held after a restart: adopted (until when), or continued by a run OpenClaw started. */
411
+ restartHolds(): Array<{
412
+ readonly record: RunRecord;
413
+ readonly until: number | null;
414
+ readonly watching: string | null;
415
+ }>;
416
+ /** The lane generation new turns start on (`integrationLane(accountId, laneGeneration)`). */
417
+ get laneGeneration(): number;
418
+ /**
419
+ * OpenClaw reported the run ended (`end`: what it did, when known). A turn
420
+ * held here (handed off, or continued after a restart) gets the after-turn
421
+ * rule, then its hold drops and the live loop is woken. A turn the kit
422
+ * still holds is the kit's to record; the live loop is woken once the card
423
+ * is free, only when an earlier loop started it. A run let go of records
424
+ * nothing.
425
+ */
426
+ ended(runId: string, end?: integration.TurnEnd): Promise<void>;
427
+ /**
428
+ * Hand a long run off, once, by run id: release the kit's slot for it (its
429
+ * loop records nothing for it and may start other turns) and hold the
430
+ * conversation here until the run ends. A gate-off run: the cycle waiting
431
+ * on it is let go of. A continued run is already held here: it becomes
432
+ * hung (counted toward `MAX_HUNG_TURNS`). Returns the record when it was
433
+ * handed off now; null when it was already handed off or let go of.
434
+ */
435
+ handOff(runId: string): RunRecord | null;
436
+ /**
437
+ * An operator lets go of a conversation's (or invite's) turn: a hung hold,
438
+ * a restart hold, or — past `TURN_OVERDUE_MS`, or with `force` — a turn
439
+ * still running. Its run may still be live and answer: a second reply is
440
+ * then possible, which is why a turn under 30 minutes (most likely still
441
+ * working) is refused without `force`. A gate-off run always needs
442
+ * `force`: it reads the whole tray, so a new run would answer the same
443
+ * cards while it may still be going.
444
+ */
445
+ release(id: string, options?: {
446
+ force?: boolean;
447
+ }): ReleaseResult;
448
+ private releaseNow;
449
+ private refuseYoung;
450
+ private refuseSingleRun;
451
+ /**
452
+ * Adopt the turns the last process left in flight (the store). Each one's
453
+ * conversation (or invite) is held at once — before the loop's first gate —
454
+ * for `RESTART_HOLD_MS`; the after-turn rule is applied to what the ended
455
+ * run did now and again when the hold expires. A run OpenClaw starts in the
456
+ * turn's session meanwhile (`observeRun`) takes the hold over. A turn first
457
+ * started more than `STORED_TURN_MAX_AGE_MS` ago is dropped. Returns what
458
+ * was adopted.
459
+ */
460
+ adopt(stored?: readonly StoredTurn[]): RunRecord[];
461
+ /**
462
+ * A run started in some session (the `model_call_started` hook). One in
463
+ * the session of a turn adopted after a restart is OpenClaw continuing
464
+ * that turn: it takes the hold over as a turn of its own (`watch`), handed
465
+ * off past `TURN_OVERDUE_MS` like any other.
466
+ */
467
+ observeRun(runId: string, sessionKey: string | undefined): void;
468
+ private watchContinued;
469
+ private recordRestartEnded;
470
+ /**
471
+ * The hold expired with nothing continuing the turn: the after-turn rule
472
+ * once more — the resumed main session may have answered the card
473
+ * meanwhile — then the conversation is free.
474
+ */
475
+ private expireAdopted;
476
+ private finishAdopted;
477
+ /** An ended run stays in the store a little longer: a restart ends the run before it ends the process. */
478
+ private keep;
479
+ /** The next prune at the oldest kept entry's expiry. */
480
+ private schedulePrune;
481
+ private pruneKept;
482
+ private persist;
483
+ private wakeWhenFree;
484
+ }
485
+ /** The account's turns, created on first use and kept for the process. */
486
+ declare function accountTurns(accountId: string): AccountTurns;
487
+ /** The account's kit tracker (shared by every loop for the account). */
488
+ declare function trackerFor(accountId: string): integration.TurnTracker;
489
+
490
+ /**
491
+ * The receive loop for one account: the SDK kit's `ReceiveLoop`, with what
492
+ * is OpenClaw's plugged in.
493
+ *
494
+ * socket frame / connect / wake frame / invite ──► one cycle per burst ──► tray
495
+ * ──► gate call on the agent's own model (gate-call mode) ──► dismiss / defer at once
496
+ * ──► one OpenClaw run per reply and per invite ──► the after-turn rule (D5)
497
+ *
498
+ * The cycle, the tray read, the gate, which cards a running turn holds, the
499
+ * prompts, and what is recorded after a turn are the kit's. This module
500
+ * supplies the runtime parts: the gate call (`runtime.llm.complete`, tool
501
+ * free), the turn (`./turns.ts` over `runtime.subagent.run`), whether a turn
502
+ * can have the hosted tools (`readiness`), and the log lines and metrics.
503
+ *
504
+ * `AGENTCHAT_REPLY_GATE_ENABLED=0` switches to the kit's single-run mode:
505
+ * one run with the served wake instruction whenever something is owed; the
506
+ * agent judges every card inside it and records its own verdicts.
507
+ */
508
+
509
+ interface IntegrationLoopOptions {
510
+ readonly accountId: string;
511
+ readonly agentId: string;
512
+ readonly client: integration.ReceiveLoopClient;
513
+ readonly texts: integration.TextsSource;
514
+ /** The SDK socket (built by `IntegrationSocket`); the loop connects and disconnects it. `null`: wakes only through `wake()`. */
515
+ readonly socket: RealtimeClient | null;
516
+ /** The agent's handle, for the echo filter (learned from the tray when absent). */
517
+ readonly handle?: string | undefined;
518
+ readonly callModel: GateModelCall;
519
+ readonly startRun: TurnStarter;
520
+ /** The account's turns, shared with every loop for the account in this process (`accountTurns`). */
521
+ readonly turns: AccountTurns;
522
+ readonly logger: Logger;
523
+ readonly metrics?: MetricsRecorder;
524
+ readonly readiness?: () => TurnReadiness;
525
+ /** `false`: single-run mode (no gate call). */
526
+ readonly gateEnabled?: boolean;
527
+ /** D5 pacing window (the kit's default 60 s); tests shorten it. */
528
+ readonly paceMs?: number;
529
+ readonly quietMs?: number;
530
+ readonly maxMs?: number;
531
+ readonly now?: () => number;
532
+ readonly setTimeout?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
533
+ readonly clearTimeout?: (handle: ReturnType<typeof setTimeout>) => void;
534
+ }
535
+ interface IntegrationLoop {
536
+ readonly loop: integration.ReceiveLoop;
537
+ /** Stop the loop (it disconnects the socket). Turns already running go on and still have their outcome recorded. */
538
+ stop(): Promise<void>;
105
539
  }
540
+ declare function createIntegrationLoop(options: IntegrationLoopOptions): IntegrationLoop;
106
541
 
107
542
  declare function hostedMcpUrl(apiBase?: string): string;
108
543
  interface McpServerEntry {
@@ -122,16 +557,19 @@ interface McpProbeResult {
122
557
  readonly serverName?: string;
123
558
  readonly serverVersion?: string;
124
559
  readonly protocolVersion?: string;
125
- /** Whether the server published `instructions` (OpenClaw injects them into the system prompt). */
126
- readonly hasInstructions?: boolean;
560
+ /** Every tool the server listed for this key (bare names). */
561
+ readonly tools?: readonly string[];
562
+ /** Tools a turn needs that the server did not list. */
563
+ readonly missing?: readonly string[];
127
564
  readonly error?: string;
128
565
  }
129
566
  /**
130
- * Doctor check: is the hosted MCP server reachable with this key? Sends one
131
- * MCP `initialize` over Streamable HTTP with the bearer key — the same
132
- * request OpenClaw makes on connect — and reads the server's answer. A
133
- * `401` means the key does not authenticate; a transport error means the
134
- * endpoint is not reachable from here.
567
+ * Doctor and status check: can this key list the hosted tools? The SDK
568
+ * kit's `probeHostedTools` — one MCP `initialize` and one `tools/list` over
569
+ * Streamable HTTP with the bearer key, the requests OpenClaw makes on
570
+ * connect. A `401` means the key does not authenticate; a transport error
571
+ * means the endpoint is not reachable from here; a list without the tools a
572
+ * turn needs means a turn could not look.
135
573
  */
136
574
  declare function probeHostedMcp(params: {
137
575
  apiKey: string;
@@ -163,65 +601,127 @@ declare function probeHostedMcp(params: {
163
601
  declare const AGENTCHAT_CHANNEL_ID: "agentchat";
164
602
  declare const AGENTCHAT_DEFAULT_ACCOUNT_ID = "default";
165
603
 
166
- interface WakeCoalescerOptions {
167
- readonly onFire: () => void;
168
- /** Called when a delayed (retry-ladder) wake fires, before it is counted like any other wake. */
169
- readonly onDelayedWake?: () => void;
170
- readonly debounceMs?: number;
171
- readonly maxWindowMs?: number;
604
+ /**
605
+ * How the kit's receive loop starts a turn on OpenClaw.
606
+ *
607
+ * The loop (gate-call mode) decides which conversations and invites get a
608
+ * turn, composes the prompt from the served texts, and holds the card in
609
+ * its tracker while the turn runs; this adapter runs the turn as one
610
+ * OpenClaw agent run (`runtime.subagent.run`, `deliver: false`, a fresh
611
+ * session, the account's lane) and reports its end in the kit's terms once
612
+ * OpenClaw has confirmed it (`./run.ts`):
613
+ *
614
+ * - `ok` → `completed`, with the AgentChat calls the
615
+ * run made (from its transcript; null = unknown)
616
+ * - `error`, `timeout` → `failed` (the run's own deadline is a failure,
617
+ * never an elapsed wait)
618
+ * - the plugin runtime is gone → `still_running` with no `next`: the tracker
619
+ * keeps the conversation, nothing in this process
620
+ * starts a second turn for it
621
+ *
622
+ * A run that never ends keeps holding its conversation: the loop cannot end
623
+ * a turn, and the plugin runtime offers no abort for a subagent run. After
624
+ * 30 minutes the turn is handed off (`AccountTurns.handOff`): the kit's slot
625
+ * is freed so other conversations get turns, while that one stays held until
626
+ * OpenClaw reports the run ended (its run deadline,
627
+ * `agents.defaults.timeoutSeconds`) — then the after-turn rule is applied
628
+ * to it there, with the card the gate saw, which the record carries.
629
+ */
630
+
631
+ interface LoopTurnStarterOptions {
632
+ readonly accountId: string;
633
+ /** The OpenClaw agent the account is routed to. */
634
+ readonly agentId: string;
635
+ /** Starts one OpenClaw run and reports its confirmed end (`createRuntimeTurnStarter`). */
636
+ readonly startRun: TurnStarter;
637
+ /** The account's turns (`accountTurns`): every run is recorded there until OpenClaw reports it ended. */
638
+ readonly turns: AccountTurns;
639
+ /** The loop this starter belongs to. */
640
+ readonly owner: string;
641
+ readonly logger: Logger;
172
642
  readonly now?: () => number;
173
- readonly setTimeout?: (fn: () => void, ms: number) => NodeJS.Timeout;
174
- readonly clearTimeout?: (handle: NodeJS.Timeout) => void;
175
643
  }
176
- declare class WakeCoalescer {
177
- private readonly onFire;
178
- private readonly onDelayedWake;
179
- private readonly debounceMs;
180
- private readonly maxWindowMs;
181
- private readonly now;
182
- private readonly _setTimeout;
183
- private readonly _clearTimeout;
184
- private timer;
185
- private burstStartedAt;
186
- private delayed;
187
- private delayedDeadline;
188
- private stopped;
189
- wakes: number;
190
- absorbed: number;
191
- fires: number;
192
- constructor(options: WakeCoalescerOptions);
193
- /** True while a debounce timer is armed. */
194
- get armed(): boolean;
195
- /** True while a retry wake is scheduled and has not fired. */
196
- get delayedPending(): boolean;
197
- /**
198
- * A wake. The first one of a burst arms the window; every later one is
199
- * absorbed and restarts it (trailing edge), never past the burst's cap.
200
- */
201
- wake(): void;
202
- /** A delayed wake (retry ladder). The sooner pending deadline is kept. */
203
- wakeAfter(delayMs: number): void;
204
- /** Cancel everything; later wakes are ignored. */
205
- stop(): void;
206
- private fire;
644
+ /** The kit's `TurnStarter` for OpenClaw. */
645
+ declare function createLoopTurnStarter(options: LoopTurnStarterOptions): integration.TurnStarter;
646
+ /** What OpenClaw reported, as the kit's D5 rule reads it. `ok` without an error is the only completed end. */
647
+ declare function turnEndOf(outcome: TurnOutcome): integration.TurnEnd;
648
+
649
+ /**
650
+ * The served texts: the SDK kit's `TextsCache`, kept in the plugin's state dir.
651
+ *
652
+ * Every text an agent sees is written once on the server and served as data
653
+ * (`GET /v1/texts?runtime=openclaw`): the wake instruction, the invite
654
+ * prompt, the gate-call preamble and answer format, the identity line, where
655
+ * the manual is. The kit's cache fetches them at channel start and daily,
656
+ * keeps the last good copy in `<state dir>/agentchat/<accountId>/texts.json`
657
+ * (an offline start is not mute), and backs off after a failure. The server
658
+ * spells the hosted tools for `runtime=openclaw` the way OpenClaw exposes
659
+ * them (`agentchat__<tool>`); the copy handed out is still passed through the
660
+ * idempotent re-speller (a no-op then), so a server that serves bare names
661
+ * again — a rolled-back deploy — cannot hand the agent wrong tool names. The
662
+ * stored copy is always server-verbatim.
663
+ */
664
+
665
+ type TextsClient = Pick<AgentChatClient, 'texts'> & {
666
+ readonly baseUrl?: string;
667
+ };
668
+ /** Re-spell the hosted tool names in every agent-facing text. Pure, idempotent; the stored copy stays server-verbatim. */
669
+ declare function spellTextsForOpenClaw(texts: Texts): Texts;
670
+ /** The kit's cache for one account, its file in the plugin's state dir. */
671
+ declare function createTextsCache(params: {
672
+ client: TextsClient;
673
+ accountId: string;
674
+ stateDir?: string | undefined;
675
+ logger?: Logger;
676
+ }): integration.TextsCache;
677
+ /**
678
+ * What the receive loop reads: the cache's copy through the re-speller. The
679
+ * spelled copy is memoised per served copy, so a cycle does not re-spell.
680
+ */
681
+ declare class OpenClawTexts implements integration.TextsSource {
682
+ private readonly cache;
683
+ private spelledFrom;
684
+ private spelled;
685
+ constructor(cache: integration.TextsCache);
686
+ current(): Texts | null;
687
+ ensure(): Promise<Texts | null>;
688
+ get source(): string;
689
+ get fetchedAt(): string | null;
690
+ get lastError(): string | null;
691
+ private spell;
692
+ }
693
+ interface LoadTextsParams {
694
+ readonly client: TextsClient;
695
+ readonly accountId: string;
696
+ readonly stateDir?: string | undefined;
207
697
  }
698
+ /**
699
+ * The identity line for the key's own agent, as served — for the
700
+ * placement paths that run outside the gateway (wizard, `channels add`,
701
+ * `doctor --fix`, re-enable). One fetch through the kit's cache (the server,
702
+ * else the file it keeps); `null` when neither has a copy. Never throws.
703
+ */
704
+ declare function loadIdentityLine(params: LoadTextsParams): Promise<string | null>;
208
705
 
209
706
  /**
210
- * Turns: the names OpenClaw gives the hosted tools, the prompts a turn starts
211
- * with, and the session keys and lane the turns run on.
707
+ * Turns: the name OpenClaw gives the hosted tools, and the session keys and
708
+ * lane the turns run on.
212
709
  *
213
- * No product text lives here. The wake instruction and the invite prompt are
214
- * served by AgentChat (`GET /v1/texts`, fetched by `./texts.ts`) and placed
215
- * by this module; the one line of our own states a fact (which conversation
216
- * the gate decided to answer), never judgement.
710
+ * No text lives here. What a turn starts with — the served wake instruction
711
+ * or invite prompt and the id it is about — is composed by the SDK kit's
712
+ * receive loop from `GET /v1/texts?runtime=openclaw`, which the server spells
713
+ * the way OpenClaw exposes the hosted tools (`agentchat__<tool>`). The plugin
714
+ * still re-spells served text on the way out (`spellToolsForOpenClaw`): it
715
+ * is a no-op on `agentchat__…`, and it keeps the tool names right if a
716
+ * server that serves bare names comes back (a rolled-back deploy). The tray's
717
+ * gate question (`GET /v1/inbox` serves bare names) is spelled by the kit's
718
+ * gate with `OPENCLAW_TOOL_NAMER`.
217
719
  *
218
720
  * OpenClaw exposes an MCP server's tools to the model as `<server>__<tool>`:
219
721
  * the tool-policy pipeline builds the namespace prefix as
220
722
  * `normalizeToolName(sanitizeServerName(serverName) + "__")`
221
723
  * (`openclaw/dist/tool-policy-*.js`, 2026.6.10) and the docs describe the
222
- * same shape (docs.openclaw.ai/tools/mcp). The server spells the hosted
223
- * tools by their bare names (`agentchat_inbox`); `spellToolsForOpenClaw`
224
- * re-spells exactly those tokens so the agent is told the names it can call.
724
+ * same shape (docs.openclaw.ai/tools/mcp).
225
725
  */
226
726
 
227
727
  /** Name of the MCP server entry this plugin places. Changing it changes every tool name the model sees — keep in lockstep with `./mcp.ts`. */
@@ -234,22 +734,8 @@ declare function mcpToolName(tool: string): string;
234
734
  * OpenClaw spelling itself is not prefixed twice.
235
735
  */
236
736
  declare const OPENCLAW_TOOL_NAMER: ToolNamer;
237
- /** Re-spell every bare hosted tool name in a served text the way OpenClaw exposes it. Pure, idempotent. */
737
+ /** Re-spell every bare hosted tool name in a served text the way OpenClaw exposes it. Pure, idempotent; a no-op on text the server already spelled. */
238
738
  declare function spellToolsForOpenClaw(text: string): string;
239
- /**
240
- * The prompt a wake turn starts with: the served wake instruction and, when
241
- * the gate decided a specific conversation, one factual line naming it. The
242
- * `reply` verdict is recorded when the turn has completed — never at its
243
- * start — so while the turn runs the conversation is still unread and its
244
- * card still on the tray; the line says so and names the conversation to
245
- * open. The model may record its own verdict in the turn (the served texts
246
- * tell it to record `reply` after its send, or `dismiss` when it read and
247
- * chose not to answer); the invoker then records nothing more for it. Only
248
- * a turn that recorded none gets `reply` from the host when it completes.
249
- */
250
- declare function wakeTurnPrompt(texts: Pick<Texts, 'wake_instruction'>, conversationId?: string): string;
251
- /** The prompt a group-invite turn starts with: the served invite prompt. */
252
- declare function inviteTurnPrompt(texts: Pick<Texts, 'invite_prompt'>): string;
253
739
 
254
740
  /**
255
741
  * Error taxonomy for the AgentChat channel plugin.
@@ -284,35 +770,24 @@ declare class AgentChatChannelError extends Error {
284
770
  }
285
771
 
286
772
  /**
287
- * Minimal HTTP client used by the setup plugin (P7) to:
288
- * - verify an API key is live before finalizing setup (`validateApiKey`)
289
- * - drive the email-OTP self-registration flow for agents without a key yet
290
- * (`registerAgentStart` → `registerAgentVerify`)
291
- * - drive the email-OTP recovery flow that re-issues a lost API key
292
- * (`recoverAgentStart` → `recoverAgentVerify`)
293
- *
294
- * Why this lives separately from `outbound.ts`:
295
- * - `outbound.ts` is the hot-path message sender. It wants retries, a circuit
296
- * breaker, metrics, and a long-lived `fetch`. Setup is one-shot, low-rate,
297
- * user-interactive — a 200ms validation call doesn't need any of that.
298
- * - Setup runs before the runtime exists; coupling it to `OutboundAdapter`
299
- * (which expects a parsed `AgentchatChannelConfig`) would force an odd
300
- * partial-config path during registration.
301
- *
302
- * The server endpoints this module targets are stable AgentChat REST calls:
303
- * - `GET /v1/agents/me` → 200 OK when the key authenticates
304
- * - `POST /v1/register` → 200 with `{ pending_id }`
305
- * - `POST /v1/register/verify` → 201 with `{ agent, api_key }` on success
306
- * - `POST /v1/agents/recover` → 200 with `{ pending_id, message }` — always,
307
- * whether or not the email + handle match
308
- * a live agent (no existence leak)
309
- * - `POST /v1/agents/recover/verify` → 200 with `{ handle, api_key }` on success
310
- *
311
- * Registration and recovery deliberately bypass the `agentchatme` SDK: the
312
- * SDK's `recover(email)` predates the handle + email recovery contract and
313
- * has no way to send `handle`, and the pinned SDK floor cannot move until a
314
- * compatible SDK is published. Owning these four calls here keeps the plugin
315
- * on the current server contract regardless of which SDK version resolves.
773
+ * Setup calls, through the `agentchatme` SDK:
774
+ * - verify an API key is live before finalizing setup (`validateApiKey`,
775
+ * `client.getMe()` → `GET /v1/agents/me`)
776
+ * - the email-OTP self-registration for agents without a key yet
777
+ * (`registerAgentStart` → `registerAgentVerify`; `AgentChatClient.register`
778
+ * / `.verify` → `POST /v1/register`, `/v1/register/verify`)
779
+ * - the email-OTP recovery that re-issues a lost API key
780
+ * (`recoverAgentStart` → `recoverAgentVerify`; `AgentChatClient.recover`
781
+ * with `handle` / `.recoverVerify` → `POST /v1/agents/recover`,
782
+ * `/v1/agents/recover/verify`). The server answers recovery with the same
783
+ * `{ pending_id, message }` whether or not the email + handle match a
784
+ * live agent (no existence leak).
785
+ *
786
+ * This module holds no HTTP of its own: it turns the SDK's typed results
787
+ * and errors into result unions a setup UI can `switch` on without
788
+ * guessing at status codes. Every call is made once (`retry: never` in the
789
+ * SDK for these routes; one attempt for the key check) — setup is
790
+ * interactive, and a retry would only send a second email.
316
791
  *
317
792
  * Per-email policy (server-enforced, the numbers live in the server's
318
793
  * `agent_email_policy` row and are NOT hard-coded here): an email can back
@@ -320,9 +795,6 @@ declare class AgentChatChannelError extends Error {
320
795
  * The server quotes the number that applies in `details.limit`; every
321
796
  * user-facing string built from these results must quote that value rather
322
797
  * than assume one.
323
- *
324
- * All methods return strongly-typed result unions — setup UIs can `switch` on
325
- * the discriminant without guessing at HTTP status codes.
326
798
  */
327
799
  /** Subset of the AgentChat agent row the setup surface needs to show the user. */
328
800
  interface AgentchatAgentIdentity {
@@ -406,10 +878,14 @@ type RegisterVerifyResult = {
406
878
  /** See `RegisterStartResult.limit`. */
407
879
  readonly limit?: number;
408
880
  };
881
+ /**
882
+ * Options for the registration and recovery calls. The SDK makes these
883
+ * calls with its own transport (the runtime's `fetch`, its default timeout);
884
+ * its static `register` / `verify` / `recover` / `recoverVerify` take no
885
+ * `fetch` or timeout of their own, so neither is offered here.
886
+ */
409
887
  interface RegisterOptions {
410
888
  readonly apiBase?: string;
411
- readonly fetch?: typeof fetch;
412
- readonly timeoutMs?: number;
413
889
  }
414
890
  /**
415
891
  * Kick off an email-OTP registration. Server caches the intent under a
@@ -487,4 +963,4 @@ declare function recoverAgentVerify(input: RecoverAgentVerifyInput, opts?: Regis
487
963
  */
488
964
  declare function assertApiKeyValid(apiKey: string, opts?: ValidateApiKeyOptions): Promise<AgentchatAgentIdentity>;
489
965
 
490
- export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, type EmailPolicyReason, type ErrorClass, MCP_SERVER_NAME, OPENCLAW_TOOL_NAMER, type RecoverAgentStartInput, type RecoverAgentVerifyInput, type RecoverStartResult, type RecoverVerifyResult, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, TextsStore, type ValidateApiKeyOptions, type ValidateApiKeyResult, WakeCoalescer, assertApiKeyValid, hostedMcpServerEntry, hostedMcpSnippet, hostedMcpUrl, inviteTurnPrompt, loadIdentityLine, loadTexts, mcpToolName, probeHostedMcp, recoverAgentStart, recoverAgentVerify, registerAgentStart, registerAgentVerify, spellToolsForOpenClaw, validateApiKey, wakeTurnPrompt };
966
+ export { AGENTCHAT_CHANNEL_ID, AGENTCHAT_DEFAULT_ACCOUNT_ID, AgentChatChannelError, type AgentchatAgentIdentity, type EmailPolicyReason, type ErrorClass, type IntegrationLoop, type IntegrationLoopOptions, MAX_HUNG_TURNS, MCP_SERVER_NAME, MetricsRecorder, OPENCLAW_TOOL_NAMER, OpenClawTexts, type RecoverAgentStartInput, type RecoverAgentVerifyInput, type RecoverStartResult, type RecoverVerifyResult, type RegisterAgentStartInput, type RegisterAgentVerifyInput, type RegisterOptions, type RegisterStartResult, type RegisterVerifyResult, type ValidateApiKeyOptions, type ValidateApiKeyResult, accountTurns, assertApiKeyValid, createIntegrationLoop, createLoopTurnStarter, createTextsCache, hostedMcpServerEntry, hostedMcpSnippet, hostedMcpUrl, loadIdentityLine, mcpToolName, probeHostedMcp, recoverAgentStart, recoverAgentVerify, registerAgentStart, registerAgentVerify, spellTextsForOpenClaw, spellToolsForOpenClaw, trackerFor, turnEndOf, validateApiKey };