@alfe.ai/openclaw-chat 0.9.3 → 0.9.5

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-import { C as SessionSummary, S as SessionData, _ as createAlfeChannelPlugin, b as AlfeResolvedAccount, p as plugin, v as AlfeChannelConfig, x as ChatMessage, y as AlfePluginConfig } 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 SessionSummary, S as SessionData, _ as createAlfeChannelPlugin, b as AlfeResolvedAccount, p as plugin, v as AlfeChannelConfig, x as ChatMessage, y as AlfePluginConfig } 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 { d as plugin, h as createAlfeChannelPlugin } from "./plugin2.js";
+import { _ as createAlfeChannelPlugin, p as plugin } from "./plugin2.js";
 export { createAlfeChannelPlugin, plugin as default };

package/dist/plugin.cjs

@@ -12,6 +12,8 @@ exports.admitAgentEvent = require_plugin.admitAgentEvent;
 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
@@ -568,6 +588,64 @@ interface PluginApi {
     priority?: number;
   }): void;
 }
+/**
+ * Injectable seams for anchor computation — real implementations resolve
+ * symlinks and locate the `openclaw` bin. Overridable so the pure anchor
+ * logic can be unit-tested without a homebrew/openclaw layout on disk.
+ */
+interface AnchorEnv {
+  realpath: (p: string) => string;
+  which: (cmd: string) => string | undefined;
+  requireMainFilename: string | undefined;
+  argv1: string | undefined;
+  execPath: string;
+}
+/**
+ * Compute the ordered, de-duplicated list of resolver anchors to try, each
+ * best-effort `realpath`'d so a bin SYMLINK (e.g. `/opt/homebrew/bin/openclaw`
+ * → `../lib/node_modules/openclaw/openclaw.mjs`) resolves to the real module
+ * whose `createRequire` CAN find `openclaw/plugin-sdk/*`.
+ *
+ * Order (proven against homebrew-keg / relocated-node / bin-symlink layouts):
+ *   1. require.main?.filename, process.argv[1] — realpath'd (the bin symlink →
+ *      real `openclaw.mjs`). argv[1] is often the symlink; realpath is what
+ *      makes it a usable anchor.
+ *   2. `which openclaw` → realpath — the robust cross-setup anchor. On a
+ *      homebrew keg, argv[1] is a symlink under `/opt/homebrew/bin` (no
+ *      `node_modules` sibling); its realpath lands in the real
+ *      `lib/node_modules/openclaw` tree where resolution succeeds.
+ *   3. execPath-derived global-modules path (the original Strategy 2), plus a
+ *      realpath'd variant of the execPath prefix for relocated-node layouts.
+ *
+ * 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;
@@ -649,4 +727,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { SessionSummary as C, SessionData as S, createAlfeChannelPlugin as _, __agentTurnQueueForTest as a, AlfeResolvedAccount as b, admitAgentEvent as c, buildToolActivity as d, joinAssistantText as f, stripLeakedToolSummary as g, rewriteAssistantText as h, VOICE_REPLY_SYSTEM_PROMPT as i, buildA2ACompletePayload as l, resolveAbortTargetKeys as m, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as n, __resetAgentTurnQueueForTest as o, plugin as p, RunEventGate as r, __setActiveRunForTest as s, ActiveRunRef as t, buildOriginEnvelopeContext as u, AlfeChannelConfig as v, ChatMessage as x, AlfePluginConfig 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
@@ -568,6 +588,64 @@ interface PluginApi {
     priority?: number;
   }): void;
 }
+/**
+ * Injectable seams for anchor computation — real implementations resolve
+ * symlinks and locate the `openclaw` bin. Overridable so the pure anchor
+ * logic can be unit-tested without a homebrew/openclaw layout on disk.
+ */
+interface AnchorEnv {
+  realpath: (p: string) => string;
+  which: (cmd: string) => string | undefined;
+  requireMainFilename: string | undefined;
+  argv1: string | undefined;
+  execPath: string;
+}
+/**
+ * Compute the ordered, de-duplicated list of resolver anchors to try, each
+ * best-effort `realpath`'d so a bin SYMLINK (e.g. `/opt/homebrew/bin/openclaw`
+ * → `../lib/node_modules/openclaw/openclaw.mjs`) resolves to the real module
+ * whose `createRequire` CAN find `openclaw/plugin-sdk/*`.
+ *
+ * Order (proven against homebrew-keg / relocated-node / bin-symlink layouts):
+ *   1. require.main?.filename, process.argv[1] — realpath'd (the bin symlink →
+ *      real `openclaw.mjs`). argv[1] is often the symlink; realpath is what
+ *      makes it a usable anchor.
+ *   2. `which openclaw` → realpath — the robust cross-setup anchor. On a
+ *      homebrew keg, argv[1] is a symlink under `/opt/homebrew/bin` (no
+ *      `node_modules` sibling); its realpath lands in the real
+ *      `lib/node_modules/openclaw` tree where resolution succeeds.
+ *   3. execPath-derived global-modules path (the original Strategy 2), plus a
+ *      realpath'd variant of the execPath prefix for relocated-node layouts.
+ *
+ * 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;
@@ -649,4 +727,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { SessionSummary as C, SessionData as S, createAlfeChannelPlugin as _, __agentTurnQueueForTest as a, AlfeResolvedAccount as b, admitAgentEvent as c, buildToolActivity as d, joinAssistantText as f, stripLeakedToolSummary as g, rewriteAssistantText as h, VOICE_REPLY_SYSTEM_PROMPT as i, buildA2ACompletePayload as l, resolveAbortTargetKeys as m, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as n, __resetAgentTurnQueueForTest as o, plugin as p, RunEventGate as r, __setActiveRunForTest as s, ActiveRunRef as t, buildOriginEnvelopeContext as u, AlfeChannelConfig as v, ChatMessage as x, AlfePluginConfig 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 plugin, f as resolveAbortTargetKeys, i as __resetAgentTurnQueueForTest, l as buildToolActivity, m as stripLeakedToolSummary, n as VOICE_REPLY_SYSTEM_PROMPT, o as admitAgentEvent, p as rewriteAssistantText, r as __agentTurnQueueForTest, s as buildA2ACompletePayload, t as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, u as joinAssistantText } from "./plugin2.js";
-export { CROSS_AGENT_TOOLS_SYSTEM_PROMPT, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, 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

@@ -1,12 +1,13 @@
 let node_module = require("node:module");
 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_os = require("node:os");
 let _alfe_ai_chat = require("@alfe.ai/chat");
 let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
 let node_crypto = require("node:crypto");
 let _alfe_ai_config = require("@alfe.ai/config");
-let node_fs = require("node:fs");
 //#region src/outbound-media.ts
 /**
 * Outbound media upload — agent → user.
@@ -209,7 +210,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)}`);
@@ -873,7 +875,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;
@@ -883,7 +885,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(() => {
@@ -2091,27 +2094,214 @@ function loadOpenClawSdk(req, log, anchor) {
 	return resolvedDispatch;
 }
 /**
+* Default `which openclaw` implementation. Prefers the shell's own resolver
+* (`command -v` / `which`), then falls back to scanning `PATH` for an
+* `openclaw` executable. Returns undefined if it can't be located — every
+* caller treats a missing anchor as "skip", never as fatal.
+*/
+function whichOpenClaw(pathEnv) {
+	for (const probe of [{
+		cmd: "command",
+		args: ["-v", "openclaw"]
+	}, {
+		cmd: "which",
+		args: ["openclaw"]
+	}]) try {
+		const out = (0, node_child_process.execFileSync)(probe.cmd, probe.args, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim().split("\n")[0]?.trim();
+		if (out) return out;
+	} catch {}
+	for (const dir of (pathEnv ?? "").split(node_path.delimiter)) {
+		if (!dir) continue;
+		const candidate = (0, node_path.join)(dir, "openclaw");
+		try {
+			(0, node_fs.realpathSync)(candidate);
+			return candidate;
+		} catch {}
+	}
+}
+/**
+* Compute the ordered, de-duplicated list of resolver anchors to try, each
+* best-effort `realpath`'d so a bin SYMLINK (e.g. `/opt/homebrew/bin/openclaw`
+* → `../lib/node_modules/openclaw/openclaw.mjs`) resolves to the real module
+* whose `createRequire` CAN find `openclaw/plugin-sdk/*`.
+*
+* Order (proven against homebrew-keg / relocated-node / bin-symlink layouts):
+*   1. require.main?.filename, process.argv[1] — realpath'd (the bin symlink →
+*      real `openclaw.mjs`). argv[1] is often the symlink; realpath is what
+*      makes it a usable anchor.
+*   2. `which openclaw` → realpath — the robust cross-setup anchor. On a
+*      homebrew keg, argv[1] is a symlink under `/opt/homebrew/bin` (no
+*      `node_modules` sibling); its realpath lands in the real
+*      `lib/node_modules/openclaw` tree where resolution succeeds.
+*   3. execPath-derived global-modules path (the original Strategy 2), plus a
+*      realpath'd variant of the execPath prefix for relocated-node layouts.
+*
+* Pure except for the injected `realpath` / `which` seams — unit-tested.
+*/
+function computeOpenClawSdkAnchors(deps) {
+	const anchors = [];
+	const push = (p) => {
+		if (!p) return;
+		let real;
+		try {
+			real = deps.realpath(p);
+		} catch {}
+		for (const candidate of [real, p]) if (candidate && !anchors.includes(candidate)) anchors.push(candidate);
+	};
+	push(deps.requireMainFilename);
+	push(deps.argv1);
+	try {
+		push(deps.which("openclaw"));
+	} catch {}
+	for (const base of [deps.execPath, safeRealpath(deps.realpath, deps.execPath)]) {
+		if (!base) continue;
+		try {
+			const derived = (0, node_path.join)((0, node_path.resolve)((0, node_path.dirname)(base), ".."), "lib", "node_modules", "openclaw", "package.json");
+			if (!anchors.includes(derived)) anchors.push(derived);
+		} catch {}
+	}
+	return anchors;
+}
+function safeRealpath(realpath, p) {
+	try {
+		const r = realpath(p);
+		return r === p ? void 0 : r;
+	} catch {
+		return;
+	}
+}
+/**
 * Resolve OpenClaw SDK functions from the running process.
 *
 * The openclaw package is NOT in the plugin's node_modules (it's a peer dep).
 * Since the plugin runs inside OpenClaw's process, we anchor resolution to
-* OpenClaw's own entry module via require.main, then fall back to deriving
-* the global modules path from process.execPath.
+* OpenClaw's own realpath'd entry (surviving bin-symlink / homebrew-keg /
+* relocated-node layouts), then to a `which openclaw` lookup, then fall back to
+* deriving the global modules path from process.execPath.
 */
 function resolveOpenClawSdk(log) {
-	const anchors = [require$1.main?.filename, process.argv[1]].filter(Boolean);
+	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
+	});
 	for (const anchor of anchors) try {
 		if (loadOpenClawSdk((0, node_module.createRequire)(anchor), log, anchor)) return;
 	} catch {}
