@alfe.ai/openclaw-chat 0.9.4 → 0.9.6

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-import { C as ChatMessage, S as AlfeResolvedAccount, T as SessionSummary, b as AlfeChannelConfig, h as plugin, w as SessionData, x as AlfePluginConfig, y as createAlfeChannelPlugin } from "./plugin.cjs";
+import { C as AlfeResolvedAccount, E as SessionSummary, S as AlfePluginConfig, T as SessionData, b as createAlfeChannelPlugin, g as plugin, w as ChatMessage, x as AlfeChannelConfig } from "./plugin.cjs";
 export { type AlfeChannelConfig, type AlfePluginConfig, type AlfeResolvedAccount, type ChatMessage, type SessionData, type SessionSummary, createAlfeChannelPlugin, plugin as default };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { C as ChatMessage, S as AlfeResolvedAccount, T as SessionSummary, b as AlfeChannelConfig, h as plugin, w as SessionData, x as AlfePluginConfig, y as createAlfeChannelPlugin } from "./plugin.js";
+import { C as AlfeResolvedAccount, E as SessionSummary, S as AlfePluginConfig, T as SessionData, b as createAlfeChannelPlugin, g as plugin, w as ChatMessage, x as AlfeChannelConfig } from "./plugin.js";
 export { type AlfeChannelConfig, type AlfePluginConfig, type AlfeResolvedAccount, type ChatMessage, type SessionData, type SessionSummary, createAlfeChannelPlugin, plugin as default };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { f as plugin, g as createAlfeChannelPlugin } from "./plugin2.js";
+import { _ as createAlfeChannelPlugin, p as plugin } from "./plugin2.js";
 export { createAlfeChannelPlugin, plugin as default };

package/dist/plugin.cjs

@@ -13,6 +13,7 @@ exports.buildA2ACompletePayload = require_plugin.buildA2ACompletePayload;
 exports.buildOriginEnvelopeContext = require_plugin.buildOriginEnvelopeContext;
 exports.buildToolActivity = require_plugin.buildToolActivity;
 exports.computeOpenClawSdkAnchors = require_plugin.computeOpenClawSdkAnchors;
+exports.decideChatServiceStart = require_plugin.decideChatServiceStart;
 exports.default = require_plugin.plugin;
 exports.joinAssistantText = require_plugin.joinAssistantText;
 exports.resolveAbortTargetKeys = require_plugin.resolveAbortTargetKeys;

package/dist/plugin.d.cts

@@ -64,6 +64,20 @@ type StoredMessageComponent = {
   label: string;
   value: string;
 };
+/**
+ * Persisted reference to a message attachment. Deliberately stores NO URL —
+ * the download URL is short-lived and re-signed on demand through the chat
+ * service's participant-gated resolve endpoint (keyed by `attachmentId`). Only
+ * media bound to the conversation (a real chat-bucket upload) is persisted;
+ * remote-passthrough media has no `attachmentId` and is not stored.
+ */
+interface StoredAttachment {
+  attachmentId: string;
+  type: 'image' | 'video' | 'audio' | 'document' | 'file';
+  mimeType: string;
+  filename: string;
+  size?: number;
+}
 interface ChatMessage {
   role: 'user' | 'assistant';
   content: string;
@@ -77,6 +91,12 @@ interface ChatMessage {
    * content). Persisted so a refresh / reconnect replays the button.
    */
   components?: StoredMessageComponent[];
+  /**
+   * Attachment references (images/files). Additive — absent on pre-attachment
+   * files. Persisted so history replays them; the client resolves each URL on
+   * demand via the participant-gated endpoint. See {@link StoredAttachment}.
+   */
+  attachments?: StoredAttachment[];
 }
 /**
  * Persisted form of a turn's agent activity (tool cards + thinking), so a
@@ -579,6 +599,15 @@ interface AnchorEnv {
   requireMainFilename: string | undefined;
   argv1: string | undefined;
   execPath: string;
+  /**
+   * Well-known global `node_modules` directories to try as `<dir>/openclaw`
+   * anchors, independent of PATH / `which` / execPath. Load-bearing when the
+   * plugin runs in-process inside a runtime whose PATH is stripped or whose
+   * `child_process` is sandboxed (homebrew-keg self-hosted macOS), so every
+   * environment-derived anchor above returns nothing. Optional — defaults to
+   * none (tests that don't exercise this pass `undefined`).
+   */
+  globalModulesDirs?: string[];
 }
 /**
  * Compute the ordered, de-duplicated list of resolver anchors to try, each
@@ -600,6 +629,32 @@ interface AnchorEnv {
  * Pure except for the injected `realpath` / `which` seams — unit-tested.
  */
 declare function computeOpenClawSdkAnchors(deps: AnchorEnv): string[];
