@alfe.ai/openclaw-chat 0.6.1 → 0.8.0

package/dist/plugin2.js

@@ -1,10 +1,349 @@
 import { createRequire } from "node:module";
 import { mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { ChatServiceClient, resolveAlfeChat } from "@alfe.ai/chat";
 import { randomUUID } from "node:crypto";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { resolveConfig } from "@alfe.ai/config";
 import { existsSync } from "node:fs";
+//#region src/outbound-media.ts
+/**
+* Outbound media upload — agent → user.
+*
+* OpenClaw approves LOCAL file paths in outbound media (`MEDIA:` tokens →
+* `payload.mediaUrl(s)`, and inline markdown images which the runtime never
+* extracts for this channel). Forwarding those strings verbatim ships a VM
+* path to the browser, which resolves it against the chat origin → broken
+* image. This module uploads local refs to S3 through the EXISTING chat
+* attachment machinery (`AgentApiClient.presignAttachments` →
+* `POST /agent/chat/attachments/presign` → presigned PUT) and hands back
+* hosted download URLs plus rich metadata.
+*
+* Key constraints (all load-bearing):
+* - `deliver` fires PER STREAMING BLOCK plus a terminal frame, so the same
+*   media ref recurs within one turn. Every resolution goes through a
+*   per-turn `OutboundMediaContext` cache — one presign+PUT per distinct
+*   path per turn, failures cached too, failure annotations emitted once.
+* - The upload runs inside the per-agent single-flight turn queue; an
+*   unbounded PUT would head-of-line block every later turn. Every PUT is
+*   bounded by an AbortController timeout.
+* - The size cap mirrors the presign endpoint's 25 MB / 10-files limits —
+*   NOT the plugin's 50 MB inbound download cap — so oversize files fail
+*   fast locally instead of as an opaque presign 400.
+* - The presigned PUT is signed with `ContentType`; the raw fetch MUST send
+*   a matching `Content-Type` header. (This raw fetch to a presigned S3 URL
+*   is the sanctioned exception to the no-raw-fetch rule.)
+* - `resolveConfig()` throws on self-hosted agents without env/config.toml
+*   (and on unknown token prefixes). With no client, local refs resolve to
+*   FAILURES (dropped + fallback note) — never passthrough: a local path
+*   was never deliverable, and shipping it would leak filesystem structure.
+*   Remote http(s) refs are unaffected. The unavailability is memoized for
+*   the process lifetime (config appears via `alfe setup` + restart).
+*/
+const MAX_OUTBOUND_MEDIA_SIZE = 25 * 1024 * 1024;
+const UPLOAD_TIMEOUT_MS = 3e4;
+const EXTENSION_MIME = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	svg: "image/svg+xml",
+	mp4: "video/mp4",
+	mov: "video/quicktime",
+	webm: "video/webm",
+	mp3: "audio/mpeg",
+	wav: "audio/wav",
+	ogg: "audio/ogg",
+	m4a: "audio/mp4",
+	pdf: "application/pdf",
+	txt: "text/plain",
+	md: "text/markdown",
+	csv: "text/csv",
+	json: "application/json"
+};
+/** Extensions the markdown-image rewrite will upload. Restricting to image
+* types keeps `![x](/etc/passwd)`-style refs from shipping arbitrary VM
+* files to the attachment bucket. */
+const IMAGE_EXTENSIONS = new Set([
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"webp",
+	"svg"
+]);
+function createOutboundMediaContext() {
+	return {
+		uploads: /* @__PURE__ */ new Map(),
+		annotatedFailures: /* @__PURE__ */ new Set()
+	};
+}
+let cachedClient;
+function getUploadClient(log) {
+	if (cachedClient !== void 0) return cachedClient;
+	try {
+		const config = resolveConfig();
+		cachedClient = new AgentApiClient({
+			apiUrl: config.apiUrl,
+			apiKey: config.apiKey
+		});
+	} catch (err) {
+		log.warn(`Outbound media upload unavailable (no resolvable Alfe config): ${err instanceof Error ? err.message : String(err)}`);
+		cachedClient = null;
+	}
+	return cachedClient;
+}
+function mimeFromPath(p) {
+	const ext = extensionOf(p);
+	return (ext ? EXTENSION_MIME[ext] : void 0) ?? "application/octet-stream";
+}
+function extensionOf(p) {
+	const name = basename(p);
+	return name.includes(".") ? name.split(".").at(-1)?.toLowerCase() : void 0;
+}
+function isRemoteUrl(ref) {
+	return /^https?:\/\//i.test(ref);
+}
+/** Non-http(s) URI schemes (data:, blob:, media://inbound claim-checks…) —
+* not local paths, nothing we can upload. Windows drive letters (C:\) are
+* paths, not schemes. */
+function hasNonPathScheme(ref) {
+	if (/^file:\/\//i.test(ref)) return false;
+	if (/^[a-zA-Z]:[\\/]/.test(ref)) return false;
+	return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(ref);
+}
+/** file:// strip, ~ expansion, relative → cwd resolution. */
+function resolveLocalMediaPath(ref) {
+	let p = ref.replace(/^file:\/\//i, "");
+	if (p === "~" || p.startsWith("~/")) p = join(homedir(), p.slice(1));
+	return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+async function uploadLocalFile(localPath, log, deps) {
+	const client = deps.getClient ? deps.getClient() : getUploadClient(log);
+	if (!client) return null;
+	let size;
+	try {
+		const st = await stat(localPath);
+		if (!st.isFile()) {
+			log.warn(`Outbound media ref is not a file — skipping: ${localPath}`);
+			return null;
+		}
+		size = st.size;
+	} catch {
+		log.warn(`Outbound media file not found — skipping: ${localPath}`);
+		return null;
+	}
+	if (size <= 0) {
+		log.warn(`Outbound media file is empty — skipping: ${localPath}`);
+		return null;
+	}
+	if (size > 26214400) {
+		log.warn(`Outbound media exceeds ${String(MAX_OUTBOUND_MEDIA_SIZE)} bytes (${String(size)}) — skipping: ${localPath}`);
+		return null;
+	}
+	const filename = basename(localPath);
+	const mimeType = mimeFromPath(localPath);
+	try {
+		const body = await readFile(localPath);
+		const { attachments } = await client.presignAttachments([{
+			filename,
+			mimeType,
+			size
+		}]);
+		const presigned = attachments.at(0);
+		if (!presigned) {
+			log.warn(`Presign returned no attachment for ${filename}`);
+			return null;
+		}
+		const fetchFn = deps.fetchFn ?? fetch;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => {
+			controller.abort();
+		}, UPLOAD_TIMEOUT_MS);
+		try {
+			const res = await fetchFn(presigned.uploadUrl, {
+				method: "PUT",
+				headers: { "Content-Type": mimeType },
+				body,
+				signal: controller.signal
+			});
+			if (!res.ok) {
+				log.warn(`Outbound media PUT failed (${String(res.status)}) for ${filename}`);
+				return null;
+			}
+		} finally {
+			clearTimeout(timeout);
+		}
+		log.info(`Uploaded outbound media: ${filename} (${String(size)} bytes)`);
+		return {
+			url: presigned.downloadUrl,
+			filename,
+			mimeType,
+			size
+		};
+	} catch (err) {
+		log.warn(`Outbound media upload failed for ${filename}: ${err instanceof Error ? err.message : String(err)}`);
+		return null;
+	}
+}
+/**
+* Resolve one outbound media ref. Remote http(s) URLs pass through; local
+* paths upload (deduped per turn via `ctx`); non-path schemes and failures
+* resolve to null.
+*/
+function resolveOutboundMediaRef(ref, ctx, log, deps = {}) {
+	const trimmed = ref.trim();
+	if (!trimmed) return Promise.resolve(null);
+	if (isRemoteUrl(trimmed)) return Promise.resolve({ url: trimmed });
+	if (hasNonPathScheme(trimmed)) {
+		log.warn(`Outbound media ref has unsupported scheme — skipping: ${trimmed.slice(0, 120)}`);
+		return Promise.resolve(null);
+	}
+	const localPath = resolveLocalMediaPath(trimmed);
+	const cached = ctx.uploads.get(localPath);
+	if (cached) return cached;
+	const promise = ctx.uploads.size >= 10 ? (() => {
+		log.warn(`Outbound media per-turn cap (${String(10)}) reached — skipping: ${localPath}`);
+		return Promise.resolve(null);
+	})() : uploadLocalFile(localPath, log, deps);
+	ctx.uploads.set(localPath, promise);
+	return promise;
+}
+/**
+* Resolve a turn's `mediaUrl(s)` refs into hosted URLs + rich metadata.
+* `newFailures` lists local refs that failed and haven't been annotated
+* yet this turn — append fallback text for them so a media-only message
+* doesn't silently vanish.
+*/
+async function resolveOutboundMedia(refs, ctx, log, deps = {}) {
+	const mediaUrls = [];
+	const attachments = [];
+	const newFailures = [];
+	for (const ref of refs) {
+		const trimmed = ref.trim();
+		if (!trimmed) continue;
+		const resolved = await resolveOutboundMediaRef(trimmed, ctx, log, deps);
+		if (resolved) {
+			mediaUrls.push(resolved.url);
+			attachments.push(resolved);
+			continue;
+		}
+		if (isRemoteUrl(trimmed) || hasNonPathScheme(trimmed)) continue;
+		const localPath = resolveLocalMediaPath(trimmed);
+		if (!ctx.annotatedFailures.has(localPath)) {
+			ctx.annotatedFailures.add(localPath);
+			newFailures.push(basename(localPath));
+		}
+	}
+	return {
+		mediaUrls,
+		attachments,
+		newFailures
+	};
+}
+/** Formats the once-per-turn fallback note for failed uploads. */
+function formatMediaFailureNote(failures) {
+	return failures.map((f) => `[attachment failed to upload: ${f}]`).join("\n");
+}
+/** Split into code (fenced blocks + inline spans) and plain segments so the
+* rewrite never touches code. Fence detection is line-anchored ```/~~~,
+* matching OpenClaw's own parser precedent. Offset-based slicing so
+* rejoining segments with '' reproduces the input byte-for-byte. */
+function splitCodeSegments(text) {
+	const fenceSpans = [];
+	let inFence = false;
+	let fenceStart = 0;
+	let offset = 0;
+	for (const line of text.split("\n")) {
+		if (/^[ \t]*(`{3,}|~{3,})/.test(line)) if (!inFence) {
+			inFence = true;
+			fenceStart = offset;
+		} else {
+			fenceSpans.push({
+				start: fenceStart,
+				end: offset + line.length
+			});
+			inFence = false;
+		}
+		offset += line.length + 1;
+	}
+	if (inFence) fenceSpans.push({
+		start: fenceStart,
+		end: text.length
+	});
+	const segments = [];
+	let cursor = 0;
+	for (const span of fenceSpans) {
+		if (span.start > cursor) segments.push({
+			code: false,
+			text: text.slice(cursor, span.start)
+		});
+		segments.push({
+			code: true,
+			text: text.slice(span.start, span.end)
+		});
+		cursor = span.end;
+	}
+	if (cursor < text.length) segments.push({
+		code: false,
+		text: text.slice(cursor)
+	});
+	const result = [];
+	for (const seg of segments) {
+		if (seg.code) {
+			result.push(seg);
+			continue;
+		}
+		for (const part of seg.text.split(/(`[^`\n]+`)/)) {
+			if (!part) continue;
+			result.push({
+				code: part.startsWith("`") && part.endsWith("`") && part.length > 2,
+				text: part
+			});
+		}
+	}
+	return result;
+}
+const MARKDOWN_IMAGE_RE = /!\[([^\]\n]*)\]\(([^)\s]+)\)/g;
+/**
+* Rewrite `![alt](<local image path>)` to hosted URLs. Per-image: a failed
+* upload leaves that image's text untouched (a truncated mid-stream path
+* fails `stat` and is left alone; the terminal frame carries the full text
+* and rewrites correctly). Only image extensions are uploaded.
+*/
+async function rewriteLocalMarkdownImages(text, ctx, log, deps = {}) {
+	if (!text.includes("![")) return text;
+	const segments = splitCodeSegments(text);
+	return (await Promise.all(segments.map(async (seg) => {
+		if (seg.code || !seg.text.includes("![")) return seg.text;
+		const matches = [...seg.text.matchAll(MARKDOWN_IMAGE_RE)];
+		if (matches.length === 0) return seg.text;
+		let out = "";
+		let cursor = 0;
+		for (const match of matches) {
+			const [full, alt, src] = match;
+			const start = match.index;
+			out += seg.text.slice(cursor, start);
+			cursor = start + full.length;
+			if (isRemoteUrl(src) || hasNonPathScheme(src)) {
+				out += full;
+				continue;
+			}
+			const ext = extensionOf(src.split("?")[0]);
+			if (!ext || !IMAGE_EXTENSIONS.has(ext)) {
+				out += full;
+				continue;
+			}
+			const resolved = await resolveOutboundMediaRef(src, ctx, log, deps);
+			out += resolved ? `![${alt}](${resolved.url})` : full;
+		}
+		out += seg.text.slice(cursor);
+		return out;
+	}))).join("");
+}
+//#endregion
 //#region src/alfe-channel.ts
 /**
 * Alfe channel plugin definition — registers 'alfe' as an OpenClaw channel.
@@ -19,11 +358,161 @@ import { existsSync } from "node:fs";
 *
 * Config section: channels.alfe in openclaw.yaml
 */