-	try {
-		const derivedPath = (0, node_path.join)((0, node_path.resolve)((0, node_path.dirname)(process.execPath), ".."), "lib", "node_modules", "openclaw", "package.json");
-		if (loadOpenClawSdk((0, node_module.createRequire)(derivedPath), log, derivedPath)) return;
-	} catch {}
 	log.warn("OpenClaw SDK not resolvable — chat dispatch will not work");
 }
 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;
@@ -2361,7 +2551,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
@@ -2597,7 +2787,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,
@@ -2710,7 +2900,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)
 		});
@@ -2755,15 +2946,30 @@ const plugin = {
 		}
 		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 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);
 			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,
@@ -2811,7 +3017,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;
@@ -2863,13 +3072,15 @@ 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)
 				};
 			});
+			api.registerGatewayMethod("runtime.activity", () => Promise.resolve({ active: activeRun !== null }));
 			gw.__alfeChatGatewayMethodsRegistered = true;
-			log.info("Registered gateway RPC methods: sessions.list, sessions.get");
+			log.info("Registered gateway RPC methods: sessions.list, sessions.get, runtime.activity");
 		}
 		api.on("session_start", async (...eventArgs) => {
 			if (!pluginRuntime) return;
@@ -2977,12 +3188,24 @@ Object.defineProperty(exports, "buildToolActivity", {
 		return buildToolActivity;
 	}
 });
+Object.defineProperty(exports, "computeOpenClawSdkAnchors", {
+	enumerable: true,
+	get: function() {
+		return computeOpenClawSdkAnchors;
+	}
+});
 Object.defineProperty(exports, "createAlfeChannelPlugin", {
 	enumerable: true,
 	get: function() {
 		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 { a as __agentTurnQueueForTest, c as admitAgentEvent, d as buildToolActivity, f as joinAssistantText, g as stripLeakedToolSummary, h as rewriteAssistantText, i as VOICE_REPLY_SYSTEM_PROMPT, l as buildA2ACompletePayload, m as resolveAbortTargetKeys, n as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, o as __resetAgentTurnQueueForTest, p as plugin, r as RunEventGate, s as __setActiveRunForTest, t as ActiveRunRef, u as buildOriginEnvelopeContext } from "./plugin.cjs";
-export { ActiveRunRef, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, 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 { a as __agentTurnQueueForTest, c as admitAgentEvent, d as buildToolActivity, f as joinAssistantText, g as stripLeakedToolSummary, h as rewriteAssistantText, i as VOICE_REPLY_SYSTEM_PROMPT, l as buildA2ACompletePayload, m as resolveAbortTargetKeys, n as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, o as __resetAgentTurnQueueForTest, p as plugin, r as RunEventGate, s as __setActiveRunForTest, t as ActiveRunRef, u as buildOriginEnvelopeContext } from "./plugin.js";
-export { ActiveRunRef, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, 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

@@ -1,12 +1,13 @@
 import { createRequire } from "node:module";
 import { mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { ChatServiceClient, resolveAlfeChat } from "@alfe.ai/chat";
 import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
 import { randomUUID } from "node:crypto";
 import { resolveConfig } from "@alfe.ai/config";
-import { existsSync } from "node:fs";
 //#region src/outbound-media.ts
 /**
 * Outbound media upload — agent → user.
@@ -209,7 +210,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)}`);
@@ -873,7 +875,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;
@@ -883,7 +885,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(() => {
@@ -2091,27 +2094,214 @@ function loadOpenClawSdk(req, log, anchor) {
 	return resolvedDispatch;
 }
 /**
+* Default `which openclaw` implementation. Prefers the shell's own resolver
+* (`command -v` / `which`), then falls back to scanning `PATH` for an
+* `openclaw` executable. Returns undefined if it can't be located — every
+* caller treats a missing anchor as "skip", never as fatal.
+*/
+function whichOpenClaw(pathEnv) {
+	for (const probe of [{
+		cmd: "command",
+		args: ["-v", "openclaw"]
+	}, {
+		cmd: "which",
+		args: ["openclaw"]
+	}]) try {
+		const out = execFileSync(probe.cmd, probe.args, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim().split("\n")[0]?.trim();
+		if (out) return out;
+	} catch {}
+	for (const dir of (pathEnv ?? "").split(delimiter)) {
+		if (!dir) continue;
+		const candidate = join(dir, "openclaw");
+		try {
+			realpathSync(candidate);
+			return candidate;
+		} catch {}
+	}
+}
+/**
+* Compute the ordered, de-duplicated list of resolver anchors to try, each
+* best-effort `realpath`'d so a bin SYMLINK (e.g. `/opt/homebrew/bin/openclaw`
+* → `../lib/node_modules/openclaw/openclaw.mjs`) resolves to the real module
+* whose `createRequire` CAN find `openclaw/plugin-sdk/*`.
+*
+* Order (proven against homebrew-keg / relocated-node / bin-symlink layouts):
+*   1. require.main?.filename, process.argv[1] — realpath'd (the bin symlink →
+*      real `openclaw.mjs`). argv[1] is often the symlink; realpath is what
+*      makes it a usable anchor.
+*   2. `which openclaw` → realpath — the robust cross-setup anchor. On a
+*      homebrew keg, argv[1] is a symlink under `/opt/homebrew/bin` (no
+*      `node_modules` sibling); its realpath lands in the real
+*      `lib/node_modules/openclaw` tree where resolution succeeds.
+*   3. execPath-derived global-modules path (the original Strategy 2), plus a
+*      realpath'd variant of the execPath prefix for relocated-node layouts.
+*
+* Pure except for the injected `realpath` / `which` seams — unit-tested.
+*/
+function computeOpenClawSdkAnchors(deps) {
+	const anchors = [];
+	const push = (p) => {
+		if (!p) return;
+		let real;
+		try {
+			real = deps.realpath(p);
+		} catch {}
+		for (const candidate of [real, p]) if (candidate && !anchors.includes(candidate)) anchors.push(candidate);
+	};
+	push(deps.requireMainFilename);
+	push(deps.argv1);
+	try {
+		push(deps.which("openclaw"));
+	} catch {}
+	for (const base of [deps.execPath, safeRealpath(deps.realpath, deps.execPath)]) {
+		if (!base) continue;
+		try {
+			const derived = join(resolve(dirname(base), ".."), "lib", "node_modules", "openclaw", "package.json");
+			if (!anchors.includes(derived)) anchors.push(derived);
+		} catch {}
+	}
+	return anchors;
+}
+function safeRealpath(realpath, p) {
+	try {
+		const r = realpath(p);
+		return r === p ? void 0 : r;
+	} catch {
+		return;
+	}
+}
+/**
 * Resolve OpenClaw SDK functions from the running process.
 *
 * The openclaw package is NOT in the plugin's node_modules (it's a peer dep).
 * Since the plugin runs inside OpenClaw's process, we anchor resolution to
-* OpenClaw's own entry module via require.main, then fall back to deriving
-* the global modules path from process.execPath.
+* OpenClaw's own realpath'd entry (surviving bin-symlink / homebrew-keg /
+* relocated-node layouts), then to a `which openclaw` lookup, then fall back to
+* deriving the global modules path from process.execPath.
 */
 function resolveOpenClawSdk(log) {
-	const anchors = [require.main?.filename, process.argv[1]].filter(Boolean);
+	const pathEnv = process.env.PATH;
+	const anchors = computeOpenClawSdkAnchors({
+		realpath: realpathSync,
+		which: () => whichOpenClaw(pathEnv),
+		requireMainFilename: require.main?.filename,
+		argv1: process.argv[1],
+		execPath: process.execPath
+	});
 	for (const anchor of anchors) try {
 		if (loadOpenClawSdk(createRequire(anchor), log, anchor)) return;
 	} catch {}
-	try {
-		const derivedPath = join(resolve(dirname(process.execPath), ".."), "lib", "node_modules", "openclaw", "package.json");
-		if (loadOpenClawSdk(createRequire(derivedPath), log, derivedPath)) return;
-	} catch {}
 	log.warn("OpenClaw SDK not resolvable — chat dispatch will not work");
 }
 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;
@@ -2361,7 +2551,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
@@ -2597,7 +2787,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,
@@ -2710,7 +2900,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)
 		});
@@ -2755,15 +2946,30 @@ const plugin = {
 		}
 		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 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);
 			pluginRuntime = api.runtime ?? null;
-			connectingPromise = Promise.resolve().then(() => {
+			let thisConnect = null;
+			thisConnect = Promise.resolve().then(() => {
 				try {
 					const { apiKey, chatWsUrl } = resolveAlfeChat({
 						apiKey: pluginConfig.apiKey,
@@ -2811,7 +3017,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;
@@ -2863,13 +3072,15 @@ 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)
 				};
 			});
+			api.registerGatewayMethod("runtime.activity", () => Promise.resolve({ active: activeRun !== null }));
 			gw.__alfeChatGatewayMethodsRegistered = true;
-			log.info("Registered gateway RPC methods: sessions.list, sessions.get");
+			log.info("Registered gateway RPC methods: sessions.list, sessions.get, runtime.activity");
 		}
 		api.on("session_start", async (...eventArgs) => {
 			if (!pluginRuntime) return;
@@ -2923,4 +3134,4 @@ const plugin = {
 	}
 };
 //#endregion
-export { __setActiveRunForTest as a, buildOriginEnvelopeContext as c, plugin as d, resolveAbortTargetKeys as f, createAlfeChannelPlugin as h, __resetAgentTurnQueueForTest as i, buildToolActivity as l, stripLeakedToolSummary as m, VOICE_REPLY_SYSTEM_PROMPT as n, admitAgentEvent as o, rewriteAssistantText as p, __agentTurnQueueForTest as r, buildA2ACompletePayload as s, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as t, joinAssistantText 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.3",
+  "version": "0.9.5",
   "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.9.0",
+    "@alfe.ai/agent-api-client": "^0.10.0",
     "@alfe.ai/chat": "^0.0.16",
     "@alfe.ai/config": "^0.3.0"
   },