@alfe.ai/openclaw 0.4.9 → 0.4.11

package/dist/plugin2.js

@@ -1,13 +1,15 @@
 import { createRequire } from "node:module";
-import { extname, join } from "node:path";
-import { readFile } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
-import { createConnection } from "node:net";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
+import { createConnection } from "node:net";
+import { StringDecoder } from "node:string_decoder";
 import { createLogger } from "@auriclabs/logger";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -2787,197 +2789,183 @@ const Type = /* @__PURE__ */ __exportAll({
 //#endregion
 //#region src/types.ts
 function isIPCRequest(msg) {
-	return typeof msg === "object" && msg !== null && msg.type === "req" && typeof msg.id === "string" && typeof msg.method === "string";
+	if (!isRecord$1(msg)) return false;
+	return msg.type === "req" && isBoundedString(msg.id, 128) && isBoundedString(msg.method, 256) && isRecord$1(msg.params);
 }
 function isIPCResponse(msg) {
-	return typeof msg === "object" && msg !== null && typeof msg.id === "string" && typeof msg.ok === "boolean" && !("type" in msg);
+	if (!isRecord$1(msg)) return false;
+	return isBoundedString(msg.id, 128) && typeof msg.ok === "boolean" && !("type" in msg) && (msg.error === void 0 || isIPCError(msg.error));
 }
 function isIPCEvent(msg) {
-	return typeof msg === "object" && msg !== null && msg.type === "event" && typeof msg.event === "string";
+	if (!isRecord$1(msg)) return false;
+	return msg.type === "event" && isBoundedString(msg.event, 256);
+}
+function isIPCError(value) {
+	return isRecord$1(value) && isBoundedString(value.code, 128) && isBoundedString(value.message, 4096);
+}
+function isBoundedString(value, maxLength) {
+	return typeof value === "string" && value.length > 0 && value.length <= maxLength;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /** IPC protocol version — must match daemon's PROTOCOL_VERSION */
 const PROTOCOL_VERSION = 1;
 //#endregion
 //#region src/ipc-client.ts
 /**
-* IPC Client — connects to the Alfe gateway daemon via Unix socket.
-*
-* Protocol: newline-delimited JSON over Unix socket.
-*   Request:  { type: 'req', id, method, params }
-*   Response: { id, ok, payload?, error? }
-*   Event:    { type: 'event', event, payload }
-*
-* Features:
-* - Automatic reconnection with exponential backoff (1s → 30s)
-* - Request/response correlation via message ID
-* - Event emission for incoming daemon events + requests
-* - Graceful handling if daemon not running (warns, retries, doesn't crash)
+* Reconnecting newline-delimited JSON client for the local Alfe gateway.
+* The socket is local, but it is still a bidirectional runtime boundary: both
+* peers cap frames, validate envelopes, and bind callbacks to one connection.
 */
 const MIN_BACKOFF_MS = 1e3;
 const MAX_BACKOFF_MS = 3e4;
 const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+const MAX_REQUEST_TIMEOUT_MS = 12e4;
+const MAX_PENDING_REQUESTS = 128;
+/** Must stay aligned with `packages/gateway/src/protocol.ts`. */
+const MAX_IPC_MESSAGE_BYTES = 1024 * 1024;
 var IPCClient = class extends EventEmitter {
 	socket = null;
-	socketPath;
 	buffer = "";
+	decoder = new StringDecoder("utf8");
 	backoffMs = MIN_BACKOFF_MS;
 	closed = false;
-	_connected = false;
+	isSocketConnected = false;
 	reconnectTimer = null;
 	pending = /* @__PURE__ */ new Map();
-	log = createLogger("IpcClient");
-	constructor(socketPath) {
+	constructor(socketPath, log = createLogger("IpcClient")) {
 		super();
 		this.socketPath = socketPath;
+		this.log = log;
+		if (socketPath.length < 1 || socketPath.length > 4096 || socketPath.includes("\0")) throw new TypeError("IPC socket path must contain 1 to 4096 characters without NUL bytes");
 	}
 	get connected() {
-		return this._connected;
+		return this.isSocketConnected;
 	}
-	/**
-	* Start the IPC connection with auto-reconnect.
-	*/
 	start() {
+		if (this.socket || this.reconnectTimer) return;
 		this.closed = false;
-		this.doConnect();
+		this.openSocket();
 	}
-	/**
-	* Stop the IPC connection and all timers.
-	*/
 	stop() {
 		this.closed = true;
 		this.clearReconnectTimer();
-		for (const [id, pending] of this.pending) {
-			clearTimeout(pending.timer);
-			pending.resolve({
-				id,
-				ok: false,
-				error: {
-					code: "CLIENT_STOPPED",
-					message: "IPC client stopped"
-				}
-			});
-		}
-		this.pending.clear();
-		if (this.socket) {
-			try {
-				this.socket.end();
-			} catch {}
-			this.socket = null;
-		}
-		this._connected = false;
-		this.removeAllListeners();
+		this.resolveAllPending("CLIENT_STOPPED", "IPC client stopped");
+		const socket = this.socket;
+		this.socket = null;
+		this.isSocketConnected = false;
+		this.resetDecoder();
+		if (socket) try {
+			socket.destroy();
+		} catch {}
 	}
-	/**
-	* Send a request to the daemon and wait for a response.
-	*/
 	async request(method, params = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
-		if (!this._connected || !this.socket) return {
-			id: "",
-			ok: false,
-			error: {
-				code: "NOT_CONNECTED",
-				message: "Not connected to daemon"
-			}
-		};
+		if (!this.isSocketConnected || !this.socket) return this.errorResponse("", "NOT_CONNECTED", "Not connected to daemon");
+		if (method.length < 1 || method.length > 256) return this.errorResponse("", "INVALID_REQUEST", "IPC method must contain 1 to 256 characters");
+		const runtimeParams = params;
+		if (typeof runtimeParams !== "object" || runtimeParams === null || Array.isArray(runtimeParams)) return this.errorResponse("", "INVALID_REQUEST", "IPC params must be an object");
+		if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_REQUEST_TIMEOUT_MS) return this.errorResponse("", "INVALID_REQUEST", `IPC timeout must be an integer from 1 to ${String(MAX_REQUEST_TIMEOUT_MS)}ms`);
 		const id = randomUUID();
+		if (this.pending.size >= MAX_PENDING_REQUESTS) return this.errorResponse(id, "TOO_MANY_REQUESTS", "Too many IPC requests are in flight");
 		const request = {
 			type: "req",
 			id,
 			method,
 			params
 		};
+		const frame = this.serializeFrame(request, id);
+		if (typeof frame !== "string") return frame;
+		const socket = this.socket;
 		return new Promise((resolve) => {
 			const timer = setTimeout(() => {
 				this.pending.delete(id);
-				resolve({
-					id,
-					ok: false,
-					error: {
-						code: "TIMEOUT",
-						message: `Request ${method} timed out after ${String(timeoutMs)}ms`
-					}
-				});
+				resolve(this.errorResponse(id, "TIMEOUT", `Request ${method} timed out after ${String(timeoutMs)}ms`));
 			}, timeoutMs);
+			timer.unref();
 			this.pending.set(id, {
 				resolve,
 				timer
 			});
 			try {
-				const socket = this.socket;
-				if (socket) socket.write(JSON.stringify(request) + "\n");
-			} catch (err) {
+				socket.write(frame);
+			} catch (error) {
 				clearTimeout(timer);
 				this.pending.delete(id);
-				resolve({
-					id,
-					ok: false,
-					error: {
-						code: "SEND_FAILED",
-						message: `Failed to send: ${err instanceof Error ? err.message : String(err)}`
-					}
-				});
+				resolve(this.errorResponse(id, "SEND_FAILED", `Failed to send: ${error instanceof Error ? error.message : String(error)}`));
 			}
 		});
 	}
-	/**
-	* Send a response to a daemon request.
-	* Used internally by the request event handler.
-	*/
 	sendResponse(response) {
-		if (!this._connected || !this.socket) return;
+		const socket = this.socket;
+		if (!this.isSocketConnected || !socket) return;
+		if (!isIPCResponse(response)) {
+			this.log.warn("Refusing malformed outgoing IPC response");
+			return;
+		}
+		const frame = this.serializeFrame(response, response.id);
+		if (typeof frame !== "string") {
+			this.log.warn(`Refusing oversized or unserializable IPC response for ${response.id}`);
+			return;
+		}
 		try {
-			this.socket.write(JSON.stringify(response) + "\n");
+			socket.write(frame);
 		} catch {}
 	}
-	doConnect() {
-		if (this.closed) return;
+	openSocket() {
+		if (this.closed || this.socket) return;
+		this.resetDecoder();
 		this.log.debug(`Connecting to daemon at ${this.socketPath}...`);
-		this.socket = createConnection(this.socketPath, () => {
+		const socket = createConnection(this.socketPath, () => {
+			if (this.closed || this.socket !== socket) {
+				socket.destroy();
+				return;
+			}
 			this.log.info(`Connected to daemon (${this.socketPath})`);
-			this._connected = true;
+			this.isSocketConnected = true;
 			this.backoffMs = MIN_BACKOFF_MS;
-			this.buffer = "";
-			this.emit("connected");
+			this.safeEmit("connected");
 		});
-		this.socket.on("data", (data) => {
-			this.buffer += data.toString();
-			this.processBuffer();
+		this.socket = socket;
+		socket.on("data", (data) => {
+			if (this.socket !== socket || this.closed) return;
+			this.buffer += this.decoder.write(data);
+			this.processBuffer(socket);
+			if (Buffer.byteLength(this.buffer, "utf8") > 1048576) this.closeOversized(socket, "unterminated frame");
 		});
-		this.socket.on("close", () => {
-			const wasConnected = this._connected;
-			this._connected = false;
-			for (const [id, pending] of this.pending) {
-				clearTimeout(pending.timer);
-				pending.resolve({
-					id,
-					ok: false,
-					error: {
-						code: "DISCONNECTED",
-						message: "Connection closed"
-					}
-				});
-			}
-			this.pending.clear();
+		socket.on("close", () => {
+			if (this.socket !== socket) return;
+			const wasConnected = this.isSocketConnected;
+			this.socket = null;
+			this.isSocketConnected = false;
+			this.resetDecoder();
+			this.resolveAllPending("DISCONNECTED", "Connection closed");
 			if (wasConnected) {
 				this.log.warn("Disconnected from daemon");
-				this.emit("disconnected", "connection closed");
+				this.safeEmit("disconnected", "connection closed");
 			}
-			this.scheduleReconnect();
+			if (!this.closed) this.scheduleReconnect();
 		});
-		this.socket.on("error", (err) => {
-			if (err.code === "ECONNREFUSED" || err.code === "ENOENT" || err.code === "ECONNRESET") this.log.debug(`Daemon not available: ${err.code}`);
-			else {
-				this.log.error(`IPC socket error: ${err.message}`);
-				this.emit("error", err);
+		socket.on("error", (error) => {
+			if (this.socket !== socket || this.closed) return;
+			if (error.code === "ECONNREFUSED" || error.code === "ENOENT" || error.code === "ECONNRESET") {
+				this.log.debug(`Daemon not available: ${error.code}`);
+				return;
 			}
+			this.log.error(`IPC socket error: ${error.message}`);
+			if (this.listenerCount("error") > 0) this.safeEmit("error", error);
 		});
 	}
-	processBuffer() {
-		let newlineIdx;
-		while ((newlineIdx = this.buffer.indexOf("\n")) !== -1) {
-			const line = this.buffer.slice(0, newlineIdx).trim();
-			this.buffer = this.buffer.slice(newlineIdx + 1);
+	processBuffer(socket) {
+		let newlineIndex;
+		while ((newlineIndex = this.buffer.indexOf("\n")) !== -1) {
+			const line = this.buffer.slice(0, newlineIndex).trim();
+			this.buffer = this.buffer.slice(newlineIndex + 1);
 			if (!line) continue;
+			if (Buffer.byteLength(line, "utf8") > 1048576) {
+				this.closeOversized(socket, "frame");
+				return;
+			}
 			let parsed;
 			try {
 				parsed = JSON.parse(line);
@@ -2985,24 +2973,11 @@ var IPCClient = class extends EventEmitter {
 				this.log.warn("Received invalid JSON from daemon");
 				continue;
 			}
-			if (isIPCResponse(parsed)) {
-				this.handleResponse(parsed);
-				continue;
-			}
-			if (isIPCEvent(parsed)) {
-				if (parsed.event === "plugin.replaced") {
-					this.log.warn("Replaced by another process — stopping reconnection");
-					this.closed = true;
-					this.clearReconnectTimer();
-				}
-				this.emit("event", parsed.event, parsed.payload);
-				continue;
-			}
-			if (isIPCRequest(parsed)) {
-				this.handleIncomingRequest(parsed);
-				continue;
-			}
-			this.log.debug({ msg: parsed }, "Unhandled message from daemon");
+			if (isIPCResponse(parsed)) this.handleResponse(parsed);
+			else if (isIPCEvent(parsed)) this.handleEvent(parsed.event, parsed.payload, socket);
+			else if (isIPCRequest(parsed)) this.handleIncomingRequest(parsed);
+			else this.log.warn("Ignoring malformed IPC envelope");
+			if (this.socket !== socket) return;
 		}
 	}
 	handleResponse(response) {
@@ -3012,37 +2987,117 @@ var IPCClient = class extends EventEmitter {
 		this.pending.delete(response.id);
 		pending.resolve(response);
 	}
+	handleEvent(event, payload, socket) {
+		if (event === "plugin.replaced") {
+			this.log.warn("Replaced by another process — closing this IPC client");
+			this.closed = true;
+			this.clearReconnectTimer();
+		}
+		this.safeEmit("event", event, payload);
+		if (event === "plugin.replaced" && this.socket === socket) socket.destroy();
+	}
 	handleIncomingRequest(request) {
+		let responded = false;
 		const respond = (partial) => {
-			const response = {
+			if (responded) return;
+			responded = true;
+			this.sendResponse({
 				id: request.id,
 				...partial
-			};
-			this.sendResponse(response);
+			});
 		};
-		this.emit("request", request.method, request.params, respond);
+		if (this.listenerCount("request") === 0) {
+			respond({
+				ok: false,
+				error: {
+					code: "UNKNOWN_METHOD",
+					message: `No handler for method: ${request.method}`
+				}
+			});
+			return;
+		}
+		try {
+			this.emit("request", request.method, request.params, respond);
+		} catch (error) {
+			this.log.error(`IPC request handler failed: ${error instanceof Error ? error.message : String(error)}`);
+			respond({
+				ok: false,
+				error: {
+					code: "HANDLER_FAILED",
+					message: "IPC request handler failed"
+				}
+			});
+		}
+	}
+	serializeFrame(value, id) {
+		let frame;
+		try {
+			frame = `${JSON.stringify(value)}\n`;
+		} catch (error) {
+			return this.errorResponse(id, "SERIALIZE_FAILED", error instanceof Error ? error.message : String(error));
+		}
+		if (Buffer.byteLength(frame, "utf8") > 1048576) return this.errorResponse(id, "PAYLOAD_TOO_LARGE", `IPC frame exceeds ${String(MAX_IPC_MESSAGE_BYTES)} bytes`);
+		return frame;
+	}
+	closeOversized(socket, kind) {
+		this.log.warn(`Closing daemon connection after oversized IPC ${kind} (limit ${String(MAX_IPC_MESSAGE_BYTES)} bytes)`);
+		this.resetDecoder();
+		if (this.socket === socket) socket.destroy();
+	}
+	resolveAllPending(code, message) {
+		for (const [id, pending] of this.pending) {
+			clearTimeout(pending.timer);
+			pending.resolve(this.errorResponse(id, code, message));
+		}
+		this.pending.clear();
 	}
 	scheduleReconnect() {
-		if (this.closed) return;
-		this.clearReconnectTimer();
+		if (this.closed || this.reconnectTimer || this.socket) return;
 		const delay = this.backoffMs;
 		this.backoffMs = Math.min(this.backoffMs * 2, MAX_BACKOFF_MS);
 		this.log.debug(`Reconnecting in ${String(delay)}ms...`);
 		this.reconnectTimer = setTimeout(() => {
-			this.doConnect();
+			this.reconnectTimer = null;
+			this.openSocket();
 		}, delay);
 		this.reconnectTimer.unref();
 	}
 	clearReconnectTimer() {
-		if (this.reconnectTimer) {
-			clearTimeout(this.reconnectTimer);
-			this.reconnectTimer = null;
+		if (!this.reconnectTimer) return;
+		clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = null;
+	}
+	resetDecoder() {
+		this.buffer = "";
+		this.decoder = new StringDecoder("utf8");
+	}
+	errorResponse(id, code, message) {
+		return {
+			id,
+			ok: false,
+			error: {
+				code,
+				message
+			}
+		};
+	}
+	safeEmit(event, ...args) {
+		try {
+			this.emit(event, ...args);
+		} catch (error) {
+			this.log.error(`IPC ${event} listener failed: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
 };
 //#endregion
 //#region src/capability-reporter.ts
-const PLUGIN_VERSION = "0.1.0";
+/**
+* Capability Reporter — registers OpenClaw's capabilities with the daemon.
+*
+* On connect (and reconnect), sends a `register` request to the daemon
+* with OpenClaw framework info, plugin version, and capabilities list.
+*/
+const pkg$1 = createRequire(import.meta.url)("../package.json");
 const OPENCLAW_CAPABILITIES = [
 	"sessions",
 	"tools",
@@ -3058,7 +3113,7 @@ async function registerWithDaemon(client, log, pluginName = "@alfe.ai/openclaw")
 	const response = await client.request("register", {
 		framework: "openclaw",
 		name: pluginName,
-		version: PLUGIN_VERSION,
+		version: pkg$1.version,
 		protocolVersion: 1,
 		capabilities: [...OPENCLAW_CAPABILITIES],
 		pid: process.pid
@@ -3071,10 +3126,252 @@ async function registerWithDaemon(client, log, pluginName = "@alfe.ai/openclaw")
 		} else log.error(`Registration failed: ${err?.message ?? "unknown error"}`);
 		return null;
 	}
+	if (!isRegisterResult(response.payload)) {
+		log.error("Registration failed: daemon returned an invalid response");
+		return null;
+	}
 	const result = response.payload;
 	log.info(`Registered with daemon v${result.daemonVersion} (protocol v${String(result.protocolVersion)})`);
 	return result;
 }
+function isRegisterResult(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const result = value;
+	return typeof result.status === "string" && result.status.length > 0 && result.status.length <= 128 && typeof result.daemonVersion === "string" && result.daemonVersion.length > 0 && result.daemonVersion.length <= 128 && Number.isSafeInteger(result.protocolVersion) && result.protocolVersion > 0;
+}
+//#endregion
+//#region src/avatar-source.ts
+/** Safe local/remote avatar loading for the `set_avatar` tool. */
+const MAX_AVATAR_BYTES = 5 * 1024 * 1024;
+const MAX_AVATAR_URL_LENGTH = 2048;
+const MAX_LOCAL_PATH_LENGTH = 4096;
+const AVATAR_DOWNLOAD_TIMEOUT_MS = 3e4;
+const AVATAR_MIME_BY_EXT = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp"
+};
+function deriveAgentAssetsOrigin(apiUrl) {
+	const api = new URL(apiUrl);
+	if (api.protocol !== "https:" || api.username || api.password || !api.hostname.startsWith("api.")) throw new Error("Cannot derive a trusted agent-assets origin from the configured API URL");
+	api.hostname = api.hostname.replace(/^api\./u, "assets.");
+	api.pathname = "/";
+	api.search = "";
+	api.hash = "";
+	return api.origin;
+}
+async function loadAvatarSource(input, options) {
+	if (input.url !== void 0 === (input.path !== void 0)) throw new Error("Provide exactly one of url or path");
+	if (input.url !== void 0) return loadRemoteAvatar(input.url, options.agentAssetsOrigin, options.fetchImpl ?? fetch);
+	return loadWorkspaceAvatar(input.path ?? "", options.workspacePath);
+}
+function assertPresignedS3UploadUrl(rawUrl) {
+	if (rawUrl.length < 1 || rawUrl.length > MAX_AVATAR_URL_LENGTH) throw new Error("Avatar upload URL is invalid");
+	const url = new URL(rawUrl);
+	if (url.protocol !== "https:" || url.username || url.password || !(url.hostname === "amazonaws.com" || url.hostname.endsWith(".amazonaws.com"))) throw new Error("Avatar upload URL is not a trusted S3 endpoint");
+	return url.href;
+}
+async function loadRemoteAvatar(rawUrl, agentAssetsOrigin, fetchImpl) {
+	if (rawUrl.length < 1 || rawUrl.length > MAX_AVATAR_URL_LENGTH) throw new Error("Avatar URL must contain 1 to 2048 characters");
+	const url = new URL(rawUrl);
+	if (url.protocol !== "https:" || url.username || url.password || url.origin !== agentAssetsOrigin) throw new Error(`Avatar URL must use the trusted agent-assets origin ${agentAssetsOrigin}`);
+	if (!url.pathname.startsWith("/generated/") && !url.pathname.startsWith("/avatars/")) throw new Error("Avatar URL must reference a generated or uploaded agent asset");
+	const response = await fetchImpl(url, {
+		redirect: "error",
+		signal: AbortSignal.timeout(AVATAR_DOWNLOAD_TIMEOUT_MS)
+	});
+	if (!response.ok) throw new Error(`Failed to download the avatar image (${String(response.status)})`);
+	const declaredLength = response.headers.get("content-length");
+	if (declaredLength !== null) {
+		const bytes = Number(declaredLength);
+		if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > 5242880) throw new Error(`Avatar response exceeds the ${String(MAX_AVATAR_BYTES)} byte limit`);
+	}
+	const mimeType = avatarMime(url.pathname, response.headers.get("content-type"));
+	const bytes = await readResponseBytes(response, MAX_AVATAR_BYTES);
+	assertImageSignature(bytes, mimeType);
+	return {
+		bytes,
+		mimeType
+	};
+}
+async function loadWorkspaceAvatar(rawPath, workspacePath) {
+	if (rawPath.length < 1 || rawPath.length > MAX_LOCAL_PATH_LENGTH || isAbsolute(rawPath)) throw new Error("Avatar path must be a workspace-relative path of at most 4096 characters");
+	if (rawPath.includes("\0")) throw new Error("Avatar path contains an invalid character");
+	let workspace;
+	try {
+		workspace = await realpath(workspacePath);
+	} catch {
+		throw new Error("Avatar workspace is unavailable");
+	}
+	const candidate = resolve(workspace, rawPath);
+	if (!isWithin(workspace, candidate)) throw new Error("Avatar path resolves outside the workspace");
+	let fileInfo;
+	try {
+		fileInfo = await lstat(candidate);
+	} catch {
+		throw new Error("Avatar file does not exist or cannot be accessed");
+	}
+	if (fileInfo.isSymbolicLink() || !fileInfo.isFile()) throw new Error("Avatar path must reference a regular non-symlink file");
+	let canonical;
+	try {
+		canonical = await realpath(candidate);
+	} catch {
+		throw new Error("Avatar file does not exist or cannot be accessed");
+	}
+	if (!isWithin(workspace, canonical)) throw new Error("Avatar path resolves outside the workspace");
+	const mimeType = avatarMime(canonical, null);
+	const handle = await open(canonical, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const opened = await handle.stat();
+		if (!opened.isFile() || opened.size < 1 || opened.size > 5242880) throw new Error(`Avatar file must contain 1 to ${String(MAX_AVATAR_BYTES)} bytes`);
+		const target = Buffer.allocUnsafe(MAX_AVATAR_BYTES + 1);
+		let offset = 0;
+		while (offset <= MAX_AVATAR_BYTES) {
+			const { bytesRead } = await handle.read(target, offset, target.length - offset, offset);
+			if (bytesRead === 0) break;
+			offset += bytesRead;
+		}
+		if (offset < 1 || offset > 5242880) throw new Error(`Avatar file must contain 1 to ${String(MAX_AVATAR_BYTES)} bytes`);
+		const bytes = Buffer.from(target.subarray(0, offset));
+		assertImageSignature(bytes, mimeType);
+		return {
+			bytes,
+			mimeType
+		};
+	} finally {
+		await handle.close();
+	}
+}
+async function readResponseBytes(response, maxBytes) {
+	if (!response.body) throw new Error("Avatar response had no body");
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel("avatar exceeds size limit");
+				throw new Error(`Avatar response exceeds the ${String(maxBytes)} byte limit`);
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	if (total < 1) throw new Error("Avatar response was empty");
+	return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+}
+function avatarMime(pathname, contentType) {
+	const normalizedType = (contentType ?? "").split(";", 1)[0]?.trim().toLowerCase();
+	if (normalizedType === "image/png" || normalizedType === "image/jpeg" || normalizedType === "image/webp") return normalizedType;
+	const fromExtension = AVATAR_MIME_BY_EXT[extname(pathname).toLowerCase()];
+	if (fromExtension) return fromExtension;
+	throw new Error("Avatar image must be PNG, JPEG, or WebP");
+}
+function assertImageSignature(bytes, mimeType) {
+	if (!(mimeType === "image/png" && bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	])) || mimeType === "image/jpeg" && bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255 || mimeType === "image/webp" && bytes.length >= 12 && bytes.subarray(0, 4).toString("ascii") === "RIFF" && bytes.subarray(8, 12).toString("ascii") === "WEBP")) throw new Error(`Avatar bytes do not match the declared ${mimeType} image type`);
+}
+function isWithin(root, candidate) {
+	const rel = relative(root, candidate);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+//#endregion
+//#region src/tool-input.ts
+/** Runtime validation for model-controlled OpenClaw tool parameters. */
+const MAX_JSON_DEPTH = 8;
+const MAX_JSON_NODES = 1e4;
+const MAX_RECORD_ENTRIES = 1e3;
+const MAX_RECORD_KEY_LENGTH = 256;
+const MAX_RECORD_STRING_LENGTH = 1e4;
+const MAX_JSON_BYTES = 1024 * 1024;
+const UNSAFE_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function requireString(params, field, maxLength, pattern) {
+	const value = params[field];
+	if (typeof value !== "string" || value.length < 1 || value.length > maxLength) throw new Error(`${field} must contain 1 to ${String(maxLength)} characters`);
+	if (pattern && !pattern.test(value)) throw new Error(`${field} has an invalid format`);
+	return value;
+}
+function optionalString(params, field, maxLength) {
+	if (params[field] === void 0) return void 0;
+	return requireString(params, field, maxLength);
+}
+function requireConfirmation(params, message) {
+	if (params.confirm !== true) throw new Error(message);
+}
+function requireMatchingConfirmation(params, field, expected) {
+	if (params[field] !== expected) throw new Error(`${field} must exactly match ${expected}`);
+}
+function optionalJsonRecord(params, field) {
+	if (params[field] === void 0) return void 0;
+	return requireJsonRecord(params, field);
+}
+function requireJsonRecord(params, field) {
+	const state = {
+		nodes: 0,
+		ancestors: /* @__PURE__ */ new Set()
+	};
+	const cloned = cloneJson(params[field], field, 0, state);
+	if (!isRecord(cloned)) throw new Error(`${field} must be an object`);
+	const serialized = JSON.stringify(cloned);
+	if (Buffer.byteLength(serialized, "utf8") > MAX_JSON_BYTES) throw new Error(`${field} exceeds the ${String(MAX_JSON_BYTES)} byte limit`);
+	return cloned;
+}
+function cloneJson(value, label, depth, state) {
+	state.nodes += 1;
+	if (state.nodes > MAX_JSON_NODES) throw new Error(`${label} contains too many values`);
+	if (depth > MAX_JSON_DEPTH) throw new Error(`${label} exceeds ${String(MAX_JSON_DEPTH)} nesting levels`);
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite number`);
+		return value;
+	}
+	if (typeof value === "string") {
+		if (value.length > MAX_RECORD_STRING_LENGTH) throw new Error(`${label} contains a string longer than ${String(MAX_RECORD_STRING_LENGTH)} characters`);
+		return value;
+	}
+	if (typeof value !== "object") throw new Error(`${label} must contain only JSON values`);
+	if (state.ancestors.has(value)) throw new Error(`${label} must not contain cycles`);
+	state.ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			if (value.length > MAX_RECORD_ENTRIES) throw new Error(`${label} contains too many entries`);
+			return value.map((entry) => cloneJson(entry, label, depth + 1, state));
+		}
+		if (!isRecord(value)) throw new Error(`${label} must contain only plain objects`);
+		const entries = Object.entries(value);
+		if (entries.length > MAX_RECORD_ENTRIES) throw new Error(`${label} contains too many entries`);
+		const output = Object.create(null);
+		for (const [key, entry] of entries) {
+			if (key.length < 1 || key.length > MAX_RECORD_KEY_LENGTH || UNSAFE_KEYS.has(key)) throw new Error(`${label} contains an invalid key`);
+			output[key] = cloneJson(entry, label, depth + 1, state);
+		}
+		return output;
+	} finally {
+		state.ancestors.delete(value);
+	}
+}
+function isRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
 //#endregion
 //#region src/plugin.ts
 /**
@@ -3086,44 +3383,11 @@ async function registerWithDaemon(client, log, pluginName = "@alfe.ai/openclaw")
 * 3. Re-registers on reconnect (daemon may restart)
 * 4. Gracefully handles daemon being unavailable
 *
-* Follows the same plugin pattern as @alfe.ai/openclaw-voice.
 */
 const pkg = createRequire(import.meta.url)("../package.json");
 const DEFAULT_SOCKET_PATH = join(homedir(), ".alfe", "gateway.sock");
 let ipcClient = null;
-/** Max avatar upload size — mirrors the server-side finalize check. */
-const MAX_AVATAR_BYTES = 5 * 1024 * 1024;
-/** Image types the avatar presign/finalize flow accepts, keyed by file extension. */
-const AVATAR_MIME_BY_EXT = {
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".webp": "image/webp"
-};
-/** Infer an avatar mime type from a file path, rejecting unsupported types. */
-function avatarMimeFromPath(path) {
-	const ext = extname(path).toLowerCase();
-	const mimeType = AVATAR_MIME_BY_EXT[ext];
-	if (!mimeType) throw new Error(`unsupported image type "${ext || path}" — set_avatar accepts .png, .jpg/.jpeg, or .webp`);
-	return mimeType;
-}
-/**
-* Infer an avatar mime type for a remote image — prefer the response's
-* Content-Type, else the URL path extension. Lets `set_avatar` accept a URL
-* (e.g. the one `generate_image` returns), which is how an agent naturally
-* wants to set the picture it just generated.
-*/
-function avatarMimeFromUrl(url, contentType) {
-	const ct = (contentType ?? "").split(";")[0].trim().toLowerCase();
-	if (ct === "image/png" || ct === "image/jpeg" || ct === "image/webp") return ct;
-	let pathname = url;
-	try {
-		pathname = new URL(url).pathname;
-	} catch {}
-	const byExt = AVATAR_MIME_BY_EXT[extname(pathname).toLowerCase()];
-	if (byExt) return byExt;
-	throw new Error(`could not determine the image type for "${url}" — set_avatar accepts png, jpeg, or webp`);
-}
+let ipcOwner = null;
 function ok(result) {
 	return { content: [{
 		type: "text",
@@ -3153,7 +3417,7 @@ function defineTool(def) {
 			try {
 				return ok(await def.handler(params));
 			} catch (e) {
-				return errResult(e.message);
+				return errResult(e instanceof Error ? e.message : "Unknown error");
 			}
 		}
 	};
@@ -3163,15 +3427,19 @@ function buildIntegrationTools(client) {
 		defineTool({
 			name: "list_integrations",
 			description: "List all integrations installed for this agent, including their status and available config fields.",
-			parameters: Type.Object({}),
+			parameters: Type.Object({}, { additionalProperties: false }),
 			handler: async () => client.listIntegrations()
 		}),
 		defineTool({
 			name: "get_integration_config",
 			description: "Get the current configuration and editable fields for a specific integration.",
-			parameters: Type.Object({ integrationId: Type.String({ description: "The integration to inspect (e.g. \"voice\", \"slack\")" }) }),
+			parameters: Type.Object({ integrationId: Type.String({
+				description: "The integration to inspect (e.g. \"voice\", \"slack\")",
+				minLength: 1,
+				maxLength: 256
+			}) }, { additionalProperties: false }),
 			handler: async (params) => {
-				const integrationId = params.integrationId;
+				const integrationId = requireString(params, "integrationId", 256);
 				return client.getIntegrationConfig(integrationId);
 			}
 		}),
@@ -3179,27 +3447,53 @@ function buildIntegrationTools(client) {
 			name: "update_integration_config",
 			description: "Update configuration for an installed integration. Only agent-editable fields can be changed.",
 			parameters: Type.Object({
-				integrationId: Type.String({ description: "The integration to update" }),
-				fields: Type.Record(Type.String(), Type.Unknown(), { description: "Key-value pairs of config fields to update" })
-			}),
+				integrationId: Type.String({
+					description: "The integration to update",
+					minLength: 1,
+					maxLength: 256
+				}),
+				fields: Type.Record(Type.String({
+					minLength: 1,
+					maxLength: 256
+				}), Type.Unknown(), {
+					description: "Key-value pairs of config fields to update",
+					maxProperties: 1e3
+				})
+			}, { additionalProperties: false }),
 			handler: async (params) => {
-				const integrationId = params.integrationId;
-				const fields = params.fields;
+				const integrationId = requireString(params, "integrationId", 256);
+				const fields = requireJsonRecord(params, "fields");
 				return client.updateIntegrationConfig(integrationId, fields);
 			}
 		}),
 		defineTool({
 			name: "install_integration",
-			description: "Install an integration from the registry. Returns the newly created integration record.",
+			description: "Install an integration from the registry. This changes the agent runtime and may run integration lifecycle hooks. Set confirm=true only after the user approves the install.",
 			parameters: Type.Object({
-				integrationId: Type.String({ description: "The integration to install (e.g. \"voice\", \"slack\", \"discord\")" }),
-				version: Type.Optional(Type.String({ description: "Specific version to install (defaults to latest)" })),
-				config: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Initial configuration key-value pairs" }))
-			}),
+				integrationId: Type.String({
+					description: "The integration to install (e.g. \"voice\", \"slack\", \"discord\")",
+					minLength: 1,
+					maxLength: 256
+				}),
+				version: Type.Optional(Type.String({
+					description: "Specific version to install (defaults to latest)",
+					minLength: 1,
+					maxLength: 64
+				})),
+				config: Type.Optional(Type.Record(Type.String({
+					minLength: 1,
+					maxLength: 256
+				}), Type.Unknown(), {
+					description: "Initial configuration key-value pairs",
+					maxProperties: 1e3
+				})),
+				confirm: Type.Literal(true, { description: "Must be true after the user explicitly approves the integration install" })
+			}, { additionalProperties: false }),
 			handler: async (params) => {
-				const integrationId = params.integrationId;
-				const version = params.version;
-				const config = params.config;
+				const integrationId = requireString(params, "integrationId", 256);
+				const version = optionalString(params, "version", 64);
+				const config = optionalJsonRecord(params, "config");
+				requireConfirmation(params, "confirm must be true after the user explicitly approves the integration install");
 				return client.installIntegration(integrationId, {
 					version,
 					config
@@ -3208,27 +3502,39 @@ function buildIntegrationTools(client) {
 		}),
 		defineTool({
 			name: "remove_integration",
-			description: "Remove an installed integration. The daemon will handle teardown during reconciliation.",
-			parameters: Type.Object({ integrationId: Type.String({ description: "The integration to remove" }) }),
+			description: "Remove an installed integration. The daemon will tear down its runtime resources during reconciliation. Copy the exact id into confirmIntegrationId after the user approves.",
+			parameters: Type.Object({
+				integrationId: Type.String({
+					description: "The integration to remove",
+					minLength: 1,
+					maxLength: 256
+				}),
+				confirmIntegrationId: Type.String({
+					description: "Exact integration id copied to confirm removal",
+					minLength: 1,
+					maxLength: 256
+				})
+			}, { additionalProperties: false }),
 			handler: async (params) => {
-				const integrationId = params.integrationId;
+				const integrationId = requireString(params, "integrationId", 256);
+				requireMatchingConfirmation(params, "confirmIntegrationId", integrationId);
 				return client.removeIntegration(integrationId);
 			}
 		}),
 		defineTool({
 			name: "browse_integration_registry",
 			description: "Browse available integrations in the registry. Shows all integrations that can be installed.",
-			parameters: Type.Object({}),
+			parameters: Type.Object({}, { additionalProperties: false }),
 			handler: async () => client.getRegistry()
 		})
 	];
 }
-function buildVoiceTools(client) {
+function buildVoiceTools(client, options) {
 	return [
 		defineTool({
 			name: "list_voices",
 			description: "List the available voices this agent can speak with (the ElevenLabs catalogue). Use this to pick or confirm a voice before calling set_voice with the chosen id.",
-			parameters: Type.Object({}),
+			parameters: Type.Object({}, { additionalProperties: false }),
 			handler: async () => {
 				const { voices } = await client.listVoices();
 				return { voices: voices.map((v) => ({
@@ -3244,9 +3550,14 @@ function buildVoiceTools(client) {
 		defineTool({
 			name: "set_voice",
 			description: "Change this agent's OWN voice. Pass a `voiceId` from list_voices. Returns the updated voice config. (Voice is always on — it cannot be turned off per-agent.)",
-			parameters: Type.Object({ voiceId: Type.String({ description: "The ElevenLabs voice id to use, from list_voices (e.g. the `id` field)." }) }),
+			parameters: Type.Object({ voiceId: Type.String({
+				description: "The ElevenLabs voice id to use, from list_voices (e.g. the `id` field).",
+				minLength: 8,
+				maxLength: 64,
+				pattern: "^[A-Za-z0-9]{8,64}$"
+			}) }, { additionalProperties: false }),
 			handler: async (params) => {
-				const voiceId = params.voiceId;
+				const voiceId = requireString(params, "voiceId", 64, /^[A-Za-z0-9]{8,64}$/u);
 				return {
 					updated: true,
 					voiceConfig: (await client.updateSelf({ voiceConfig: { voiceId } })).voiceConfig
@@ -3256,9 +3567,13 @@ function buildVoiceTools(client) {
 		defineTool({
 			name: "generate_avatar",
 			description: "Generate and set THIS agent's own profile picture / avatar from a text prompt (e.g. a character description). Updates the agent's real profile picture shown in the dashboard, chat, and apps. Use this — do NOT use `config set ui.assistant.avatar`, which has no effect on the real profile.",
-			parameters: Type.Object({ prompt: Type.String({ description: "Text description of the avatar to generate (e.g. a character or portrait description)." }) }),
+			parameters: Type.Object({ prompt: Type.String({
+				description: "Text description of the avatar to generate (e.g. a character or portrait description).",
+				minLength: 1,
+				maxLength: 2e3
+			}) }, { additionalProperties: false }),
 			handler: async (params) => {
-				const prompt = params.prompt;
+				const prompt = requireString(params, "prompt", 2e3);
 				return {
 					updated: true,
 					avatarUrl: (await client.generateAvatar({ prompt })).avatarUrl,
@@ -3268,34 +3583,40 @@ function buildVoiceTools(client) {
 		}),
 		defineTool({
 			name: "set_avatar",
-			description: "Set THIS agent's OWN profile picture from an image — pass a `url` (e.g. the URL returned by `generate_image`) OR a local file `path` you created/downloaded (png/jpeg/webp, <=5MB). Updates the real profile picture shown in the dashboard, chat, and apps. IMPORTANT: this is how you set YOUR OWN avatar — do NOT use `update_identity` (that edits a CONTACT/person you know, not your own profile) and do NOT use `config set ui.assistant.avatar` (no effect).",
+			description: "Set THIS agent's OWN profile picture from an image — pass an Alfe agent-assets `url` (e.g. the URL returned by `generate_image`) OR a workspace-relative local `path` (png/jpeg/webp, <=5MB). Updates the real profile picture shown in the dashboard, chat, and apps. IMPORTANT: this is how you set YOUR OWN avatar — do NOT use `update_identity` (that edits a CONTACT/person you know, not your own profile) and do NOT use `config set ui.assistant.avatar` (no effect).",
 			parameters: Type.Object({
-				url: Type.Optional(Type.String({ description: "URL of an image to use as the avatar — e.g. the `url` returned by `generate_image`. png/jpeg/webp, <=5MB." })),
-				path: Type.Optional(Type.String({ description: "Absolute path to a LOCAL image file (.png, .jpg/.jpeg, or .webp, <=5MB). Use `url` instead if you have a URL." }))
-			}),
+				url: Type.Optional(Type.String({
+					description: "Trusted Alfe agent-assets URL — e.g. the `url` returned by `generate_image`. png/jpeg/webp, <=5MB.",
+					minLength: 1,
+					maxLength: 2048,
+					pattern: "^https://"
+				})),
+				path: Type.Optional(Type.String({
+					description: "Workspace-relative path to a local image file (.png, .jpg/.jpeg, or .webp, <=5MB).",
+					minLength: 1,
+					maxLength: 4096
+				}))
+			}, { additionalProperties: false }),
 			handler: async (params) => {
-				const url = params.url;
-				const path = params.path;
-				let bytes;
-				let mimeType;
-				if (url) {
-					const dl = await fetch(url);
-					if (!dl.ok) throw new Error(`failed to download the image from the url (${String(dl.status)})`);
-					bytes = Buffer.from(await dl.arrayBuffer());
-					mimeType = avatarMimeFromUrl(url, dl.headers.get("content-type"));
-				} else if (path) {
-					mimeType = avatarMimeFromPath(path);
-					bytes = await readFile(path);
-				} else throw new Error("provide either `url` (an image URL, e.g. from generate_image) or `path` (a local image file)");
-				if (bytes.length > MAX_AVATAR_BYTES) throw new Error(`image is ${String(bytes.length)} bytes — the avatar limit is ${String(MAX_AVATAR_BYTES)} bytes (5MB)`);
+				const { bytes, mimeType } = await loadAvatarSource({
+					url: optionalString(params, "url", 2048),
+					path: optionalString(params, "path", 4096)
+				}, {
+					workspacePath: options.workspacePath,
+					agentAssetsOrigin: options.agentAssetsOrigin
+				});
 				const { uploadUrl, s3Key } = await client.presignAvatar({
 					mimeType,
 					size: bytes.length
 				});
-				const putRes = await fetch(uploadUrl, {
+				const trustedUploadUrl = assertPresignedS3UploadUrl(uploadUrl);
+				if (typeof s3Key !== "string" || s3Key.length < 1 || s3Key.length > 1024 || !s3Key.startsWith("avatars/")) throw new Error("Avatar presign returned an invalid object key");
+				const putRes = await fetch(trustedUploadUrl, {
 					method: "PUT",
 					headers: { "Content-Type": mimeType },
-					body: new Uint8Array(bytes)
+					body: new Uint8Array(bytes),
+					redirect: "error",
+					signal: AbortSignal.timeout(3e4)
 				});
 				if (!putRes.ok) throw new Error(`failed to upload the avatar image (${String(putRes.status)})`);
 				return {
@@ -3307,19 +3628,35 @@ function buildVoiceTools(client) {
 		}),
 		defineTool({
 			name: "generate_image",
-			description: "Generate an image from a text prompt. Returns a URL to the generated PNG. To show the image to the user, embed it in your reply as markdown: ![description](imageUrl). To set the generated image as YOUR OWN profile picture, pass its url to `set_avatar` (NOT update_identity, which edits other people you know). Or skip this and use `generate_avatar` to generate + set your avatar in one step. Optional `model` picks the image model (default gpt-image-1). Generation is synchronous and may take up to ~30s; if it times out, retry or use a standard size.",
+			description: "Generate an image from a text prompt. Returns a URL to the generated image. To show the image to the user, embed it in your reply as markdown: ![description](imageUrl). To set the generated image as YOUR OWN profile picture, pass its url to `set_avatar` (NOT update_identity, which edits other people you know). Or skip this and use `generate_avatar` to generate + set your avatar in one step. Optional `model` picks the image model (default gpt-image-1). Generation is queued server-side while this tool polls for completion and may take up to three minutes; if it times out, retry or use a standard size.",
 			parameters: Type.Object({
-				prompt: Type.String({ description: "Text description of the image to generate." }),
-				model: Type.Optional(Type.String({ description: "Image model id (default \"gpt-image-1\"). Others may be available, e.g. dall-e-3." })),
-				size: Type.Optional(Type.String({ description: "Image size. For the default gpt-image-1 use one of \"1024x1024\" (square), \"1536x1024\" (landscape), \"1024x1536\" (portrait), or \"auto\" — NOT \"512x512\". Other models accept their own sizes. Omit to use the provider default." })),
-				quality: Type.Optional(Type.String({ description: "Image quality hint (provider-dependent)." }))
-			}),
+				prompt: Type.String({
+					description: "Text description of the image to generate.",
+					minLength: 1,
+					maxLength: 4e3
+				}),
+				model: Type.Optional(Type.String({
+					description: "Image model id (default \"gpt-image-1\"). Others may be available, e.g. dall-e-3.",
+					minLength: 1,
+					maxLength: 100
+				})),
+				size: Type.Optional(Type.String({
+					description: "Image size. For the default gpt-image-1 use one of \"1024x1024\" (square), \"1536x1024\" (landscape), \"1024x1536\" (portrait), or \"auto\" — NOT \"512x512\". Other models accept their own sizes. Omit to use the provider default.",
+					minLength: 1,
+					maxLength: 32
+				})),
+				quality: Type.Optional(Type.String({
+					description: "Image quality hint (provider-dependent).",
+					minLength: 1,
+					maxLength: 32
+				}))
+			}, { additionalProperties: false }),
 			handler: async (params) => {
 				const { imageUrl, model } = await client.generateImage({
-					prompt: params.prompt,
-					model: params.model,
-					size: params.size,
-					quality: params.quality
+					prompt: requireString(params, "prompt", 4e3),
+					model: optionalString(params, "model", 100),
+					size: optionalString(params, "size", 32),
+					quality: optionalString(params, "quality", 32)
 				});
 				return {
 					imageUrl,
@@ -3342,42 +3679,59 @@ const plugin = {
 		try {
 			cfg = resolveConfig();
 		} catch (err) {
-			log.warn(`Integration tools not registered — config not available: ${err.message}`);
+			log.warn(`Integration tools not registered — config not available: ${err instanceof Error ? err.message : "unknown error"}`);
 		}
 		if (cfg) {
 			const client = new AgentApiClient({
 				apiKey: cfg.apiKey,
 				apiUrl: cfg.apiUrl
 			});
-			const tools = [...buildIntegrationTools(client), ...buildVoiceTools(client)];
+			let agentAssetsOrigin = "https://assets.invalid";
+			try {
+				agentAssetsOrigin = deriveAgentAssetsOrigin(cfg.apiUrl);
+			} catch {
+				log.warn("Remote set_avatar URLs are unavailable for this API configuration");
+			}
+			const tools = [...buildIntegrationTools(client), ...buildVoiceTools(client, {
+				workspacePath: cfg.workspacePath,
+				agentAssetsOrigin
+			})];
 			for (const tool of tools) api.registerTool(tool);
 			log.info(`Registered ${String(tools.length)} agent tools: ${tools.map((t) => t.name).join(", ")}`);
 		}
+		const serviceOwner = Symbol("alfe-daemon-ipc-owner");
 		const startDaemonIpc = () => {
 			if (globalThis.__alfeOpenclawPluginActivated === true) {
 				log.debug("Alfe OpenClaw Plugin already activated — skipping duplicate");
 				return;
 			}
 			globalThis.__alfeOpenclawPluginActivated = true;
+			ipcOwner = serviceOwner;
 			if (ipcClient) {
 				log.warn("Stopping stale IPC client from prior activation");
 				ipcClient.stop();
 				ipcClient = null;
 			}
 			log.info("Alfe OpenClaw Plugin activating...");
-			const socketPath = ((api.config ?? {}).plugins?.entries?.["@alfe.ai/openclaw"]?.config ?? {}).socketPath ?? process.env.ALFE_GATEWAY_SOCKET ?? DEFAULT_SOCKET_PATH;
-			ipcClient = new IPCClient(socketPath);
+			const configuredSocketPath = ((api.config ?? {}).plugins?.entries?.["@alfe.ai/openclaw"]?.config ?? {}).socketPath ?? process.env.ALFE_GATEWAY_SOCKET ?? DEFAULT_SOCKET_PATH;
+			if (typeof configuredSocketPath !== "string" || configuredSocketPath.length < 1 || configuredSocketPath.length > 4096 || configuredSocketPath.includes("\0")) {
+				ipcOwner = null;
+				globalThis.__alfeOpenclawPluginActivated = false;
+				throw new Error("Invalid Alfe gateway socket path");
+			}
+			const socketPath = configuredSocketPath;
+			ipcClient = new IPCClient(socketPath, log);
 			ipcClient.on("event", (event, payload) => {
 				switch (event) {
 					case "cloud.status": {
-						const status = payload;
-						log.info(`Alfe cloud: ${status.connected ? "connected" : "disconnected"}`);
+						const connected = typeof payload === "object" && payload !== null && !Array.isArray(payload) && payload.connected === true;
+						log.info(`Alfe cloud: ${connected ? "connected" : "disconnected"}`);
 						break;
 					}
 					case "daemon.shutdown":
 						log.info("Daemon shutting down — will reconnect when available");
 						break;
-					default: log.debug(`Daemon event: ${event}`, payload);
+					default: log.debug(`Daemon event: ${event}`);
 				}
 			});
 			ipcClient.on("request", (method, _params, respond) => {
@@ -3394,7 +3748,9 @@ const plugin = {
 			ipcClient.on("connected", () => {
 				log.info("Connected to Alfe daemon — registering capabilities...");
 				registerWithDaemon(ipc, log, plugin.id).then((result) => {
-					if (!result) log.error("Failed to register with daemon — commands may not be routed");
+					if (ipcClient === ipc && ipcOwner === serviceOwner && !result) log.error("Failed to register with daemon — commands may not be routed");
+				}).catch((error) => {
+					if (ipcClient === ipc && ipcOwner === serviceOwner) log.error(`Capability registration failed: ${error instanceof Error ? error.message : String(error)}`);
 				});
 			});
 			ipcClient.on("disconnected", (reason) => {
@@ -3403,15 +3759,28 @@ const plugin = {
 			ipcClient.on("error", (err) => {
 				log.error(`IPC error: ${err.message}`);
 			});
-			ipcClient.start();
+			try {
+				ipcClient.start();
+			} catch (error) {
+				ipcClient.stop();
+				ipcClient = null;
+				ipcOwner = null;
+				globalThis.__alfeOpenclawPluginActivated = false;
+				throw error;
+			}
 			log.info(`Alfe OpenClaw Plugin activated (socket: ${socketPath})`);
 		};
 		const stopDaemonIpc = () => {
+			if (ipcOwner !== serviceOwner) {
+				log.debug("Ignoring stop from a non-owning Alfe IPC service registration");
+				return;
+			}
 			log.info("Alfe OpenClaw Plugin deactivating...");
 			if (ipcClient) {
 				ipcClient.stop();
 				ipcClient = null;
 			}
+			ipcOwner = null;
 			globalThis.__alfeOpenclawPluginActivated = false;
 			log.info("Alfe OpenClaw Plugin deactivated");
 		};
@@ -3431,9 +3800,10 @@ const plugin = {
 			log.info("Alfe OpenClaw Plugin deactivating (legacy)...");
 			ipcClient.stop();
 			ipcClient = null;
-			globalThis.__alfeOpenclawPluginActivated = false;
 			log.info("Alfe OpenClaw Plugin deactivated");
 		}
+		ipcOwner = null;
+		globalThis.__alfeOpenclawPluginActivated = false;
 	}
 };
 //#endregion