+const noopLog = {
+	info: () => void 0,
+	warn: () => void 0,
+	error: () => void 0
+};
+function isSafeComponentUrl(raw) {
+	let u;
+	try {
+		u = new URL(raw);
+	} catch {
+		return false;
+	}
+	if (u.protocol !== "https:") return false;
+	const host = u.hostname.toLowerCase();
+	return host === "alfe.ai" || host.endsWith(".alfe.ai");
+}
+const MAX_COMPONENTS_PER_MESSAGE = 10;
+const MAX_COMPONENT_LABEL_CHARS = 120;
+const MAX_COMPONENT_VALUE_CHARS = 400;
+const MAX_OPTIONS_PER_COMPONENT = 25;
+/** Cap a maybe-string; returns '' for non-strings so callers can `if (!x)`. */
+function capStr(v, max) {
+	return typeof v === "string" ? v.slice(0, max) : "";
+}
+/**
+* Validate + cap the {label,value} option list of a select / multi_select.
+* Drops malformed / empty entries; caps the count. Empty result → the caller
+* drops the whole component (a chooser with no choices is useless).
+*/
+function sanitizeOptions(raw) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) {
+		if (out.length >= MAX_OPTIONS_PER_COMPONENT) break;
+		if (!item || typeof item !== "object") continue;
+		const o = item;
+		const label = capStr(o.label, MAX_COMPONENT_LABEL_CHARS);
+		const value = capStr(o.value, MAX_COMPONENT_VALUE_CHARS);
+		if (!label || !value) continue;
+		out.push({
+			label,
+			value
+		});
+	}
+	return out;
+}
+/**
+* Validate + normalize agent-supplied components down to the persisted wire
+* shape. Drops anything malformed or unsafe (unsafe URL, missing required
+* fields, no valid options, over-cap). Returns at most
+* MAX_COMPONENTS_PER_MESSAGE. Handles the full core set: `link_button`,
+* `quick_reply`, `select`, `multi_select`, `confirm`, `copy_button`. Only
+* `link_button` is URL-safety-gated — the rest carry no URL, so their values
+* are plain text (capped, never navigated).
+*/
+function sanitizeComponents(raw) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	const usedIds = /* @__PURE__ */ new Set();
+	for (const item of raw) {
+		if (out.length >= MAX_COMPONENTS_PER_MESSAGE) break;
+		if (!item || typeof item !== "object") continue;
+		const c = item;
+		const label = capStr(c.label, MAX_COMPONENT_LABEL_CHARS);
+		let id = typeof c.id === "string" && c.id ? c.id : randomUUID();
+		if (usedIds.has(id)) id = randomUUID();
+		usedIds.add(id);
+		const style = c.style === "primary" || c.style === "secondary" || c.style === "danger" ? c.style : void 0;
+		if (c.type === "link_button") {
+			if (!label) continue;
+			if (typeof c.url !== "string" || !isSafeComponentUrl(c.url)) continue;
+			const target = c.target === "same-tab" || c.target === "new-tab" || c.target === "popup" ? c.target : void 0;
+			out.push({
+				type: "link_button",
+				id,
+				label,
+				url: c.url,
+				...target ? { target } : {},
+				...style ? { style } : {}
+			});
+		} else if (c.type === "quick_reply") {
+			if (!label) continue;
+			const value = capStr(c.value, MAX_COMPONENT_VALUE_CHARS);
+			if (!value) continue;
+			out.push({
+				type: "quick_reply",
+				id,
+				label,
+				value,
+				...style ? { style } : {}
+			});
+		} else if (c.type === "select") {
+			const options = sanitizeOptions(c.options);
+			if (options.length === 0) continue;
+			const placeholder = capStr(c.placeholder, MAX_COMPONENT_LABEL_CHARS);
+			out.push({
+				type: "select",
+				id,
+				...label ? { label } : {},
+				...placeholder ? { placeholder } : {},
+				options
+			});
+		} else if (c.type === "multi_select") {
+			const options = sanitizeOptions(c.options);
+			if (options.length === 0) continue;
+			const submitLabel = capStr(c.submitLabel, MAX_COMPONENT_LABEL_CHARS);
+			out.push({
+				type: "multi_select",
+				id,
+				...label ? { label } : {},
+				options,
+				...submitLabel ? { submitLabel } : {}
+			});
+		} else if (c.type === "confirm") {
+			const confirmLabel = capStr(c.confirmLabel, MAX_COMPONENT_LABEL_CHARS);
+			const confirmValue = capStr(c.confirmValue, MAX_COMPONENT_VALUE_CHARS);
+			if (!confirmLabel || !confirmValue) continue;
+			const cancelLabel = capStr(c.cancelLabel, MAX_COMPONENT_LABEL_CHARS);
+			const cancelValue = capStr(c.cancelValue, MAX_COMPONENT_VALUE_CHARS);
+			out.push({
+				type: "confirm",
+				id,
+				...label ? { label } : {},
+				confirmLabel,
+				confirmValue,
+				...cancelLabel ? { cancelLabel } : {},
+				...cancelValue ? { cancelValue } : {}
+			});
+		} else if (c.type === "copy_button") {
+			if (!label) continue;
+			const value = capStr(c.value, MAX_COMPONENT_VALUE_CHARS);
+			if (!value) continue;
+			out.push({
+				type: "copy_button",
+				id,
+				label,
+				value
+			});
+		}
+	}
+	return out;
+}
 const CHANNEL_ID = "alfe";
 const DEFAULT_ACCOUNT_ID = "default";