+/**
+ * Decide what `startChatService()` should do given the current connection
+ * state. Pure so the branch logic — the load-bearing fix for the
+ * health-monitor no-op restart loop (Badi Junior, 2026-07-09) — is unit
+ * testable without standing up a real WebSocket or the OpenClaw SDK.
+ *
+ * OpenClaw calls the registered service's `start()` in two very different
+ * situations that a sticky activation flag could not tell apart:
+ *  - a redundant duplicate (re-`activate()` per tool-discovery pass / reconnect)
+ *    → must be a no-op ('skip'), and
+ *  - a channel health-monitor REVIVE of a channel it decided is "stopped"
+ *    (`health-monitor: [alfe:default] restarting (reason: stopped)`), sometimes
+ *    with no preceding `stop()` → must actually reconnect.
+ *
+ * Keying on the live client fixes it:
+ *  - a connect in flight, or an already-connected client → 'skip'
+ *  - a client that exists but is not connected → 'recycle' it then reconnect
+ *  - no client at all → 'connect'
+ *
+ * Exported for unit tests.
+ */
+declare function decideChatServiceStart(state: {
+  connectInFlight: boolean;
+  clientPresent: boolean;
+  clientConnected: boolean;
+}): 'skip' | 'recycle' | 'connect';
 declare function enqueueAgentTurn(task: () => Promise<void>, opts?: {
   coalesceKey?: string;
   onSuperseded?: () => void;
@@ -681,4 +736,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { ChatMessage as C, AlfeResolvedAccount as S, SessionSummary as T, rewriteAssistantText as _, VOICE_REPLY_SYSTEM_PROMPT as a, AlfeChannelConfig as b, __setActiveRunForTest as c, buildOriginEnvelopeContext as d, buildToolActivity as f, resolveAbortTargetKeys as g, plugin as h, RunEventGate as i, admitAgentEvent as l, joinAssistantText as m, AnchorEnv as n, __agentTurnQueueForTest as o, computeOpenClawSdkAnchors as p, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as r, __resetAgentTurnQueueForTest as s, ActiveRunRef as t, buildA2ACompletePayload as u, stripLeakedToolSummary as v, SessionData as w, AlfePluginConfig as x, createAlfeChannelPlugin as y };
+export { AlfeResolvedAccount as C, SessionSummary as E, AlfePluginConfig as S, SessionData as T, resolveAbortTargetKeys as _, VOICE_REPLY_SYSTEM_PROMPT as a, createAlfeChannelPlugin as b, __setActiveRunForTest as c, buildOriginEnvelopeContext as d, buildToolActivity as f, plugin as g, joinAssistantText as h, RunEventGate as i, admitAgentEvent as l, decideChatServiceStart as m, AnchorEnv as n, __agentTurnQueueForTest as o, computeOpenClawSdkAnchors as p, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as r, __resetAgentTurnQueueForTest as s, ActiveRunRef as t, buildA2ACompletePayload as u, rewriteAssistantText as v, ChatMessage as w, AlfeChannelConfig as x, stripLeakedToolSummary as y };

package/dist/plugin.d.ts

@@ -64,6 +64,20 @@ type StoredMessageComponent = {
   label: string;
   value: string;
 };
+/**
+ * Persisted reference to a message attachment. Deliberately stores NO URL —
+ * the download URL is short-lived and re-signed on demand through the chat
+ * service's participant-gated resolve endpoint (keyed by `attachmentId`). Only
+ * media bound to the conversation (a real chat-bucket upload) is persisted;
+ * remote-passthrough media has no `attachmentId` and is not stored.
+ */
+interface StoredAttachment {
+  attachmentId: string;
+  type: 'image' | 'video' | 'audio' | 'document' | 'file';
+  mimeType: string;
+  filename: string;
+  size?: number;
+}
 interface ChatMessage {
   role: 'user' | 'assistant';
   content: string;
@@ -77,6 +91,12 @@ interface ChatMessage {
    * content). Persisted so a refresh / reconnect replays the button.
    */
   components?: StoredMessageComponent[];
+  /**
+   * Attachment references (images/files). Additive — absent on pre-attachment
+   * files. Persisted so history replays them; the client resolves each URL on
+   * demand via the participant-gated endpoint. See {@link StoredAttachment}.
+   */
+  attachments?: StoredAttachment[];
 }
 /**
  * Persisted form of a turn's agent activity (tool cards + thinking), so a
@@ -579,6 +599,15 @@ interface AnchorEnv {
   requireMainFilename: string | undefined;
   argv1: string | undefined;
   execPath: string;
+  /**
+   * Well-known global `node_modules` directories to try as `<dir>/openclaw`
+   * anchors, independent of PATH / `which` / execPath. Load-bearing when the
+   * plugin runs in-process inside a runtime whose PATH is stripped or whose
+   * `child_process` is sandboxed (homebrew-keg self-hosted macOS), so every
+   * environment-derived anchor above returns nothing. Optional — defaults to
+   * none (tests that don't exercise this pass `undefined`).
+   */
+  globalModulesDirs?: string[];
 }
 /**
  * Compute the ordered, de-duplicated list of resolver anchors to try, each
@@ -600,6 +629,32 @@ interface AnchorEnv {
  * Pure except for the injected `realpath` / `which` seams — unit-tested.
  */
 declare function computeOpenClawSdkAnchors(deps: AnchorEnv): string[];
+/**
+ * Decide what `startChatService()` should do given the current connection
+ * state. Pure so the branch logic — the load-bearing fix for the
+ * health-monitor no-op restart loop (Badi Junior, 2026-07-09) — is unit
+ * testable without standing up a real WebSocket or the OpenClaw SDK.
+ *
+ * OpenClaw calls the registered service's `start()` in two very different
+ * situations that a sticky activation flag could not tell apart:
+ *  - a redundant duplicate (re-`activate()` per tool-discovery pass / reconnect)
+ *    → must be a no-op ('skip'), and
+ *  - a channel health-monitor REVIVE of a channel it decided is "stopped"
+ *    (`health-monitor: [alfe:default] restarting (reason: stopped)`), sometimes
+ *    with no preceding `stop()` → must actually reconnect.
+ *
+ * Keying on the live client fixes it:
+ *  - a connect in flight, or an already-connected client → 'skip'
+ *  - a client that exists but is not connected → 'recycle' it then reconnect
+ *  - no client at all → 'connect'
+ *
+ * Exported for unit tests.
+ */
+declare function decideChatServiceStart(state: {
+  connectInFlight: boolean;
+  clientPresent: boolean;
+  clientConnected: boolean;
+}): 'skip' | 'recycle' | 'connect';
 declare function enqueueAgentTurn(task: () => Promise<void>, opts?: {
   coalesceKey?: string;
   onSuperseded?: () => void;
@@ -681,4 +736,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { ChatMessage as C, AlfeResolvedAccount as S, SessionSummary as T, rewriteAssistantText as _, VOICE_REPLY_SYSTEM_PROMPT as a, AlfeChannelConfig as b, __setActiveRunForTest as c, buildOriginEnvelopeContext as d, buildToolActivity as f, resolveAbortTargetKeys as g, plugin as h, RunEventGate as i, admitAgentEvent as l, joinAssistantText as m, AnchorEnv as n, __agentTurnQueueForTest as o, computeOpenClawSdkAnchors as p, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as r, __resetAgentTurnQueueForTest as s, ActiveRunRef as t, buildA2ACompletePayload as u, stripLeakedToolSummary as v, SessionData as w, AlfePluginConfig as x, createAlfeChannelPlugin as y };
+export { AlfeResolvedAccount as C, SessionSummary as E, AlfePluginConfig as S, SessionData as T, resolveAbortTargetKeys as _, VOICE_REPLY_SYSTEM_PROMPT as a, createAlfeChannelPlugin as b, __setActiveRunForTest as c, buildOriginEnvelopeContext as d, buildToolActivity as f, plugin as g, joinAssistantText as h, RunEventGate as i, admitAgentEvent as l, decideChatServiceStart as m, AnchorEnv as n, __agentTurnQueueForTest as o, computeOpenClawSdkAnchors as p, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as r, __resetAgentTurnQueueForTest as s, ActiveRunRef as t, buildA2ACompletePayload as u, rewriteAssistantText as v, ChatMessage as w, AlfeChannelConfig as x, stripLeakedToolSummary as y };

package/dist/plugin.js

@@ -1,2 +1,2 @@
-import { a as __setActiveRunForTest, c as buildOriginEnvelopeContext, d as joinAssistantText, f as plugin, h as stripLeakedToolSummary, i as __resetAgentTurnQueueForTest, l as buildToolActivity, m as rewriteAssistantText, n as VOICE_REPLY_SYSTEM_PROMPT, o as admitAgentEvent, p as resolveAbortTargetKeys, r as __agentTurnQueueForTest, s as buildA2ACompletePayload, t as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, u as computeOpenClawSdkAnchors } from "./plugin2.js";
-export { CROSS_AGENT_TOOLS_SYSTEM_PROMPT, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+import { a as __setActiveRunForTest, c as buildOriginEnvelopeContext, d as decideChatServiceStart, f as joinAssistantText, g as stripLeakedToolSummary, h as rewriteAssistantText, i as __resetAgentTurnQueueForTest, l as buildToolActivity, m as resolveAbortTargetKeys, n as VOICE_REPLY_SYSTEM_PROMPT, o as admitAgentEvent, p as plugin, r as __agentTurnQueueForTest, s as buildA2ACompletePayload, t as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, u as computeOpenClawSdkAnchors } from "./plugin2.js";
+export { CROSS_AGENT_TOOLS_SYSTEM_PROMPT, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };

package/dist/plugin2.cjs

@@ -3,6 +3,7 @@ let node_fs_promises = require("node:fs/promises");
 let node_fs = require("node:fs");
 let node_child_process = require("node:child_process");
 let node_path = require("node:path");
+let node_url = require("node:url");
 let node_os = require("node:os");
 let _alfe_ai_chat = require("@alfe.ai/chat");
 let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
@@ -210,7 +211,8 @@ async function uploadLocalFile(localPath, log, deps) {
 			url: presigned.downloadUrl,
 			filename,
 			mimeType,
-			size
+			size,
+			attachmentId: presigned.id
 		};
 	} catch (err) {
 		log.warn(`Outbound media upload failed for ${filename}: ${err instanceof Error ? err.message : String(err)}`);
@@ -874,7 +876,7 @@ async function createSession(sessionId, agentId, channel, tenantId, userId) {
 	return session;
 }
 const writeLocks = /* @__PURE__ */ new Map();
-async function addMessage(sessionId, role, content, senderId, senderName, components) {
+async function addMessage(sessionId, role, content, senderId, senderName, components, attachments) {
 	const next = (writeLocks.get(sessionId) ?? Promise.resolve()).then(async () => {
 		const session = await getSession(sessionId);
 		if (!session) return;
@@ -884,7 +886,8 @@ async function addMessage(sessionId, role, content, senderId, senderName, compon
 			timestamp: Date.now(),
 			...senderId ? { senderId } : {},
 			...senderName ? { senderName } : {},
-			...components?.length ? { components } : {}
+			...components?.length ? { components } : {},
+			...attachments?.length ? { attachments } : {}
 		});
 		await saveSession(session);
 	}).finally(() => {
@@ -2070,24 +2073,33 @@ let resolveRouteEnvelope = null;
 * degrades `chat.abort` to a logged no-op (Stop still seals the UI) rather than
 * a hard failure.
 */
-function loadOpenClawSdk(req, log, anchor) {
-	let resolvedDispatch = false;
-	try {
-		const channelInbound = req("openclaw/plugin-sdk/channel-inbound");
-		if (channelInbound.dispatchInboundDirectDmWithRuntime) {
-			dispatchInbound = channelInbound.dispatchInboundDirectDmWithRuntime;
-			resolvedDispatch = true;
+async function loadOpenClawSdk(req, log, anchor) {
+	const loadSubpath = async (subpath) => {
+		try {
+			const mod = await import((0, node_url.pathToFileURL)(req.resolve(subpath)).href);
+			return {
+				...typeof mod.default === "object" ? mod.default : void 0,
+				...mod
+			};
+		} catch {}
+		try {
+			return req(subpath);
+		} catch {
+			return;
 		}
-	} catch {}
-	try {
-		const harness = req("openclaw/plugin-sdk/agent-harness");
-		if (harness.abortEmbeddedAgentRun) abortEmbeddedAgentRun = harness.abortEmbeddedAgentRun;
-		if (harness.resolveActiveEmbeddedRunSessionId) resolveActiveRunSessionId = harness.resolveActiveEmbeddedRunSessionId;
-	} catch {}
-	try {
-		const envelope = req("openclaw/plugin-sdk/inbound-envelope");
-		if (envelope.resolveInboundRouteEnvelopeBuilderWithRuntime) resolveRouteEnvelope = envelope.resolveInboundRouteEnvelopeBuilderWithRuntime;
-	} catch {}
+	};
+	let resolvedDispatch = false;
+	const channelInbound = await loadSubpath("openclaw/plugin-sdk/channel-inbound");
+	if (channelInbound?.dispatchInboundDirectDmWithRuntime) {
+		dispatchInbound = channelInbound.dispatchInboundDirectDmWithRuntime;
+		resolvedDispatch = true;
+	}
+	const harness = await loadSubpath("openclaw/plugin-sdk/agent-harness");
+	const abortRun = harness?.abortAgentHarnessRun ?? harness?.abortEmbeddedAgentRun;
+	if (abortRun) abortEmbeddedAgentRun = abortRun;
+	if (harness?.resolveActiveEmbeddedRunSessionId) resolveActiveRunSessionId = harness.resolveActiveEmbeddedRunSessionId;
+	const envelope = await loadSubpath("openclaw/plugin-sdk/inbound-envelope");
+	if (envelope?.resolveInboundRouteEnvelopeBuilderWithRuntime) resolveRouteEnvelope = envelope.resolveInboundRouteEnvelopeBuilderWithRuntime;
 	if (resolvedDispatch) log.info(`Resolved OpenClaw SDK from ${anchor} (hard-abort=${abortEmbeddedAgentRun && resolveActiveRunSessionId ? "available" : "unavailable"})`);
 	return resolvedDispatch;
 }
@@ -2158,6 +2170,7 @@ function computeOpenClawSdkAnchors(deps) {
 	try {
 		push(deps.which("openclaw"));
 	} catch {}
+	for (const dir of deps.globalModulesDirs ?? []) push((0, node_path.join)(dir, "openclaw", "package.json"));
 	for (const base of [deps.execPath, safeRealpath(deps.realpath, deps.execPath)]) {
 		if (!base) continue;
 		try {
@@ -2176,6 +2189,27 @@ function safeRealpath(realpath, p) {
 	}
 }
 /**
+* Well-known global `node_modules` locations to try as SDK anchors, in priority
+* order. Environment-INDEPENDENT (no PATH / `which` / execPath), so they resolve
+* the SDK even when the in-process plugin context has a stripped PATH or a
+* sandboxed `child_process` (the homebrew-keg self-hosted macOS case where every
+* environment-derived anchor returns nothing). Non-existent candidates are
+* harmless — `createRequire` just fails and the next anchor runs. `NODE_PATH`,
+* when set, is an explicit module-dir list, so honour it too.
+*/
+function candidateGlobalModulesDirs() {
+	const dirs = [
+		"/opt/homebrew/lib/node_modules",
+		"/usr/local/lib/node_modules",
+		"/usr/lib/node_modules",
+		"/usr/local/share/npm/lib/node_modules"
+	];
+	const home = process.env.HOME;
+	if (home) dirs.push((0, node_path.join)(home, ".npm-global", "lib", "node_modules"));
+	for (const d of (process.env.NODE_PATH ?? "").split(node_path.delimiter)) if (d) dirs.push(d);
+	return dirs;
+}
+/**
 * Resolve OpenClaw SDK functions from the running process.
 *
 * The openclaw package is NOT in the plugin's node_modules (it's a peer dep).
@@ -2184,23 +2218,123 @@ function safeRealpath(realpath, p) {
 * relocated-node layouts), then to a `which openclaw` lookup, then fall back to
 * deriving the global modules path from process.execPath.
 */
-function resolveOpenClawSdk(log) {
+async function resolveOpenClawSdk(log) {
 	const pathEnv = process.env.PATH;
 	const anchors = computeOpenClawSdkAnchors({
 		realpath: node_fs.realpathSync,
 		which: () => whichOpenClaw(pathEnv),
 		requireMainFilename: require$1.main?.filename,
 		argv1: process.argv[1],
-		execPath: process.execPath
+		execPath: process.execPath,
+		globalModulesDirs: candidateGlobalModulesDirs()
 	});
 	for (const anchor of anchors) try {
-		if (loadOpenClawSdk((0, node_module.createRequire)(anchor), log, anchor)) return;
+		if (await loadOpenClawSdk((0, node_module.createRequire)(anchor), log, anchor)) return;
 	} catch {}
-	log.warn("OpenClaw SDK not resolvable — chat dispatch will not work");
+	log.warn(`OpenClaw SDK not resolvable — chat dispatch will not work. argv1=${process.argv[1] ?? "<none>"} execPath=${process.execPath} PATH=${pathEnv ? "set" : "EMPTY"} anchorsTried=[${anchors.join(", ")}]`);
 }
 let pluginRuntime = null;
 let chatClient = null;
 let connectingPromise = null;
+/**
+* Decide what `startChatService()` should do given the current connection
+* state. Pure so the branch logic — the load-bearing fix for the
+* health-monitor no-op restart loop (Badi Junior, 2026-07-09) — is unit
+* testable without standing up a real WebSocket or the OpenClaw SDK.
+*
+* OpenClaw calls the registered service's `start()` in two very different
+* situations that a sticky activation flag could not tell apart:
+*  - a redundant duplicate (re-`activate()` per tool-discovery pass / reconnect)
+*    → must be a no-op ('skip'), and
+*  - a channel health-monitor REVIVE of a channel it decided is "stopped"
+*    (`health-monitor: [alfe:default] restarting (reason: stopped)`), sometimes
+*    with no preceding `stop()` → must actually reconnect.
+*
+* Keying on the live client fixes it:
+*  - a connect in flight, or an already-connected client → 'skip'
+*  - a client that exists but is not connected → 'recycle' it then reconnect
+*  - no client at all → 'connect'
+*
+* Exported for unit tests.
+*/
+function decideChatServiceStart(state) {
+	if (state.connectInFlight) return "skip";
+	if (state.clientPresent && state.clientConnected) return "skip";
+	if (state.clientPresent) return "recycle";
+	return "connect";
+}
+const STORED_ATTACHMENT_TYPES = new Set([
+	"image",
+	"video",
+	"audio",
+	"document",
+	"file"
+]);
+/** Narrow a possibly-loose type string, inferring from the mime as a fallback. */
+function coerceStoredAttachmentType(type, mimeType) {
+	if (type && STORED_ATTACHMENT_TYPES.has(type)) return type;
+	const m = mimeType ?? "";
+	if (m.startsWith("image/")) return "image";
+	if (m.startsWith("video/")) return "video";
+	if (m.startsWith("audio/")) return "audio";
+	if (m === "application/pdf" || m.includes("document") || m.includes("spreadsheet") || m.includes("presentation")) return "document";
+	return "file";
+}
+/**
+* Map inbound user attachments to the persisted reference shape (drops the
+* presigned url — it's re-signed on demand). Every composer upload carries a
+* chat-bucket `id`, so all are persisted.
+*/
+function userAttachmentsToStored(refs) {
+	if (!refs?.length) return void 0;
+	const out = [];
+	for (const r of refs) {
+		if (!r.id) continue;
+		out.push({
+			attachmentId: r.id,
+			type: coerceStoredAttachmentType(r.type, r.mimeType),
+			mimeType: r.mimeType,
+			filename: r.filename ?? "file",
+			...typeof r.size === "number" && r.size > 0 ? { size: r.size } : {}
+		});
+	}
+	return out.length ? out : void 0;
+}
+/**
+* Map resolved assistant media to persisted references. Only media uploaded to
+* our bucket (carrying `attachmentId`) is replayable — remote-passthrough media
+* has no bindable record and stays live-URL-only.
+*/
+function assistantMediaToStored(media) {
+	if (!media?.length) return void 0;
+	const out = [];
+	for (const m of media) {
+		if (!m.attachmentId) continue;
+		out.push({
+			attachmentId: m.attachmentId,
+			type: coerceStoredAttachmentType(void 0, m.mimeType),
+			mimeType: m.mimeType ?? "application/octet-stream",
+			filename: m.filename ?? "file",
+			...typeof m.size === "number" && m.size > 0 ? { size: m.size } : {}
+		});
+	}
+	return out.length ? out : void 0;
+}
+/**
+* Project persisted attachment references onto the `sessions.get` wire shape.
+* `attachmentId` becomes the wire `id`; the URL is intentionally omitted — the
+* client resolves a short-lived signed URL on demand.
+*/
+function replayAttachments(atts) {
+	if (!atts?.length) return void 0;
+	return atts.map((a) => ({
+		id: a.attachmentId,
+		type: a.type,
+		mimeType: a.mimeType,
+		filename: a.filename,
+		...typeof a.size === "number" ? { size: a.size } : {}
+	}));
+}
 const MAX_FILE_SIZE = 50 * 1024 * 1024;
 const DOWNLOAD_TIMEOUT_MS = 3e4;
 const MAX_REDIRECTS = 5;
@@ -2450,7 +2584,7 @@ async function handleAgentRequest(request, log) {
 	const cfg = runtime.config.loadConfig();
 	const sessionId = conversationId ?? legacySessionKey;
 	if (!await getSession(sessionId)) await createSession(sessionId, "", "alfe", tenantId, userId);
-	await addMessage(sessionId, "user", message, userId ?? senderId, displayName ?? senderId);
+	await addMessage(sessionId, "user", message, userId ?? senderId, displayName ?? senderId, void 0, userAttachmentsToStored(rawAttachments));
 	const runGate = {
 		runId: null,
 		sessionKey: null
@@ -2686,7 +2820,7 @@ async function handleAgentRequest(request, log) {
 					const note = formatMediaFailureNote(media.newFailures);
 					responseText = responseText ? `${responseText}\n\n${note}` : note;
 				}
-				await addMessage(sessionId, "assistant", responseText);
+				await addMessage(sessionId, "assistant", responseText, void 0, void 0, void 0, assistantMediaToStored(media.attachments));
 				if (isA2A) a2aResponseBuffer += (a2aResponseBuffer && responseText ? "\n\n" : "") + responseText;
 				chatClient?.notify("agent-message", {
 					conversationId: conversationId ?? legacySessionKey,
@@ -2799,7 +2933,8 @@ async function handleSessionsGet(request, log) {
 				role: m.role,
 				content: m.content,
 				timestamp: m.timestamp,
-				...m.components?.length ? { components: m.components } : {}
+				...m.components?.length ? { components: m.components } : {},
+				...m.attachments?.length ? { attachments: replayAttachments(m.attachments) } : {}
 			})),
 			activity: await resolveHistoryActivity(session)
 		});
@@ -2843,16 +2978,31 @@ const plugin = {
 			log.info(`Registered ${String(a2aTools.length)} agent tools`);
 		}
 		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
-		const startChatService = () => {
-			if (globalThis.__alfeChatPluginActivated === true) {
-				log.debug("Chat plugin already activated — skipping duplicate");
+		const startChatService = async () => {
+			const action = decideChatServiceStart({
+				connectInFlight: connectingPromise !== null,
+				clientPresent: chatClient !== null,
+				clientConnected: chatClient?.isConnected ?? false
+			});
+			if (action === "skip") {
+				log.debug("Chat service already connected or connecting — skipping duplicate start");
 				return;
 			}
+			if (action === "recycle") {
+				log.info("Chat service client present but not connected — recycling before reconnect");
+				try {
+					chatClient?.stop();
+				} catch (err) {
+					log.debug(`Recycle of stale chat client failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				chatClient = null;
+			}
 			globalThis.__alfeChatPluginActivated = true;
 			log.info("Chat plugin registering...");
-			resolveOpenClawSdk(log);
+			await resolveOpenClawSdk(log);
 			pluginRuntime = api.runtime ?? null;
-			connectingPromise = Promise.resolve().then(() => {
+			let thisConnect = null;
+			thisConnect = Promise.resolve().then(() => {
 				try {
 					const { apiKey, chatWsUrl } = (0, _alfe_ai_chat.resolveAlfeChat)({
 						apiKey: pluginConfig.apiKey,
@@ -2900,7 +3050,10 @@ const plugin = {
 				} catch (err) {
 					log.error(`Failed to initialize chat service: ${err instanceof Error ? err.message : String(err)}`);
 				}
+			}).finally(() => {
+				if (connectingPromise === thisConnect) connectingPromise = null;
 			});
+			connectingPromise = thisConnect;
 		};
 		const stopChatService = async () => {
 			globalThis.__alfeChatPluginActivated = false;
@@ -2952,7 +3105,8 @@ const plugin = {
 						role: m.role,
 						content: m.content,
 						timestamp: m.timestamp,
-						...m.components?.length ? { components: m.components } : {}
+						...m.components?.length ? { components: m.components } : {},
+						...m.attachments?.length ? { attachments: replayAttachments(m.attachments) } : {}
 					})),
 					activity: await resolveHistoryActivity(session)
 				};
@@ -3079,6 +3233,12 @@ Object.defineProperty(exports, "createAlfeChannelPlugin", {
 		return createAlfeChannelPlugin;
 	}
 });
+Object.defineProperty(exports, "decideChatServiceStart", {
+	enumerable: true,
+	get: function() {
+		return decideChatServiceStart;
+	}
+});
 Object.defineProperty(exports, "joinAssistantText", {
 	enumerable: true,
 	get: function() {

package/dist/plugin2.d.cts

@@ -1,2 +1,2 @@
-import { _ as rewriteAssistantText, a as VOICE_REPLY_SYSTEM_PROMPT, c as __setActiveRunForTest, d as buildOriginEnvelopeContext, f as buildToolActivity, g as resolveAbortTargetKeys, h as plugin, i as RunEventGate, l as admitAgentEvent, m as joinAssistantText, n as AnchorEnv, o as __agentTurnQueueForTest, p as computeOpenClawSdkAnchors, r as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, s as __resetAgentTurnQueueForTest, t as ActiveRunRef, u as buildA2ACompletePayload, v as stripLeakedToolSummary } from "./plugin.cjs";
-export { ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+import { _ as resolveAbortTargetKeys, a as VOICE_REPLY_SYSTEM_PROMPT, c as __setActiveRunForTest, d as buildOriginEnvelopeContext, f as buildToolActivity, g as plugin, h as joinAssistantText, i as RunEventGate, l as admitAgentEvent, m as decideChatServiceStart, n as AnchorEnv, o as __agentTurnQueueForTest, p as computeOpenClawSdkAnchors, r as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, s as __resetAgentTurnQueueForTest, t as ActiveRunRef, u as buildA2ACompletePayload, v as rewriteAssistantText, y as stripLeakedToolSummary } from "./plugin.cjs";
+export { ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };

package/dist/plugin2.d.ts

@@ -1,2 +1,2 @@
-import { _ as rewriteAssistantText, a as VOICE_REPLY_SYSTEM_PROMPT, c as __setActiveRunForTest, d as buildOriginEnvelopeContext, f as buildToolActivity, g as resolveAbortTargetKeys, h as plugin, i as RunEventGate, l as admitAgentEvent, m as joinAssistantText, n as AnchorEnv, o as __agentTurnQueueForTest, p as computeOpenClawSdkAnchors, r as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, s as __resetAgentTurnQueueForTest, t as ActiveRunRef, u as buildA2ACompletePayload, v as stripLeakedToolSummary } from "./plugin.js";
-export { ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+import { _ as resolveAbortTargetKeys, a as VOICE_REPLY_SYSTEM_PROMPT, c as __setActiveRunForTest, d as buildOriginEnvelopeContext, f as buildToolActivity, g as plugin, h as joinAssistantText, i as RunEventGate, l as admitAgentEvent, m as decideChatServiceStart, n as AnchorEnv, o as __agentTurnQueueForTest, p as computeOpenClawSdkAnchors, r as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, s as __resetAgentTurnQueueForTest, t as ActiveRunRef, u as buildA2ACompletePayload, v as rewriteAssistantText, y as stripLeakedToolSummary } from "./plugin.js";
+export { ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };

package/dist/plugin2.js

@@ -3,6 +3,7 @@ import { mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs
 import { existsSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { ChatServiceClient, resolveAlfeChat } from "@alfe.ai/chat";
 import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
@@ -210,7 +211,8 @@ async function uploadLocalFile(localPath, log, deps) {
 			url: presigned.downloadUrl,
 			filename,
 			mimeType,
-			size
+			size,
+			attachmentId: presigned.id
 		};
 	} catch (err) {
 		log.warn(`Outbound media upload failed for ${filename}: ${err instanceof Error ? err.message : String(err)}`);
@@ -874,7 +876,7 @@ async function createSession(sessionId, agentId, channel, tenantId, userId) {
 	return session;
 }
 const writeLocks = /* @__PURE__ */ new Map();
-async function addMessage(sessionId, role, content, senderId, senderName, components) {
+async function addMessage(sessionId, role, content, senderId, senderName, components, attachments) {
 	const next = (writeLocks.get(sessionId) ?? Promise.resolve()).then(async () => {
 		const session = await getSession(sessionId);
 		if (!session) return;
@@ -884,7 +886,8 @@ async function addMessage(sessionId, role, content, senderId, senderName, compon
 			timestamp: Date.now(),
 			...senderId ? { senderId } : {},
 			...senderName ? { senderName } : {},
-			...components?.length ? { components } : {}
+			...components?.length ? { components } : {},
+			...attachments?.length ? { attachments } : {}
 		});
 		await saveSession(session);
 	}).finally(() => {
@@ -2070,24 +2073,33 @@ let resolveRouteEnvelope = null;
 * degrades `chat.abort` to a logged no-op (Stop still seals the UI) rather than
 * a hard failure.
 */
-function loadOpenClawSdk(req, log, anchor) {
-	let resolvedDispatch = false;
-	try {
-		const channelInbound = req("openclaw/plugin-sdk/channel-inbound");
-		if (channelInbound.dispatchInboundDirectDmWithRuntime) {
-			dispatchInbound = channelInbound.dispatchInboundDirectDmWithRuntime;
-			resolvedDispatch = true;
+async function loadOpenClawSdk(req, log, anchor) {
+	const loadSubpath = async (subpath) => {
+		try {
+			const mod = await import(pathToFileURL(req.resolve(subpath)).href);
+			return {
+				...typeof mod.default === "object" ? mod.default : void 0,
+				...mod
+			};
+		} catch {}
+		try {
+			return req(subpath);
+		} catch {
+			return;
 		}
-	} catch {}
-	try {
-		const harness = req("openclaw/plugin-sdk/agent-harness");
-		if (harness.abortEmbeddedAgentRun) abortEmbeddedAgentRun = harness.abortEmbeddedAgentRun;
-		if (harness.resolveActiveEmbeddedRunSessionId) resolveActiveRunSessionId = harness.resolveActiveEmbeddedRunSessionId;
-	} catch {}
-	try {
-		const envelope = req("openclaw/plugin-sdk/inbound-envelope");
-		if (envelope.resolveInboundRouteEnvelopeBuilderWithRuntime) resolveRouteEnvelope = envelope.resolveInboundRouteEnvelopeBuilderWithRuntime;
-	} catch {}
+	};
+	let resolvedDispatch = false;
+	const channelInbound = await loadSubpath("openclaw/plugin-sdk/channel-inbound");
+	if (channelInbound?.dispatchInboundDirectDmWithRuntime) {
+		dispatchInbound = channelInbound.dispatchInboundDirectDmWithRuntime;
+		resolvedDispatch = true;
+	}
+	const harness = await loadSubpath("openclaw/plugin-sdk/agent-harness");
+	const abortRun = harness?.abortAgentHarnessRun ?? harness?.abortEmbeddedAgentRun;
+	if (abortRun) abortEmbeddedAgentRun = abortRun;
+	if (harness?.resolveActiveEmbeddedRunSessionId) resolveActiveRunSessionId = harness.resolveActiveEmbeddedRunSessionId;
+	const envelope = await loadSubpath("openclaw/plugin-sdk/inbound-envelope");
+	if (envelope?.resolveInboundRouteEnvelopeBuilderWithRuntime) resolveRouteEnvelope = envelope.resolveInboundRouteEnvelopeBuilderWithRuntime;
 	if (resolvedDispatch) log.info(`Resolved OpenClaw SDK from ${anchor} (hard-abort=${abortEmbeddedAgentRun && resolveActiveRunSessionId ? "available" : "unavailable"})`);
 	return resolvedDispatch;
 }
@@ -2158,6 +2170,7 @@ function computeOpenClawSdkAnchors(deps) {
 	try {
 		push(deps.which("openclaw"));
 	} catch {}
+	for (const dir of deps.globalModulesDirs ?? []) push(join(dir, "openclaw", "package.json"));
 	for (const base of [deps.execPath, safeRealpath(deps.realpath, deps.execPath)]) {
 		if (!base) continue;
 		try {
@@ -2176,6 +2189,27 @@ function safeRealpath(realpath, p) {
 	}
 }
 /**
+* Well-known global `node_modules` locations to try as SDK anchors, in priority
+* order. Environment-INDEPENDENT (no PATH / `which` / execPath), so they resolve
+* the SDK even when the in-process plugin context has a stripped PATH or a
+* sandboxed `child_process` (the homebrew-keg self-hosted macOS case where every
+* environment-derived anchor returns nothing). Non-existent candidates are
+* harmless — `createRequire` just fails and the next anchor runs. `NODE_PATH`,
+* when set, is an explicit module-dir list, so honour it too.
+*/
+function candidateGlobalModulesDirs() {
+	const dirs = [
+		"/opt/homebrew/lib/node_modules",
+		"/usr/local/lib/node_modules",
+		"/usr/lib/node_modules",
+		"/usr/local/share/npm/lib/node_modules"
+	];
+	const home = process.env.HOME;
+	if (home) dirs.push(join(home, ".npm-global", "lib", "node_modules"));
+	for (const d of (process.env.NODE_PATH ?? "").split(delimiter)) if (d) dirs.push(d);
+	return dirs;
+}
+/**
 * Resolve OpenClaw SDK functions from the running process.
 *
 * The openclaw package is NOT in the plugin's node_modules (it's a peer dep).
@@ -2184,23 +2218,123 @@ function safeRealpath(realpath, p) {
 * relocated-node layouts), then to a `which openclaw` lookup, then fall back to
 * deriving the global modules path from process.execPath.
 */
-function resolveOpenClawSdk(log) {
+async function resolveOpenClawSdk(log) {
 	const pathEnv = process.env.PATH;
 	const anchors = computeOpenClawSdkAnchors({
 		realpath: realpathSync,
 		which: () => whichOpenClaw(pathEnv),
 		requireMainFilename: require.main?.filename,
 		argv1: process.argv[1],
-		execPath: process.execPath
+		execPath: process.execPath,
+		globalModulesDirs: candidateGlobalModulesDirs()
 	});
 	for (const anchor of anchors) try {
-		if (loadOpenClawSdk(createRequire(anchor), log, anchor)) return;
+		if (await loadOpenClawSdk(createRequire(anchor), log, anchor)) return;
 	} catch {}
-	log.warn("OpenClaw SDK not resolvable — chat dispatch will not work");
+	log.warn(`OpenClaw SDK not resolvable — chat dispatch will not work. argv1=${process.argv[1] ?? "<none>"} execPath=${process.execPath} PATH=${pathEnv ? "set" : "EMPTY"} anchorsTried=[${anchors.join(", ")}]`);
 }
 let pluginRuntime = null;
 let chatClient = null;
 let connectingPromise = null;
+/**
+* Decide what `startChatService()` should do given the current connection
+* state. Pure so the branch logic — the load-bearing fix for the
+* health-monitor no-op restart loop (Badi Junior, 2026-07-09) — is unit
+* testable without standing up a real WebSocket or the OpenClaw SDK.
+*
+* OpenClaw calls the registered service's `start()` in two very different
+* situations that a sticky activation flag could not tell apart:
+*  - a redundant duplicate (re-`activate()` per tool-discovery pass / reconnect)
+*    → must be a no-op ('skip'), and
+*  - a channel health-monitor REVIVE of a channel it decided is "stopped"
+*    (`health-monitor: [alfe:default] restarting (reason: stopped)`), sometimes
+*    with no preceding `stop()` → must actually reconnect.
+*
+* Keying on the live client fixes it:
+*  - a connect in flight, or an already-connected client → 'skip'
+*  - a client that exists but is not connected → 'recycle' it then reconnect
+*  - no client at all → 'connect'
+*
+* Exported for unit tests.
+*/
+function decideChatServiceStart(state) {
+	if (state.connectInFlight) return "skip";
+	if (state.clientPresent && state.clientConnected) return "skip";
+	if (state.clientPresent) return "recycle";
+	return "connect";
+}
+const STORED_ATTACHMENT_TYPES = new Set([
+	"image",
+	"video",
+	"audio",
+	"document",
+	"file"
+]);
+/** Narrow a possibly-loose type string, inferring from the mime as a fallback. */
+function coerceStoredAttachmentType(type, mimeType) {
+	if (type && STORED_ATTACHMENT_TYPES.has(type)) return type;
+	const m = mimeType ?? "";
+	if (m.startsWith("image/")) return "image";
+	if (m.startsWith("video/")) return "video";
+	if (m.startsWith("audio/")) return "audio";
+	if (m === "application/pdf" || m.includes("document") || m.includes("spreadsheet") || m.includes("presentation")) return "document";
+	return "file";
+}
+/**
+* Map inbound user attachments to the persisted reference shape (drops the
+* presigned url — it's re-signed on demand). Every composer upload carries a
+* chat-bucket `id`, so all are persisted.
+*/
+function userAttachmentsToStored(refs) {
+	if (!refs?.length) return void 0;
+	const out = [];
+	for (const r of refs) {
+		if (!r.id) continue;
+		out.push({
+			attachmentId: r.id,
+			type: coerceStoredAttachmentType(r.type, r.mimeType),
+			mimeType: r.mimeType,
+			filename: r.filename ?? "file",
+			...typeof r.size === "number" && r.size > 0 ? { size: r.size } : {}
+		});
+	}
+	return out.length ? out : void 0;
+}
+/**
+* Map resolved assistant media to persisted references. Only media uploaded to
+* our bucket (carrying `attachmentId`) is replayable — remote-passthrough media
+* has no bindable record and stays live-URL-only.
+*/
+function assistantMediaToStored(media) {
+	if (!media?.length) return void 0;
+	const out = [];
+	for (const m of media) {
+		if (!m.attachmentId) continue;
+		out.push({
+			attachmentId: m.attachmentId,
+			type: coerceStoredAttachmentType(void 0, m.mimeType),
+			mimeType: m.mimeType ?? "application/octet-stream",
+			filename: m.filename ?? "file",
+			...typeof m.size === "number" && m.size > 0 ? { size: m.size } : {}
+		});
+	}
+	return out.length ? out : void 0;
+}
+/**
+* Project persisted attachment references onto the `sessions.get` wire shape.
+* `attachmentId` becomes the wire `id`; the URL is intentionally omitted — the
+* client resolves a short-lived signed URL on demand.
+*/
+function replayAttachments(atts) {
+	if (!atts?.length) return void 0;
+	return atts.map((a) => ({
+		id: a.attachmentId,
+		type: a.type,
+		mimeType: a.mimeType,
+		filename: a.filename,
+		...typeof a.size === "number" ? { size: a.size } : {}
+	}));
+}
 const MAX_FILE_SIZE = 50 * 1024 * 1024;
 const DOWNLOAD_TIMEOUT_MS = 3e4;
 const MAX_REDIRECTS = 5;
@@ -2450,7 +2584,7 @@ async function handleAgentRequest(request, log) {
 	const cfg = runtime.config.loadConfig();
 	const sessionId = conversationId ?? legacySessionKey;
 	if (!await getSession(sessionId)) await createSession(sessionId, "", "alfe", tenantId, userId);
-	await addMessage(sessionId, "user", message, userId ?? senderId, displayName ?? senderId);
+	await addMessage(sessionId, "user", message, userId ?? senderId, displayName ?? senderId, void 0, userAttachmentsToStored(rawAttachments));
 	const runGate = {
 		runId: null,
 		sessionKey: null
@@ -2686,7 +2820,7 @@ async function handleAgentRequest(request, log) {
 					const note = formatMediaFailureNote(media.newFailures);
 					responseText = responseText ? `${responseText}\n\n${note}` : note;
 				}
-				await addMessage(sessionId, "assistant", responseText);
+				await addMessage(sessionId, "assistant", responseText, void 0, void 0, void 0, assistantMediaToStored(media.attachments));
 				if (isA2A) a2aResponseBuffer += (a2aResponseBuffer && responseText ? "\n\n" : "") + responseText;
 				chatClient?.notify("agent-message", {
 					conversationId: conversationId ?? legacySessionKey,
@@ -2799,7 +2933,8 @@ async function handleSessionsGet(request, log) {
 				role: m.role,
 				content: m.content,
 				timestamp: m.timestamp,
-				...m.components?.length ? { components: m.components } : {}
+				...m.components?.length ? { components: m.components } : {},
+				...m.attachments?.length ? { attachments: replayAttachments(m.attachments) } : {}
 			})),
 			activity: await resolveHistoryActivity(session)
 		});
@@ -2843,16 +2978,31 @@ const plugin = {
 			log.info(`Registered ${String(a2aTools.length)} agent tools`);
 		}
 		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
-		const startChatService = () => {
-			if (globalThis.__alfeChatPluginActivated === true) {
-				log.debug("Chat plugin already activated — skipping duplicate");
+		const startChatService = async () => {
+			const action = decideChatServiceStart({
+				connectInFlight: connectingPromise !== null,
+				clientPresent: chatClient !== null,
+				clientConnected: chatClient?.isConnected ?? false
+			});
+			if (action === "skip") {
+				log.debug("Chat service already connected or connecting — skipping duplicate start");
 				return;
 			}
+			if (action === "recycle") {
+				log.info("Chat service client present but not connected — recycling before reconnect");
+				try {
+					chatClient?.stop();
+				} catch (err) {
+					log.debug(`Recycle of stale chat client failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				chatClient = null;
+			}
 			globalThis.__alfeChatPluginActivated = true;
 			log.info("Chat plugin registering...");
-			resolveOpenClawSdk(log);
+			await resolveOpenClawSdk(log);
 			pluginRuntime = api.runtime ?? null;
-			connectingPromise = Promise.resolve().then(() => {
+			let thisConnect = null;
+			thisConnect = Promise.resolve().then(() => {
 				try {
 					const { apiKey, chatWsUrl } = resolveAlfeChat({
 						apiKey: pluginConfig.apiKey,
@@ -2900,7 +3050,10 @@ const plugin = {
 				} catch (err) {
 					log.error(`Failed to initialize chat service: ${err instanceof Error ? err.message : String(err)}`);
 				}
+			}).finally(() => {
+				if (connectingPromise === thisConnect) connectingPromise = null;
 			});
+			connectingPromise = thisConnect;
 		};
 		const stopChatService = async () => {
 			globalThis.__alfeChatPluginActivated = false;
@@ -2952,7 +3105,8 @@ const plugin = {
 						role: m.role,
 						content: m.content,
 						timestamp: m.timestamp,
-						...m.components?.length ? { components: m.components } : {}
+						...m.components?.length ? { components: m.components } : {},
+						...m.attachments?.length ? { attachments: replayAttachments(m.attachments) } : {}
 					})),
 					activity: await resolveHistoryActivity(session)
 				};
@@ -3013,4 +3167,4 @@ const plugin = {
 	}
 };
 //#endregion
-export { __setActiveRunForTest as a, buildOriginEnvelopeContext as c, joinAssistantText as d, plugin as f, createAlfeChannelPlugin as g, stripLeakedToolSummary as h, __resetAgentTurnQueueForTest as i, buildToolActivity as l, rewriteAssistantText as m, VOICE_REPLY_SYSTEM_PROMPT as n, admitAgentEvent as o, resolveAbortTargetKeys as p, __agentTurnQueueForTest as r, buildA2ACompletePayload as s, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as t, computeOpenClawSdkAnchors as u };
+export { createAlfeChannelPlugin as _, __setActiveRunForTest as a, buildOriginEnvelopeContext as c, decideChatServiceStart as d, joinAssistantText as f, stripLeakedToolSummary as g, rewriteAssistantText as h, __resetAgentTurnQueueForTest as i, buildToolActivity as l, resolveAbortTargetKeys as m, VOICE_REPLY_SYSTEM_PROMPT as n, admitAgentEvent as o, plugin as p, __agentTurnQueueForTest as r, buildA2ACompletePayload as s, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as t, computeOpenClawSdkAnchors as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/openclaw-chat",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "OpenClaw chat plugin for Alfe — web widget and mobile app channels",
   "type": "module",
   "main": "./dist/plugin.js",
@@ -27,7 +27,7 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@alfe.ai/agent-api-client": "^0.10.0",
+    "@alfe.ai/agent-api-client": "^0.11.0",
     "@alfe.ai/chat": "^0.0.16",
     "@alfe.ai/config": "^0.3.0"
   },