openclaw-lark-multi-agent 1.8.19 → 1.8.21

package/dist/openclaw-client.js

@@ -1,6 +1,6 @@
 import WebSocket from "ws";
 import { safeErrorSummary, rawErrorExcerpt } from "./provider-errors.js";
-import { inspectError, genericFailure, announceCandidate } from "./terminal-errors.js";
+import { RunTerminalError, closedStopReason, inspectError, genericFailure, announceCandidate } from "./terminal-errors.js";
 import { SessionWaitPaused, normalizeSessionRuntimeStatus, isWaitTimeout, FOREGROUND_WAIT_MS, IDLE_GUARD_MS } from "./session-status.js";
 import { createHash, randomUUID } from "crypto";
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -74,10 +74,21 @@ const EVENT_PROGRESS_BUCKET_BYTES = 256 * 1024;
 const EVENT_PROGRESS_TOTAL_BYTES = 4 * 1024 * 1024;
 const EVENT_PROGRESS_FIELD_CHARS = 2048;
 const MAX_INLINE_CONTEXT_BYTES = Number(process.env.OPENCLAW_LARK_MULTI_AGENT_MAX_INLINE_CONTEXT_BYTES || 128 * 1024);
+const reasonPriority = (r) => r === 'superseded' || r === 'restart' ? 4 : r === 'timeout' ? 3 : r === 'error' || r === 'aborted' ? 2 : closedStopReason(r) ? 1 : 0;
+const terminalReason = (...values) => values.map(closedStopReason).sort((a, b) => reasonPriority(b) - reasonPriority(a)).find(Boolean);
 /**
  * OpenClaw Gateway WebSocket client.
  * Full agent pipeline — tools, memory, skills, context management by OpenClaw.
  */