-async function sendViaChat(deps, ctx, mediaUrl) {
+async function sendViaChat(deps, ctx, mediaUrl, components) {
 	const client = deps.getChatClient();
 	if (!client) throw new Error("Chat service not connected — cannot deliver");
+	const log = deps.log ?? noopLog;
+	const mediaCtx = createOutboundMediaContext();
+	let text = await rewriteLocalMarkdownImages(ctx.text, mediaCtx, log);
+	const media = await resolveOutboundMedia(mediaUrl ? [mediaUrl] : [], mediaCtx, log);
+	if (media.newFailures.length) {
+		if (!text.trim() && media.mediaUrls.length === 0 && !components?.length) throw new Error(`media_upload_failed: ${media.newFailures.join(", ")}`);
+		text = text ? `${text}\n\n${formatMediaFailureNote(media.newFailures)}` : formatMediaFailureNote(media.newFailures);
+	}
 	let conversationId;
 	if (ctx.to.startsWith("conv:")) {
 		conversationId = ctx.to.slice(5);
@@ -38,14 +527,19 @@ async function sendViaChat(deps, ctx, mediaUrl) {
 			await deps.createSession(conversationId, "", "alfe", void 0, userId);
 		}
 	}
-	await deps.addMessage(conversationId, "assistant", ctx.text);
+	if (components?.length) await deps.addMessage(conversationId, "assistant", text, void 0, void 0, components);
+	else await deps.addMessage(conversationId, "assistant", text);
 	const messageId = randomUUID();
 	client.notify("agent-message", {
 		conversationId,
-		text: ctx.text,
+		text,
 		sessionKey: conversationId,
 		messageId,
-		...mediaUrl ? { mediaUrls: [mediaUrl] } : {}
+		...media.mediaUrls.length ? {
+			mediaUrls: media.mediaUrls,
+			attachments: media.attachments
+		} : {},
+		...components?.length ? { components } : {}
 	});
 	return {
 		channel: "alfe",
@@ -54,6 +548,22 @@ async function sendViaChat(deps, ctx, mediaUrl) {
 		timestamp: Date.now()
 	};
 }
+/**
+* Present interactive components (link buttons, quick replies) into a
+* conversation — the outbound path for the `chat_present_components` tool.
+* `to` is a `conv:{id}` or `user:{id}` target (same vocabulary as the channel's
+* `resolveTarget`). Persists + broadcasts through the same `sendViaChat` path
+* as a normal reply, so the components ride the standard `message` frame and
+* are replayed on backfill. Components are sanitized (unsafe URLs dropped)
+* before delivery.
+*/
+async function presentComponentsViaChat(deps, args) {
+	if (args.components.length === 0) throw new Error("At least one valid component is required");
+	return await sendViaChat(deps, {
+		to: args.to,
+		text: args.text ?? ""
+	}, void 0, args.components);
+}
 function getChannelSection(cfg) {
 	return cfg.channels?.alfe ?? {};
 }
@@ -330,7 +840,7 @@ async function createSession(sessionId, agentId, channel, tenantId, userId) {
 	return session;
 }
 const writeLocks = /* @__PURE__ */ new Map();
-async function addMessage(sessionId, role, content, senderId, senderName) {
+async function addMessage(sessionId, role, content, senderId, senderName, components) {
 	const next = (writeLocks.get(sessionId) ?? Promise.resolve()).then(async () => {
 		const session = await getSession(sessionId);
 		if (!session) return;
@@ -339,7 +849,8 @@ async function addMessage(sessionId, role, content, senderId, senderName) {
 			content,
 			timestamp: Date.now(),
 			...senderId ? { senderId } : {},
-			...senderName ? { senderName } : {}
+			...senderName ? { senderName } : {},
+			...components?.length ? { components } : {}
 		});
 		await saveSession(session);
 	}).finally(() => {
@@ -984,13 +1495,13 @@ function defineTool(def) {
 		}
 	};
 }
-function buildA2ATools(getChatClient, log) {
+function buildA2ATools(getChatClient, log, present) {
 	const requireClient = () => {
 		const client = getChatClient();
 		if (!client) throw new Error("chat service not connected yet — try again in a moment");
 		return client;
 	};
-	return [
+	const tools = [
 		defineTool({
 			name: "list_agents",
 			description: "List other agents in your organization that you can communicate with.",
@@ -1066,6 +1577,134 @@ function buildA2ATools(getChatClient, log) {
 			}
 		})
 	];
+	if (present) tools.push(defineTool({
+		name: "chat_present_components",
+		description: "Attach interactive UI components to a chat message so the user can act with a tap instead of typing. PREFER components whenever you offer the user a discrete set of choices — a quick_reply or select reads far better than \"reply 1, 2, or 3\". Use:\n  • quick_reply — one-tap canned replies for a short set of options.\n  • select — a single choice from a longer list (dropdown).\n  • multi_select — let the user pick MANY options, then submit.\n  • confirm — an approval / yes-no decision (primary + secondary button).\n  • link_button — an actionable LINK (open a dashboard, a browser-takeover deep link). URL must be https on an Alfe-owned host.\n  • copy_button — let the user copy a value (token, id, snippet) to their clipboard.\nChoosing/submitting an interactive component sends the chosen value back AS THE USER'S NEXT MESSAGE, so the conversation continues normally — you will see it as ordinary user input. Don't button-spam: components are for real interactions, not decoration, and each message allows at most 10. Components degrade to plain text on clients that don't render them, so keep the essentials in `text` too.\nExamples:\n  Approval: { to:\"conv:abc\", text:\"Deploy to production?\", components:[ { type:\"confirm\", id:\"c1\", confirmLabel:\"Deploy\", confirmValue:\"yes, deploy\", cancelLabel:\"Cancel\", cancelValue:\"no, hold off\" } ] }\n  Pick one: { to:\"user:u_123\", text:\"Which environment?\", components:[ { type:\"select\", id:\"s1\", placeholder:\"Choose an environment\", options:[ { label:\"Dev\", value:\"dev\" }, { label:\"Staging\", value:\"staging\" }, { label:\"Prod\", value:\"prod\" } ] } ] }\n  Link: { to:\"conv:abc\", text:\"I need you to finish the login step.\", components:[ { type:\"link_button\", id:\"b1\", label:\"Open browser session\", url:\"https://app.alfe.ai/agents/x?tab=browser\", target:\"new-tab\", style:\"primary\" } ] }",
+		parameters: {
+			type: "object",
+			properties: {
+				to: {
+					type: "string",
+					description: "Target conversation: \"conv:{conversationId}\" or \"user:{userId}\"."
+				},
+				text: {
+					type: "string",
+					description: "Optional message text rendered above the components. Keep the key info here too — it is the fallback on clients that cannot render components."
+				},
+				components: {
+					type: "array",
+					description: "Interactive components to attach (at least one, at most 10).",
+					items: {
+						type: "object",
+						properties: {
+							type: {
+								type: "string",
+								enum: [
+									"link_button",
+									"quick_reply",
+									"select",
+									"multi_select",
+									"confirm",
+									"copy_button"
+								],
+								description: "Component kind — see the tool description for when to use each."
+							},
+							id: {
+								type: "string",
+								description: "Stable id (optional — auto-generated when omitted)."
+							},
+							label: {
+								type: "string",
+								description: "Button/control text. Required for link_button, quick_reply, copy_button; optional heading for select / multi_select."
+							},
+							url: {
+								type: "string",
+								description: "link_button only: https URL on an Alfe-owned host to open when clicked."
+							},
+							target: {
+								type: "string",
+								enum: [
+									"same-tab",
+									"new-tab",
+									"popup"
+								],
+								description: "link_button only: how the URL opens (default same-tab)."
+							},
+							value: {
+								type: "string",
+								description: "quick_reply: the text submitted as the user's next message when tapped. copy_button: the value copied to the clipboard."
+							},
+							placeholder: {
+								type: "string",
+								description: "select only: the empty-state prompt shown before a choice is made."
+							},
+							options: {
+								type: "array",
+								description: "select / multi_select only: the choices (max 25). Each is { label, value }; `value` is what gets submitted (multi_select joins checked values with \", \").",
+								items: {
+									type: "object",
+									properties: {
+										label: {
+											type: "string",
+											description: "Option text shown to the user."
+										},
+										value: {
+											type: "string",
+											description: "Value submitted when chosen."
+										}
+									},
+									required: ["label", "value"]
+								}
+							},
+							submitLabel: {
+								type: "string",
+								description: "multi_select only: submit button caption (default \"Submit\")."
+							},
+							confirmLabel: {
+								type: "string",
+								description: "confirm only: primary button text (e.g. \"Approve\")."
+							},
+							confirmValue: {
+								type: "string",
+								description: "confirm only: value submitted when the primary button is tapped."
+							},
+							cancelLabel: {
+								type: "string",
+								description: "confirm only: secondary button text (omit to show only the primary)."
+							},
+							cancelValue: {
+								type: "string",
+								description: "confirm only: value submitted when the secondary button is tapped."
+							},
+							style: {
+								type: "string",
+								enum: [
+									"primary",
+									"secondary",
+									"danger"
+								],
+								description: "link_button / quick_reply only: visual style hint."
+							}
+						},
+						required: ["type"]
+					}
+				}
+			},
+			required: ["to", "components"]
+		},
+		handler: async (params) => {
+			const to = params.to;
+			if (!to || !to.startsWith("conv:") && !to.startsWith("user:")) throw new Error("`to` must be \"conv:{conversationId}\" or \"user:{userId}\"");
+			const text = params.text;
+			log.info("chat_present_components tool called");
+			return await present({
+				to,
+				text,
+				components: params.components
+			});
+		}
+	}));
+	return tools;
 }
 //#endregion
 //#region src/attachment-url.ts
@@ -1798,6 +2437,7 @@ async function handleAgentRequest(request, log) {
 		const userLabel = displayName ?? userId ?? senderId;
 		const conversationLabel = conversationType === "group" ? shortConvId ? `[${channelLabel}] Group (${shortConvId})` : `[${channelLabel}] Group` : shortConvId ? `[${channelLabel}] ${userLabel} (${shortConvId})` : `[${channelLabel}] ${userLabel}`;
 		let a2aResponseBuffer = "";
+		const outboundMediaCtx = createOutboundMediaContext();
 		if (isA2A) resetA2AEndSignal();
 		const peer = conversationType === "group" ? {
 			kind: "group",
@@ -1863,8 +2503,13 @@ async function handleAgentRequest(request, log) {
 				} : {}
 			},
 			deliver: async (payload) => {
-				const responseText = stripLeakedToolSummary(stripThinkSpans(payload.text ?? ""));
-				const mediaUrls = [...payload.mediaUrl ? [payload.mediaUrl] : [], ...payload.mediaUrls ?? []];
+				let responseText = stripLeakedToolSummary(stripThinkSpans(payload.text ?? ""));
+				responseText = await rewriteLocalMarkdownImages(responseText, outboundMediaCtx, log);
+				const media = await resolveOutboundMedia([...payload.mediaUrl ? [payload.mediaUrl] : [], ...payload.mediaUrls ?? []], outboundMediaCtx, log);
+				if (media.newFailures.length) {
+					const note = formatMediaFailureNote(media.newFailures);
+					responseText = responseText ? `${responseText}\n\n${note}` : note;
+				}
 				await addMessage(sessionId, "assistant", responseText);
 				if (isA2A) a2aResponseBuffer += (a2aResponseBuffer && responseText ? "\n\n" : "") + responseText;
 				chatClient?.notify("agent-message", {
@@ -1872,7 +2517,10 @@ async function handleAgentRequest(request, log) {
 					text: responseText,
 					sessionKey: runGate.sessionKey ?? legacySessionKey,
 					messageId: chatMessageId ?? request.id,
-					...mediaUrls.length ? { mediaUrls } : {}
+					...media.mediaUrls.length ? {
+						mediaUrls: media.mediaUrls,
+						attachments: media.attachments
+					} : {}
 				});
 			},
 			onRecordError: (err) => {
@@ -1974,7 +2622,8 @@ async function handleSessionsGet(request, log) {
 				id: `msg-${String(m.timestamp)}`,
 				role: m.role,
 				content: m.content,
-				timestamp: m.timestamp
+				timestamp: m.timestamp,
+				...m.components?.length ? { components: m.components } : {}
 			})),
 			activity: await resolveHistoryActivity(session)
 		});
@@ -1991,19 +2640,30 @@ const plugin = {
 	version: pkg.version,
 	activate(api) {
 		const log = api.logger;
-		const alfeChannel = createAlfeChannelPlugin({
+		const outboundDeps = {
 			getChatClient: () => chatClient,
+			log,
 			listSessions,
 			getSession,
 			createSession,
 			addMessage
-		});
+		};
+		const alfeChannel = createAlfeChannelPlugin(outboundDeps);
 		api.registerChannel(alfeChannel);
 		log.info(`Registered channel: ${alfeChannel.id}`);
 		if (typeof api.registerTool === "function") {
-			const a2aTools = buildA2ATools(() => chatClient, log);
+			const present = async (args) => {
+				const clean = sanitizeComponents(args.components);
+				if (clean.length === 0) throw new Error("No valid components: link_button requires a `label` and an https `url` on an Alfe-owned host");
+				return presentComponentsViaChat(outboundDeps, {
+					to: args.to,
+					text: args.text,
+					components: clean
+				});
+			};
+			const a2aTools = buildA2ATools(() => chatClient, log, present);
 			for (const tool of a2aTools) api.registerTool(tool);
-			log.info(`Registered ${String(a2aTools.length)} agent-to-agent tools`);
+			log.info(`Registered ${String(a2aTools.length)} agent tools`);
 		}
 		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
 		const startChatService = () => {
@@ -2114,7 +2774,8 @@ const plugin = {
 						id: `msg-${String(m.timestamp)}`,
 						role: m.role,
 						content: m.content,
-						timestamp: m.timestamp
+						timestamp: m.timestamp,
+						...m.components?.length ? { components: m.components } : {}
 					})),
 					activity: await resolveHistoryActivity(session)
 				};