@agentchatme/openclaw 0.9.1 → 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/CHANGELOG.md +42 -1
- package/README.md +35 -26
- package/RUNBOOK.md +49 -17
- package/SECURITY.md +6 -2
- package/dist/binding/agents-anchor.cjs +10 -43
- package/dist/binding/agents-anchor.cjs.map +1 -1
- package/dist/binding/agents-anchor.d.cts +14 -11
- package/dist/binding/agents-anchor.d.ts +14 -11
- package/dist/binding/agents-anchor.js +10 -43
- package/dist/binding/agents-anchor.js.map +1 -1
- package/dist/index.cjs +1569 -1337
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +668 -190
- package/dist/index.d.ts +668 -190
- package/dist/index.js +1568 -1337
- package/dist/index.js.map +1 -1
- package/dist/setup-entry-C9aFZx3n.d.cts +378 -0
- package/dist/setup-entry-C9aFZx3n.d.ts +378 -0
- package/dist/setup-entry.cjs +1557 -1329
- package/dist/setup-entry.cjs.map +1 -1
- package/dist/setup-entry.d.cts +1 -1
- package/dist/setup-entry.d.ts +1 -1
- package/dist/setup-entry.js +1564 -1336
- package/dist/setup-entry.js.map +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +3 -3
- package/skills/agentchat/SKILL.md +75 -79
- package/dist/setup-entry-Dh6dRH2F.d.cts +0 -754
- package/dist/setup-entry-Dh6dRH2F.d.ts +0 -754
package/dist/index.d.cts
CHANGED
|
@@ -1,108 +1,543 @@
|
|
|
1
|
-
import { L as Logger } from './setup-entry-
|
|
2
|
-
export { A as
|
|
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 {
|
|
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
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
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
|
-
|
|
26
|
-
type
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
readonly
|
|
31
|
-
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
readonly
|
|
55
|
-
|
|
56
|
-
readonly
|
|
57
|
-
readonly
|
|
58
|
-
readonly
|
|
59
|
-
readonly
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
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
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
/**
|
|
126
|
-
readonly
|
|
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:
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
* `401` means the key does not authenticate; a transport error
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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
|
|
211
|
-
*
|
|
707
|
+
* Turns: the name OpenClaw gives the hosted tools, and the session keys and
|
|
708
|
+
* lane the turns run on.
|
|
212
709
|
*
|
|
213
|
-
* No
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
* the
|
|
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).
|
|
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,20 +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, names the conversation to open,
|
|
245
|
-
* and says the verdict is taken care of (recording it in the turn as well is
|
|
246
|
-
* idempotent).
|
|
247
|
-
*/
|
|
248
|
-
declare function wakeTurnPrompt(texts: Pick<Texts, 'wake_instruction'>, conversationId?: string): string;
|
|
249
|
-
/** The prompt a group-invite turn starts with: the served invite prompt. */
|
|
250
|
-
declare function inviteTurnPrompt(texts: Pick<Texts, 'invite_prompt'>): string;
|
|
251
739
|
|
|
252
740
|
/**
|
|
253
741
|
* Error taxonomy for the AgentChat channel plugin.
|
|
@@ -282,35 +770,24 @@ declare class AgentChatChannelError extends Error {
|
|
|
282
770
|
}
|
|
283
771
|
|
|
284
772
|
/**
|
|
285
|
-
*
|
|
286
|
-
* - verify an API key is live before finalizing setup (`validateApiKey
|
|
287
|
-
*
|
|
288
|
-
*
|
|
289
|
-
*
|
|
290
|
-
*
|
|
291
|
-
*
|
|
292
|
-
*
|
|
293
|
-
*
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
*
|
|
297
|
-
*
|
|
298
|
-
*
|
|
299
|
-
*
|
|
300
|
-
*
|
|
301
|
-
*
|
|
302
|
-
*
|
|
303
|
-
* - `POST /v1/register/verify` → 201 with `{ agent, api_key }` on success
|
|
304
|
-
* - `POST /v1/agents/recover` → 200 with `{ pending_id, message }` — always,
|
|
305
|
-
* whether or not the email + handle match
|
|
306
|
-
* a live agent (no existence leak)
|
|
307
|
-
* - `POST /v1/agents/recover/verify` → 200 with `{ handle, api_key }` on success
|
|
308
|
-
*
|
|
309
|
-
* Registration and recovery deliberately bypass the `agentchatme` SDK: the
|
|
310
|
-
* SDK's `recover(email)` predates the handle + email recovery contract and
|
|
311
|
-
* has no way to send `handle`, and the pinned SDK floor cannot move until a
|
|
312
|
-
* compatible SDK is published. Owning these four calls here keeps the plugin
|
|
313
|
-
* 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.
|
|
314
791
|
*
|
|
315
792
|
* Per-email policy (server-enforced, the numbers live in the server's
|
|
316
793
|
* `agent_email_policy` row and are NOT hard-coded here): an email can back
|
|
@@ -318,9 +795,6 @@ declare class AgentChatChannelError extends Error {
|
|
|
318
795
|
* The server quotes the number that applies in `details.limit`; every
|
|
319
796
|
* user-facing string built from these results must quote that value rather
|
|
320
797
|
* than assume one.
|
|
321
|
-
*
|
|
322
|
-
* All methods return strongly-typed result unions — setup UIs can `switch` on
|
|
323
|
-
* the discriminant without guessing at HTTP status codes.
|
|
324
798
|
*/
|
|
325
799
|
/** Subset of the AgentChat agent row the setup surface needs to show the user. */
|
|
326
800
|
interface AgentchatAgentIdentity {
|
|
@@ -404,10 +878,14 @@ type RegisterVerifyResult = {
|
|
|
404
878
|
/** See `RegisterStartResult.limit`. */
|
|
405
879
|
readonly limit?: number;
|
|
406
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
|
+
*/
|
|
407
887
|
interface RegisterOptions {
|
|
408
888
|
readonly apiBase?: string;
|
|
409
|
-
readonly fetch?: typeof fetch;
|
|
410
|
-
readonly timeoutMs?: number;
|
|
411
889
|
}
|
|
412
890
|
/**
|
|
413
891
|
* Kick off an email-OTP registration. Server caches the intent under a
|
|
@@ -485,4 +963,4 @@ declare function recoverAgentVerify(input: RecoverAgentVerifyInput, opts?: Regis
|
|
|
485
963
|
*/
|
|
486
964
|
declare function assertApiKeyValid(apiKey: string, opts?: ValidateApiKeyOptions): Promise<AgentchatAgentIdentity>;
|
|
487
965
|
|
|
488
|
-
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,
|
|
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 };
|