+/** Physical session key for a logical key.
+ *
+ * A key that already carries an explicit `agent:<id>:` prefix keeps it, so a
+ * client shared by several bots can serve sessions owned by different
+ * OpenClaw profiles. A key without a prefix stays on the historical `main`
+ * profile, so existing configurations behave exactly as before. */
+const withAgentPrefix = (key) => /^agent:[^:]+:/.test(key) ? key : `agent:main:${key}`;
+/** Logical (profile-free) part of a session key. */
+const withoutAgentPrefix = (key) => key.replace(/^agent:[^:]+:/, '');
 export class OpenClawClient {
     goEvidenceObservers = new Set();
     /** Raw full event observer. Observation is NOT a Feishu delivery receipt. */
@@ -151,7 +162,11 @@ export class OpenClawClient {
     isExplicitlyStoppedRun(sessionKey, runId) {
         if (!runId)
             return false;
-        if (this.recoveryStore?.isStoppedObservation(this.canonicalSessionKey(sessionKey), runId))
+        // A retired observation is NOT the same as a user-requested stop. A bare
+        // /stop in a multi-bot group retires EVERY bot's observation on the shared
+        // session; treating that retirement as "the user stopped this run"
+        // discarded answers the Gateway had already computed.
+        if (this.recoveryStore?.isExplicitlyStoppedObservation(this.canonicalSessionKey(sessionKey), runId))
             return true;
         const key = JSON.stringify([this.canonicalSessionKey(sessionKey), runId]);
         const at = this.explicitlyStoppedRuns.get(key);
@@ -225,7 +240,7 @@ export class OpenClawClient {
                     if (['error', 'timeout'].includes(snapshot.status)) {
                         // endedAt + exact run is terminal evidence; bare query timeouts never get here.
                         await callback?.(String(snapshot.error || snapshot.status), { sourceType: 'run_error', sessionKey: item.sessionKey, runId: item.runId,
-                            error: { sessionKey: item.sessionKey, runId: item.runId, source: 'chat', state: 'error', detail: String(snapshot.error || snapshot.status) } });
+                            error: { sessionKey: item.sessionKey, sessionId: item.sessionId, runId: item.runId, source: 'chat', state: 'error', stopReason: closedStopReason(snapshot.stopReason) || (snapshot.status === 'timeout' ? 'timeout' : undefined), detail: String(snapshot.error || snapshot.status) } });
                         this.recoveryStore.settleExactRunReactions(item.sessionKey, item.runId);
                         this.recoveryStore.finishRunObservation(item.sessionKey, item.runId);
                         await this.sessionSettlementCallbacks.get(this.canonicalSessionKey(item.sessionKey))?.({ sessionKey: item.sessionKey, runId: item.runId, sessionId: item.sessionId, final: true });
@@ -297,13 +312,13 @@ export class OpenClawClient {
      * payload. Keep only the fields collectReply actually consumes here. */
     projectBufferedEvent(event) {
         const data = event.data || {}, clip = (value) => typeof value === 'string' ? value.slice(0, EVENT_PROGRESS_FIELD_CHARS) : value;
-        const out = { runId: event.runId, sessionKey: event.sessionKey, stream: event.stream, seq: event.seq, data: {} };
+        const out = { runId: event.runId, sessionKey: event.sessionKey, sessionId: event.sessionId, stream: event.stream, seq: event.seq, data: {} };
         if (event.stream === 'chatFinal') {
             out.data = { text: data.gatewayYielded === true ? '' : typeof data.text === 'string' ? data.text : '', gatewayYielded: data.gatewayYielded === true };
             return out; // Entire authority, not a preview; no duplicated message body.
         }
         if (event.stream === 'chatError') {
-            out.data = { error: data.error };
+            out.data = { error: data.error, state: data.state, stopReason: closedStopReason(data.stopReason) };
             return out;
         }
         const keep = event.stream === 'lifecycle'
@@ -572,7 +587,7 @@ export class OpenClawClient {
                                 data: { text: textParts.join("\n"), gatewayYielded: frame.payload?.yielded === true },
                             });
                         }
-                        else if (state === "error") {
+                        else if (state === "error" || state === "aborted") {
                             // A chat-level error (e.g. "Request timed out before a response")
                             // must NOT be silently dropped — otherwise mid-run delta text gets
                             // surfaced as if it were a normal reply and the run neither errors
@@ -580,7 +595,8 @@ export class OpenClawClient {
                             this.bufferEvent(sk, {
                                 ...frame.payload,
                                 stream: "chatError",
-                                data: { error: frame.payload?.errorMessage || frame.payload?.error || "chat error" },
+                                data: { error: frame.payload?.errorMessage || frame.payload?.error || (state === 'aborted' ? 'aborted' : 'chat error'),
+                                    state, stopReason: terminalReason(frame.payload?.stopReason, frame.payload?.message?.stopReason) },
                             });
                         }
                     }
@@ -1166,7 +1182,7 @@ export class OpenClawClient {
         // structured content arrays rather than a plain string. Extract only visible
         // text parts and ignore thinking/tool blocks so the bridge can deliver final
         // cron results via the bot.
-        if (msg?.role === "assistant" && ["error", "aborted"].includes(msg?.stopReason)) {
+        if (msg?.role === "assistant" && ["error", "aborted", "timeout", "restart", "superseded"].includes(msg?.stopReason)) {
             if (this.mutedProactiveSessions.has(rawKey) || this.mutedProactiveSessions.has(shortKey))
                 return false;
             if (runId && this.ownedDeliveryRuns.has(runId))
@@ -1174,7 +1190,7 @@ export class OpenClawClient {
             return this.emitProactiveForSession(rawKey, String(msg.errorMessage || "Agent run failed"), {
                 sourceType: "run_error", runId,
                 error: { sessionKey: this.canonicalSessionKey(rawKey), runId: runId || "", source: "session.message",
-                    state: "final", stopReason: msg.stopReason, detail: String(msg.errorMessage || ""),
+                    state: "final", sessionId, stopReason: closedStopReason(msg.stopReason), detail: String(msg.errorMessage || ""),
                     ...(this.isExplicitlyStoppedRun(rawKey, runId) ? { userStop: true } : {}) },
             });
         }
@@ -1252,7 +1268,7 @@ export class OpenClawClient {
             // tripping the disconnect path.
             const startedConnected = this.connected;
             let chatFinalText = "";
-            let sessionKey = targetSessionKey ? `agent:main:${targetSessionKey.replace(/^agent:[^:]+:/, "")}` : "";
+            let sessionKey = targetSessionKey ? withAgentPrefix(targetSessionKey) : "";
             let shortSessionKey = targetSessionKey ? targetSessionKey.replace(/^agent:[^:]+:/, "") : "";
             let chatFinalTimer = null;
             let lifecycleEndTimer = null;
@@ -1264,6 +1280,7 @@ export class OpenClawClient {
             // root's recorded terminal state (all tools settled, no error, no async
             // pending) before anything resolves.
             let terminatingReconcileTimer = null;
+            let terminalHint;
             let pendingRuntimeFailureText = "";
             let lastActivitySummary = "";
             let lastActivityAt = 0;
@@ -1331,14 +1348,14 @@ export class OpenClawClient {
                     collectEvents();
                     if (!idleStillCurrent() || idleGeneration !== decisionGeneration)
                         return;
-                    if (observationClosed || snapshot?.runId !== runId || snapshot?.pendingError === true
+                    if (observationClosed || snapshot?.runId !== runId || options?.expectedSessionId && snapshot?.sessionId && snapshot.sessionId !== options.expectedSessionId || snapshot?.pendingError === true
                         || snapshot?.yielded === true || snapshot?.timeoutPhase === "queue" || snapshot?.timeoutPhase === "gateway_draining")
                         return;
                     // A bare wait timeout is not an execution timeout. Require a recorded
                     // terminal time; never infer failure from stopReason or replay flags.
                     const ended = snapshot.endedAt;
                     if (typeof ended !== "number" || !Number.isFinite(ended) || ended <= 0
-                        || (typeof snapshot.startedAt === "number" && ended < snapshot.startedAt))
+                        || (snapshot.startedAt !== undefined && (typeof snapshot.startedAt !== 'number' || !Number.isFinite(snapshot.startedAt) || snapshot.startedAt < 0 || ended < snapshot.startedAt)))
                         return;
                     if (snapshot.status === "ok" && snapshot.yielded !== true) {
                         const terminal = snapshot.terminalReply;
@@ -1357,8 +1374,9 @@ export class OpenClawClient {
                     else if (snapshot.status === "error" || snapshot.status === "timeout") {
                         if (observationClosed)
                             return;
-                        reject(new Error(`Agent error: ${typeof snapshot.error === "string" && snapshot.error.trim()
-                            ? snapshot.error : `Gateway 已确认运行以 ${snapshot.status} 结束`}`));
+                        reject(new RunTerminalError({ sessionKey, sessionId: options?.expectedSessionId, runId, source: 'chat', state: 'error',
+                            stopReason: closedStopReason(snapshot.stopReason) || (snapshot.status === 'timeout' ? 'timeout' : undefined),
+                            detail: typeof snapshot.error === 'string' ? snapshot.error : undefined }));
                     }
                 }
                 catch { /* Unavailable evidence means keep waiting, never abort/replay. */ }
@@ -1542,6 +1560,106 @@ export class OpenClawClient {
                     clearTimeout(terminatingReconcileTimer);
                 resolve(finalText);
             };
+            // One bounded public exact-run reconciliation for generic aborts. A
+            // closed wire cause wins over generic later prose, never another run.
+            const deferTerminal = (ev, detail) => {
+                const reason = closedStopReason(ev.data?.stopReason);
+                const p = { sessionKey, sessionId: options?.expectedSessionId || ev.sessionId, runId,
+                    source: 'chat', state: ev.data?.state === 'aborted' || reason ? 'aborted' : 'error', stopReason: reason, detail };
+                if (!terminalHint || reasonPriority(reason) > reasonPriority(terminalHint.stopReason))
+                    terminalHint = p;
+                if (genericChatErrorTimer)
+                    return;
+                const abortGeneration = idleGeneration;
+                genericChatErrorTimer = setTimeout(() => {
+                    genericChatErrorTimer = null;
+                    void (async () => {
+                        collectEvents();
+                        if (observationClosed)
+                            return;
+                        if (!terminalHint?.stopReason && idleGeneration !== abortGeneration) {
+                            terminalHint = undefined;
+                            return;
+                        }
+                        if (chatFinalText.trim()) {
+                            finish(chatFinalText);
+                            return;
+                        }
+                        let candidate = terminalHint;
+                        if (!candidate.stopReason) {
+                            try {
+                                const snapshot = await this.rpc('agent.wait', { runId, timeoutMs: 1 }, 2000);
+                                collectEvents();
+                                if (observationClosed)
+                                    return;
+                                if (options?.expectedSessionId && snapshot?.sessionId && snapshot.sessionId !== options.expectedSessionId)
+                                    return;
+                                if (chatFinalText.trim()) {
+                                    finish(chatFinalText);
+                                    return;
+                                }
+                                // The query sampled the provisional abort's old liveness cut.
+                                // Drain first, then fence even a recorded terminal snapshot if
+                                // verified same-run progress advanced while this read awaited.
+                                if (!terminalHint?.stopReason && idleGeneration !== abortGeneration) {
+                                    terminalHint = undefined;
+                                    return;
+                                }
+                                if (terminalHint?.stopReason)
+                                    candidate = terminalHint;
+                                else if (snapshot?.runId === runId && !snapshot.pendingError && !snapshot.yielded &&
+                                    !['queue', 'gateway_draining'].includes(snapshot.timeoutPhase) && Number.isFinite(snapshot.endedAt) && snapshot.endedAt > 0 &&
+                                    (snapshot.startedAt === undefined || typeof snapshot.startedAt === 'number' && Number.isFinite(snapshot.startedAt) && snapshot.startedAt >= 0 && snapshot.endedAt >= snapshot.startedAt)) {
+                                    if (snapshot.status === 'ok' && snapshot.terminalReply?.disposition === 'visible' && typeof snapshot.terminalReply.text === 'string') {
+                                        finish(snapshot.terminalReply.text);
+                                        return;
+                                    }
+                                    if (snapshot.status === 'ok' && ['silent', 'empty'].includes(snapshot.terminalReply?.disposition)) {
+                                        finish('NO_REPLY');
+                                        return;
+                                    }
+                                    if (!['error', 'timeout'].includes(snapshot.status))
+                                        return;
+                                    candidate = { ...candidate, state: 'error', stopReason: closedStopReason(snapshot.stopReason) || (snapshot.status === 'timeout' ? 'timeout' : undefined),
+                                        detail: typeof snapshot.error === 'string' ? snapshot.error : candidate.detail };
+                                }
+                                else {
+                                    if (snapshot?.pendingError || snapshot?.yielded || ['queue', 'gateway_draining'].includes(snapshot?.timeoutPhase)) {
+                                        terminalHint = undefined;
+                                        return;
+                                    }
+                                    // A wait-only timeout adds NO terminal cause. The actual
+                                    // abort/error envelope can still be reported as unknown.
+                                    candidate = { ...candidate, state: 'error', stopReason: undefined };
+                                }
+                            }
+                            catch { /* No cause proof: preserve the generic, unclassified diagnostic. */ }
+                        }
+                        // A rejected lookup crosses the same await boundary. It cannot
+                        // revive a stale generic hint either; new wire final/closed metadata
+                        // and explicit-stop receipts still outrank that provisional cut.
+                        collectEvents();
+                        if (observationClosed)
+                            return;
+                        if (chatFinalText.trim()) {
+                            finish(chatFinalText);
+                            return;
+                        }
+                        if (!terminalHint?.stopReason && idleGeneration !== abortGeneration) {
+                            terminalHint = undefined;
+                            return;
+                        }
+                        if (terminalHint?.stopReason && reasonPriority(terminalHint.stopReason) > reasonPriority(candidate.stopReason))
+                            candidate = terminalHint;
+                        if (this.isExplicitlyStoppedRun(sessionKey, runId)) {
+                            finish('NO_REPLY');
+                            return;
+                        }
+                        reject(new RunTerminalError(candidate));
+                    })().catch(error => { if (!observationClosed)
+                        reject(error); });
+                }, 350);
+            };
             const collectEvents = () => {
                 if (observationClosed)
                     return;
@@ -1577,7 +1695,7 @@ export class OpenClawClient {
                         // Non-destructive per-observer cursor: ACK and a replacement final
                         // may be delivered synchronously before the awaiting sender resumes.
                         // Leave every foreign/unidentified frame available to its own owner.
-                        if (!matchesRun || sessionKey && !eventSessionMatches)
+                        if (!matchesRun || sessionKey && !eventSessionMatches || options?.expectedSessionId && ev.sessionId && ev.sessionId !== options.expectedSessionId)
                             continue;
                         seenEvents.add(ev);
                         if (!sessionKey && ev.sessionKey) {
@@ -1720,6 +1838,10 @@ export class OpenClawClient {
                         }
                         if (ev.stream === "lifecycle" && ev.data?.phase === "error") {
                             const errText = String(ev.data?.error || "unknown");
+                            if (closedStopReason(ev.data?.stopReason) && ev.data.stopReason !== 'error' || /^(?:agent run )?aborted$/i.test(errText.trim()) || terminalHint) {
+                                deferTerminal(ev, errText);
+                                continue;
+                            }
                             // Some agent errors are recoverable: OpenClaw emits a lifecycle
                             // error (e.g. "Context overflow: prompt too large") and then
                             // auto-compacts and KEEPS RUNNING the same run, eventually emitting
@@ -1761,6 +1883,10 @@ export class OpenClawClient {
                             // surfaces the failure / lets auto-retry kick in — instead of
                             // surfacing whatever mid-run delta text happened to be collected.
                             const errText = String(ev.data?.error || "chat error");
+                            if (ev.data?.state === 'aborted' || closedStopReason(ev.data?.stopReason) && ev.data.stopReason !== 'error' || /^(?:agent run )?aborted$/i.test(errText.trim()) || terminalHint) {
+                                deferTerminal(ev, errText);
+                                continue;
+                            }
                             if (this.isGenericChatError(errText)) {
                                 // Gateway can emit a terminal chat error without errorMessage,
                                 // then persist a richer terminal snapshot a moment later. Do
@@ -1770,8 +1896,12 @@ export class OpenClawClient {
                                 if (!genericChatErrorTimer) {
                                     genericChatErrorTimer = setTimeout(() => {
                                         genericChatErrorTimer = null;
+                                        if (terminalHint) {
+                                            deferTerminal({ data: terminalHint }, terminalHint.detail || 'aborted');
+                                            return;
+                                        }
                                         const decisionGeneration = idleGeneration;
-                                        void this.resolveTerminalChatError(evRunId || runId, targetSessionKey || sessionKey).then((detail) => {
+                                        void this.resolveTerminalChatError(evRunId || runId, targetSessionKey || sessionKey, options?.expectedSessionId).then((detail) => {
                                             collectEvents();
                                             if (observationClosed || idleGeneration !== decisionGeneration)
                                                 return;
@@ -1779,14 +1909,24 @@ export class OpenClawClient {
                                                 finish(chatFinalText);
                                                 return;
                                             }
+                                            if (terminalHint) {
+                                                deferTerminal({ data: terminalHint }, terminalHint.detail || 'aborted');
+                                                return;
+                                            }
                                             clearTimeout(idleTimer);
                                             clearInterval(poller);
                                             if (chatFinalTimer)
                                                 clearTimeout(chatFinalTimer);
                                             if (lifecycleEndTimer)
                                                 clearTimeout(lifecycleEndTimer);
-                                            reject(new Error(`Agent error: ${detail}`));
-                                        }, error => { void handleTimeoutResult(error, () => idleGeneration === decisionGeneration); });
+                                            reject(detail);
+                                        }, error => {
+                                            if (terminalHint) {
+                                                deferTerminal({ data: terminalHint }, terminalHint.detail || 'aborted');
+                                                return;
+                                            }
+                                            void handleTimeoutResult(error, () => idleGeneration === decisionGeneration);
+                                        });
                                     }, 350);
                                 }
                                 continue;
@@ -1922,15 +2062,17 @@ export class OpenClawClient {
         const t = (errText || "").trim().toLowerCase();
         return t === "chat error" || t === "agent error: chat error";
     }
-    async resolveTerminalChatError(runId, sessionKey) {
+    async resolveTerminalChatError(runId, sessionKey, expectedSessionId) {
         try {
             const snapshot = await this.rpc("agent.wait", { runId, timeoutMs: 1500 }, 2500);
-            if (snapshot?.runId !== runId || !Number.isFinite(snapshot.endedAt) || snapshot.endedAt <= 0 || snapshot.yielded || snapshot.pendingError
-                || ['queue', 'gateway_draining'].includes(snapshot.timeoutPhase) || typeof snapshot.startedAt === 'number' && snapshot.endedAt < snapshot.startedAt
+            if (snapshot?.runId !== runId || expectedSessionId && snapshot?.sessionId && snapshot.sessionId !== expectedSessionId || !Number.isFinite(snapshot.endedAt) || snapshot.endedAt <= 0 || snapshot.yielded || snapshot.pendingError
+                || ['queue', 'gateway_draining'].includes(snapshot.timeoutPhase) || snapshot.startedAt !== undefined &&
+                (typeof snapshot.startedAt !== 'number' || !Number.isFinite(snapshot.startedAt) || snapshot.startedAt < 0 || snapshot.endedAt < snapshot.startedAt)
                 || !['error', 'timeout'].includes(snapshot.status)) {
                 throw new SessionWaitPaused(await this.getSessionRuntimeStatus(sessionKey || ''), true);
             }
-            return this.formatTerminalRunError(snapshot);
+            return new RunTerminalError({ sessionKey: this.canonicalSessionKey(sessionKey || ''), sessionId: expectedSessionId || snapshot.sessionId, runId, source: 'chat', state: 'error',
+                stopReason: closedStopReason(snapshot.stopReason) || (snapshot.status === 'timeout' ? 'timeout' : undefined), detail: typeof snapshot.error === 'string' ? snapshot.error : undefined });
         }
         catch (err) {
             if (err instanceof SessionWaitPaused)
@@ -1939,36 +2081,6 @@ export class OpenClawClient {
             throw new SessionWaitPaused(normalizeSessionRuntimeStatus(undefined), true);
         }
     }
-    formatTerminalRunError(snapshot) {
-        const rawError = typeof snapshot?.error === "string" ? snapshot.error.trim() : "";
-        const timeoutPhase = typeof snapshot?.timeoutPhase === "string" ? snapshot.timeoutPhase.trim() : "";
-        const stopReason = typeof snapshot?.stopReason === "string" ? snapshot.stopReason.trim() : "";
-        const status = typeof snapshot?.status === "string" ? snapshot.status.trim() : "";
-        const timedOut = status === "timeout" || Boolean(timeoutPhase) || /timed?\s*out|timeout/i.test(rawError);
-        if (timedOut) {
-            const startedAt = Number(snapshot?.startedAt);
-            const endedAt = Number(snapshot?.endedAt);
-            const elapsedSeconds = Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt > startedAt
-                ? Math.round((endedAt - startedAt) / 1000)
-                : 0;
-            const elapsed = elapsedSeconds > 0 ? `（运行约 ${this.formatDurationSeconds(elapsedSeconds)}）` : "";
-            const phase = timeoutPhase ? `，阶段：${timeoutPhase}` : "";
-            return `等待 Agent 运行结果超时${elapsed}${phase}；底层运行可能仍在继续${rawError ? `；${rawError}` : ""}`;
-        }
-        if (rawError)
-            return rawError;
-        if (stopReason === "stop" || stopReason === "rpc")
-            return `Agent 被停止（${stopReason}）`;
-        const meta = [status && `状态=${status}`, stopReason && `原因=${stopReason}`, timeoutPhase && `阶段=${timeoutPhase}`].filter(Boolean).join("，");
-        return meta ? `OpenClaw 运行失败：${meta}` : "OpenClaw 运行失败，但未返回具体原因";
-    }
-    formatDurationSeconds(seconds) {
-        if (seconds % 3600 === 0)
-            return `${seconds / 3600} 小时`;
-        if (seconds % 60 === 0)
-            return `${seconds / 60} 分钟`;
-        return `${seconds} 秒`;
-    }
     isRecoverableAgentError(errText) {
         const t = (errText || "").toLowerCase();
         return t.includes("context overflow")
@@ -2128,7 +2240,7 @@ export class OpenClawClient {
         return sessionKey.replace(/^agent:[^:]+:/, "");
     }
     canonicalSessionKey(sessionKey) {
-        return /^agent:[^:]+:/.test(sessionKey) ? sessionKey : `agent:main:${sessionKey}`;
+        return withAgentPrefix(sessionKey);
     }
     registerPendingSteer(sessionKey, text, displayText) {
         const key = this.shortKey(sessionKey);
@@ -2434,7 +2546,7 @@ export class OpenClawClient {
             const message = firstErr.message || String(firstErr);
             if (!/session (?:not found|unknown)|unknown session|invalid session key/i.test(message))
                 throw firstErr;
-            const fullKey = sessionKey.startsWith("agent:") ? sessionKey : `agent:main:${sessionKey}`;
+            const fullKey = withAgentPrefix(sessionKey);
             held?.guard();
             await this.patchSession({ key: fullKey, model: expectedModel, ...(held ? { expectedSessionId: held.sessionId } : {}) });
         }
@@ -2644,7 +2756,7 @@ export class OpenClawClient {
                 for (const stopped of result.runIds)
                     if (typeof stopped === "string" && stopped) {
                         this.explicitlyStoppedRuns.set(JSON.stringify([key, stopped]), Date.now());
-                        this.recoveryStore?.stopExactRun(key, stopped);
+                        this.recoveryStore?.stopExactRun(key, stopped, true);
                     }
             }
             return result;
@@ -2672,17 +2784,16 @@ export class OpenClawClient {
         }
         if (runId && this.isExplicitlyStoppedRun(sessionKey, runId) && state === 'final')
             return;
-        const stopReason = [payload?.stopReason, payload?.message?.stopReason].find(reason => reason === "error" || reason === "aborted")
-            || payload?.stopReason || payload?.message?.stopReason;
-        const isError = state === "error" || state === "aborted" || stopReason === "error" || stopReason === "aborted";
+        const stopReason = terminalReason(payload?.stopReason, payload?.message?.stopReason);
+        const isError = state === "error" || state === "aborted" || ['error', 'aborted', 'timeout', 'restart', 'superseded'].includes(stopReason || '');
         if (isError) {
             const detail = String(payload?.errorMessage || payload?.message?.errorMessage || payload?.error || payload?.reason || "").trim();
             const aborted = state === "aborted" || stopReason === "aborted";
             const text = `⚠️ Agent run ${aborted ? "was aborted" : "failed"}${detail ? `: ${detail}` : ""}`;
             this.emitProactiveForSession(sessionKey, text, {
                 sourceType: "run_error", runId,
-                error: { sessionKey: this.canonicalSessionKey(sessionKey), runId, source: "chat", state: state || "final",
-                    ...(typeof stopReason === "string" ? { stopReason } : {}), detail,
+                error: { sessionKey: this.canonicalSessionKey(sessionKey), runId, source: "chat", state: state || "final", sessionId: typeof payload?.sessionId === 'string' ? payload.sessionId : undefined,
+                    ...(closedStopReason(stopReason) ? { stopReason: closedStopReason(stopReason) } : {}), detail,
                     ...(this.isExplicitlyStoppedRun(sessionKey, runId) ? { userStop: true } : {}) },
             });
             this.releaseSuppressedSessionKeysAfter(keys, 0);
@@ -2880,8 +2991,8 @@ export class OpenClawClient {
         }
     }
     muteProactiveDelivery(sessionKey) {
-        const shortKey = sessionKey.startsWith("agent:main:") ? sessionKey.slice("agent:main:".length) : sessionKey;
-        const fullKey = `agent:main:${shortKey}`;
+        const shortKey = withoutAgentPrefix(sessionKey);
+        const fullKey = withAgentPrefix(sessionKey);
         const keys = [shortKey, fullKey];
         for (const key of keys)
             this.addMutedProactiveKey(key);
@@ -3544,7 +3655,7 @@ export class OpenClawClient {
         if (onSettled)
             this.sessionSettlementCallbacks.set(this.canonicalSessionKey(sessionKey), onSettled);
         this.sessionMessageCallbacks.set(sessionKey, onMessage);
-        this.sessionMessageCallbacks.set(`agent:main:${sessionKey}`, onMessage);
+        this.sessionMessageCallbacks.set(withAgentPrefix(sessionKey), onMessage);
         this.subscribedKeys.add(sessionKey);
         try {
             await this.rpc("sessions.messages.subscribe", { key: this.canonicalSessionKey(sessionKey) });
@@ -3554,7 +3665,7 @@ export class OpenClawClient {
         }
     }
     setVerboseTranscriptDelivery(sessionKey, enabled) {
-        const keys = [sessionKey, `agent:main:${sessionKey}`];
+        const keys = [sessionKey, withAgentPrefix(sessionKey)];
         for (const key of keys) {
             if (enabled)
                 this.verboseTranscriptSessions.add(key);
@@ -3567,9 +3678,9 @@ export class OpenClawClient {
     async unsubscribeSession(sessionKey) {
         this.sessionSettlementCallbacks.delete(this.canonicalSessionKey(sessionKey));
         this.sessionMessageCallbacks.delete(sessionKey);
-        this.sessionMessageCallbacks.delete(`agent:main:${sessionKey}`);
+        this.sessionMessageCallbacks.delete(withAgentPrefix(sessionKey));
         this.toolEventCallbacks.delete(sessionKey);
-        this.toolEventCallbacks.delete(`agent:main:${sessionKey}`);
+        this.toolEventCallbacks.delete(withAgentPrefix(sessionKey));
         this.setVerboseTranscriptDelivery(sessionKey, false);
         this.subscribedKeys.delete(sessionKey);
         try {
@@ -3584,6 +3695,6 @@ export class OpenClawClient {
      */
     onToolEvent(sessionKey, callback) {
         this.toolEventCallbacks.set(sessionKey, callback);
-        this.toolEventCallbacks.set(`agent:main:${sessionKey}`, callback);
+        this.toolEventCallbacks.set(withAgentPrefix(sessionKey), callback);
     }
 }

package/dist/queued-presentation.d.ts

@@ -37,8 +37,12 @@ export declare class QueuedPresentations {
     private flushRepairs;
     private usable;
     private current;
+    private inputContext;
     private hydrate;
-    receive(chat: string, rowId: number, messageId: string, native?: boolean, activeRunId?: string): LiveStatusController | undefined;
+    receive(chat: string, rowId: number, messageId: string, native?: boolean, activeRunId?: string, displayText?: string | {
+        source: 'visible';
+        text: string;
+    }): LiveStatusController | undefined;
     claim(chat: string, ids: number[], ownerId: string, batchId: string, native?: boolean): LiveStatusController | undefined;
     attempted(live: LiveStatusController | undefined, submissionId: string, ownerId: string, batchId: string): void;
     insertionAccepted(chat: string, rowId: number, expectedRunId: string): Promise<void>;
@@ -53,6 +57,9 @@ export declare class QueuedPresentations {
     advance(live: LiveStatusController | undefined, previousRunId: string | undefined, runId: string, ownerId: string, batchId: string): Promise<void>;
     forTarget(chat: string, runId: string, live?: LiveStatusController): LiveStatusController | undefined;
     forRun(chat: string, runId: string): LiveStatusController | undefined;
+    /** Recall invalidates copied UI previews, including frozen/terminal cards.
+     * It never changes input custody or recreates/retargets an uncertain effect. */
+    refreshRecalledInput(chat: string, rowId: number, messageId: string): Promise<void>;
     retire(chat: string): void;
     dispose(): void;
 }