@openbrt/weclawbotctl 0.1.15 → 0.1.16

package/README.md

@@ -69,6 +69,7 @@ pre-rendered `weclawbot.screen_document.v1` first. The firmware receives pixels;
 it does not lay out text, choose fonts, or split pages for agents.
 
 ```bash
+weclawbotctl preview /path/to/screen-document.json
 weclawbotctl screen /path/to/screen-document.json
 ```
 
@@ -76,9 +77,14 @@ weclawbotctl screen /path/to/screen-document.json
 only after the firmware reports `applied`; a firmware `rejected` status or a
 timeout is a failed delivery. Use `--no-wait` only for diagnostics where MQTT
 publish acknowledgement is enough.
-When the OpenClaw tool `weclawbot_publish_screen_document` is used from a
-Telegram/UI session, the plugin renders the exact mono1 pages back into PNG
-previews and attaches them to the same session when the channel supports files.
+`preview` renders the exact mono1 pages into PNG files. `screen` also emits a
+`preview.pages[].path` list by default. Agents should inspect those images when
+possible and send them through their normal chat/media channel so the user sees
+the actual effect, not just "published".
+When the OpenClaw tool `weclawbot_publish_screen_document` is used, its return
+value contains the same `preview.pages[].path` list. The agent owns delivering
+that preview to the user; the plugin's automatic preview hook is only a
+best-effort fallback.
 
 To clear the current note, use the firmware clear command:
 
@@ -208,6 +214,7 @@ pre-rendered screen document immediately:
 
 ```bash
 weclawbotctl doctor --online
+weclawbotctl preview /path/to/screen-document.json
 weclawbotctl screen /path/to/screen-document.json
 ```
 
@@ -289,9 +296,11 @@ screen has exactly one page.
 Before publishing, agents should inspect or otherwise self-evaluate the rendered
 pages against the user's preferences and their own learned standards when their
 runtime supports it. Regenerate the document if the bitmap does not satisfy those
-standards.
+standards. After a successful publish, send the preview PNGs to the user through
+the current chat/media channel so the user can see the effect.
 
 ```bash
+weclawbotctl preview /path/to/screen-document.json
 weclawbotctl screen /path/to/screen-document.json
 ```
 

package/bin/weclawbotctl.mjs

@@ -10,6 +10,7 @@ import process from "node:process";
 import { validateActivity } from "../lib/activity.mjs";
 import { validateScreenDocument } from "../lib/direct-control.mjs";
 import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "../lib/mqtt-control.mjs";
+import { writeScreenDocumentPreviewFiles } from "../lib/screen-preview.mjs";
 
 const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
@@ -17,7 +18,7 @@ const DEFAULT_OPENCLAW_PLUGIN_SPEC = "@openbrt/weclawbotctl";
 const MIN_OPENCLAW_VERSION = "2026.6.9";
 
 const [command, ...args] = process.argv.slice(2);
-const commands = new Set(["bind", "status", "doctor", "export", "unbind", "thinking", "idle", "screen", "clear", "openclaw"]);
+const commands = new Set(["bind", "status", "doctor", "export", "unbind", "thinking", "idle", "screen", "preview", "clear", "openclaw"]);
 if (!commands.has(command)) {
   usage();
   process.exit(64);
@@ -30,6 +31,7 @@ try {
   else if (command === "export") await commandExport(args);
   else if (command === "unbind") await commandUnbind(args);
   else if (command === "screen") await commandScreen(args);
+  else if (command === "preview") await commandPreview(args);
   else if (command === "clear") await commandClear(args);
   else if (command === "openclaw") await commandOpenClaw(args);
   else await commandActivity(command, args);
@@ -208,10 +210,13 @@ async function commandScreen(values) {
     force: false,
     wait: true,
     timeout: 12,
+    preview: true,
+    "preview-dir": "",
+    scale: 2,
   });
   const file = String(options._[0] || "").trim();
   if (!file || options._.length !== 1) {
-    throw new Error("Usage: weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds]");
+    throw new Error("Usage: weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds] [--preview-dir dir]");
   }
   const document = JSON.parse(await fs.readFile(file, "utf8"));
   if (options.force) {
@@ -224,6 +229,12 @@ async function commandScreen(values) {
   if (!validation.ok) {
     throw new Error(`Invalid screen document: ${validation.errors.join("; ")}`);
   }
+  const preview = options.preview
+    ? await writeScreenDocumentPreviewFiles(document, {
+      outputDir: options["preview-dir"] || "",
+      scale: Number(options.scale) || 2,
+    })
+    : { available: false, pages: [] };
   const control = {
     schema: "weclawbot.control.v1",
     id: `screen_${crypto.randomUUID()}`,
@@ -248,6 +259,7 @@ async function commandScreen(values) {
       force_replace: document.force_replace === true,
       warnings: validation.warnings,
       layout_guidance: validation.layout_guidance,
+      preview,
       status: delivery.status,
     }));
     return;
@@ -262,6 +274,39 @@ async function commandScreen(values) {
     force_replace: document.force_replace === true,
     warnings: validation.warnings,
     layout_guidance: validation.layout_guidance,
+    preview,
+  }));
+}
+
+async function commandPreview(values) {
+  const options = parseOptions(values, {
+    output: "",
+    "output-dir": "",
+    scale: 2,
+  });
+  const file = String(options._[0] || "").trim();
+  if (!file || options._.length !== 1) {
+    throw new Error("Usage: weclawbotctl preview <document.json> [--output-dir dir] [--scale 1..4]");
+  }
+  const document = JSON.parse(await fs.readFile(file, "utf8"));
+  const validation = validateScreenDocument(document, {
+    agent_transport: { available: true, screen_document_available: true },
+  });
+  if (!validation.ok) {
+    throw new Error(`Invalid screen document: ${validation.errors.join("; ")}`);
+  }
+  const outputDir = options["output-dir"] || options.output || "";
+  const preview = await writeScreenDocumentPreviewFiles(document, {
+    outputDir,
+    scale: Number(options.scale) || 2,
+  });
+  console.log(JSON.stringify({
+    ok: true,
+    id: document.id,
+    pages: document.pages.length,
+    warnings: validation.warnings,
+    layout_guidance: validation.layout_guidance,
+    preview,
   }));
 }
 
@@ -739,7 +784,8 @@ function usage() {
   weclawbotctl unbind --yes
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
-  weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds]
+  weclawbotctl preview <document.json> [--output-dir dir] [--scale 1..4]
+  weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds] [--preview-dir dir] [--no-preview]
   weclawbotctl clear [--target note|idle_photo] [--no-wait] [--timeout seconds]
   weclawbotctl openclaw install [--spec @openbrt/weclawbotctl] [--bin /path/to/openclaw] [--force=false]
   weclawbotctl openclaw doctor [--gateway=false] [--bin /path/to/openclaw] [--json]`);

package/index.mjs

@@ -9,7 +9,8 @@ import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
 import { validateActivity } from "./lib/activity.mjs";
 import { validateScreenDocument } from "./lib/direct-control.mjs";
 import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "./lib/mqtt-control.mjs";
-import { previewSummary, renderScreenDocumentPreviewPages } from "./lib/screen-preview.mjs";
+import { collectCommandStrings, extractScreenDocumentPathFromExecParams, normalizeDeliveryContext } from "./lib/openclaw-preview.mjs";
+import { renderScreenDocumentPreviewPages, writeScreenDocumentPreviewFiles } from "./lib/screen-preview.mjs";
 
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
 const SCREEN_PROMPT_PATTERN = /weclawbot|weclaw|微笺|桌宠|墨水屏|电子墨水|屏上|上屏|发到屏|推到屏|放到屏|显示到屏|发送到屏|清屏|清理屏幕|屏幕/iu;
@@ -114,8 +115,9 @@ const pluginEntry = defineToolPlugin({
         force_replace: Type.Optional(Type.Boolean()),
         wait_status: Type.Optional(Type.Boolean()),
         timeout_seconds: Type.Optional(Type.Number()),
+        preview_output_dir: Type.Optional(Type.String()),
       }, { additionalProperties: false }),
-      execute: async ({ document, device_context, credentials_path, force_replace, wait_status, timeout_seconds }) => {
+      execute: async ({ document, device_context, credentials_path, force_replace, wait_status, timeout_seconds, preview_output_dir }) => {
         const outbound = cloneObject(document);
         if (force_replace) {
           outbound.force_replace = true;
@@ -134,8 +136,7 @@ const pluginEntry = defineToolPlugin({
           document: outbound,
         };
         const credentials = await requireCredentials(credentials_path);
-        const previewPages = renderScreenDocumentPreviewPages(outbound);
-        const preview = previewSummary(previewPages);
+        const preview = await writeScreenDocumentPreviewFiles(outbound, { outputDir: preview_output_dir || "" });
         if (wait_status !== false) {
           const delivery = await publishControlAndWaitStatus(credentials, control, {
             expectedDetail: outbound.id,
@@ -290,10 +291,14 @@ async function attachScreenPreview(api, event, ctx) {
   try {
     if (api.pluginConfig?.auto_preview === false) return;
     if (event?.error) return;
-    if (!ctx?.sessionKey || typeof api.session?.workflow?.sendSessionAttachment !== "function") return;
+    const sessionKey = resolveHookSessionKey(event, ctx);
+    if (!sessionKey) {
+      logPreviewSkip(api, event, "missing sessionKey");
+      return;
+    }
     let document = null;
     let source = "tool";
-    if (event?.toolName === "weclawbot_publish_screen_document") {
+    if (isScreenPublishTool(event?.toolName)) {
       document = cloneObject(event.params?.document);
       if (event.params?.force_replace) {
         document.force_replace = true;
@@ -301,15 +306,18 @@ async function attachScreenPreview(api, event, ctx) {
       }
     } else if (isExecTool(event?.toolName)) {
       const file = extractScreenDocumentPathFromExecParams(event.params);
+      if (!file && collectCommandStrings(event.params).some((value) => /weclawbotctl\s+screen\b/u.test(value))) {
+        logPreviewSkip(api, event, "screen command detected but document path was not found");
+      }
       if (!file) return;
       document = JSON.parse(await fs.readFile(file, "utf8"));
       source = "cli";
     } else {
       return;
     }
-    await attachPreviewForDocument(api, document, ctx, source);
+    await attachPreviewForDocument(api, document, { ...ctx, sessionKey }, source);
   } catch (error) {
-    api.logger?.debug?.(`weclawbot preview attachment skipped: ${errorMessage(error)}`);
+    api.logger?.warn?.(`weclawbot preview attachment failed: ${errorMessage(error)}`);
   }
 }
 
@@ -317,9 +325,15 @@ async function attachPreviewForDocument(api, document, ctx, source) {
     const validation = validateScreenDocument(document, {
       agent_transport: { available: true, screen_document_available: true },
     });
-    if (!validation.ok) return;
+    if (!validation.ok) {
+      api.logger?.warn?.(`weclawbot preview skipped: invalid screen document (${validation.errors?.[0] || "validation failed"})`);
+      return;
+    }
     const previewPages = renderScreenDocumentPreviewPages(document);
-    if (previewPages.length === 0) return;
+    if (previewPages.length === 0) {
+      api.logger?.warn?.("weclawbot preview skipped: no preview pages rendered");
+      return;
+    }
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "weclawbot-preview-"));
     const files = [];
     for (const page of previewPages) {
@@ -328,15 +342,115 @@ async function attachPreviewForDocument(api, document, ctx, source) {
       files.push({ path: file });
     }
     const pageLabel = `${previewPages.length} page${previewPages.length === 1 ? "" : "s"}`;
-    await api.session.workflow.sendSessionAttachment({
-      sessionKey: ctx.sessionKey,
-      files,
-      text: `WeClawBot screen preview: ${document.id || "screen"} (${pageLabel}, ${source})`,
-      maxBytes: 2_000_000,
-    });
+    const caption = `WeClawBot screen preview: ${document.id || "screen"} (${pageLabel}, ${source})`;
+    let attached = false;
+    if (typeof api.session?.workflow?.sendSessionAttachment === "function") {
+      const result = await api.session.workflow.sendSessionAttachment({
+        sessionKey: ctx.sessionKey,
+        files,
+        text: caption,
+        maxBytes: 2_000_000,
+        captionFormat: "plain",
+        channelHints: { telegram: { forceDocumentMime: "image/png" } },
+      });
+      if (result?.ok) {
+        attached = true;
+        api.logger?.info?.(`weclawbot preview attached via session workflow: ${result.channel} count=${result.count}`);
+      } else {
+        api.logger?.warn?.(`weclawbot session attachment unavailable: ${result?.error || "unknown error"}`);
+      }
+    }
+    if (!attached) {
+      const result = await sendPreviewViaOutboundAdapter(api, {
+        ctx,
+        files,
+        document,
+        source,
+        caption,
+        dir,
+      });
+      if (!result?.ok) {
+        api.logger?.warn?.(`weclawbot preview outbound fallback failed: ${result?.error || "unknown error"}`);
+      } else {
+        api.logger?.info?.(`weclawbot preview attached via outbound adapter: ${result.channel} count=${result.count}`);
+      }
+    }
     scheduleRemove(dir);
 }
 
+async function sendPreviewViaOutboundAdapter(api, params) {
+  const delivery = resolvePreviewDeliveryContext(api, params.ctx);
+  if (!delivery?.channel || !delivery?.to) {
+    return { ok: false, error: `session has no active delivery route: ${params.ctx.sessionKey}` };
+  }
+  const outbound = await api.runtime?.channel?.outbound?.loadAdapter?.(delivery.channel);
+  if (!outbound?.sendMedia) {
+    return { ok: false, error: `channel ${delivery.channel} has no media outbound adapter` };
+  }
+  const cfg = api.runtime?.config?.current?.() || api.config;
+  let count = 0;
+  for (let index = 0; index < params.files.length; index += 1) {
+    const file = params.files[index];
+    const suffix = params.files.length > 1 ? ` p${index + 1}/${params.files.length}` : "";
+    await outbound.sendMedia({
+      cfg,
+      to: delivery.to,
+      accountId: delivery.accountId,
+      threadId: delivery.threadId,
+      text: `${params.caption}${suffix}`,
+      mediaUrl: file.path,
+      mediaLocalRoots: [params.dir],
+      mediaReadFile: async (filePath) => fs.readFile(filePath),
+      forceDocument: false,
+      silent: true,
+    });
+    count += 1;
+  }
+  return {
+    ok: true,
+    channel: delivery.channel,
+    deliveredTo: delivery.to,
+    count,
+  };
+}
+
+function resolvePreviewDeliveryContext(api, ctx) {
+  const direct = normalizeDeliveryContext(ctx?.deliveryContext);
+  if (direct) return direct;
+  const entry = getSessionEntryBestEffort(api, ctx);
+  return normalizeDeliveryContext(entry?.deliveryContext) || normalizeDeliveryContext(entry?.route);
+}
+
+function getSessionEntryBestEffort(api, ctx) {
+  const getter = api.runtime?.agent?.session?.getSessionEntry;
+  if (typeof getter !== "function" || !ctx?.sessionKey) return null;
+  try {
+    return getter({ agentId: ctx.agentId, sessionKey: ctx.sessionKey });
+  } catch {
+    try {
+      return getter({ sessionKey: ctx.sessionKey });
+    } catch {
+      return null;
+    }
+  }
+}
+
+function logPreviewSkip(api, event, reason) {
+  api.logger?.warn?.(`weclawbot preview skipped: tool=${String(event?.toolName || "unknown")} reason=${reason}`);
+}
+
+function resolveHookSessionKey(event, ctx) {
+  return String(ctx?.sessionKey || event?.sessionKey || "").trim();
+}
+
+function isScreenPublishTool(name) {
+  return String(name || "").includes("weclawbot_publish_screen_document");
+}
+
+function isExecTool(name) {
+  return /(^|[_-])(exec|shell|command|process)($|[_-])/iu.test(String(name || ""));
+}
+
 function shouldAutoActivity(event, ctx) {
   if (String(ctx?.trigger || "").includes("curator")) return false;
   const prompt = String(event?.prompt || "");
@@ -350,80 +464,6 @@ function hookActivityKey(event, ctx) {
   return "";
 }
 
-function isExecTool(name) {
-  return /(^|[_-])(exec|shell|command)($|[_-])/iu.test(String(name || ""));
-}
-
-function extractScreenDocumentPathFromExecParams(params) {
-  const command = collectCommandStrings(params).join("\n");
-  if (!/weclawbotctl\s+screen\b/u.test(command)) return "";
-  for (const line of command.split(/\r?\n/u)) {
-    const match = line.match(/(?:^|\s)(?:[^\s;&|]*\/)?weclawbotctl\s+screen\b([^;&|\n]*)/u);
-    if (!match) continue;
-    const tokens = shellSplit(match[1] || "");
-    const candidates = [];
-    for (let index = 0; index < tokens.length; index += 1) {
-      const token = tokens[index];
-      if (!token) continue;
-      if (token.startsWith("--")) {
-        const key = token.split("=", 1)[0];
-        if (!token.includes("=") && new Set(["--credentials", "--timeout"]).has(key)) index += 1;
-        continue;
-      }
-      candidates.push(token);
-    }
-    const picked = candidates.findLast((token) => token.endsWith(".json")) || candidates.at(-1) || "";
-    if (picked) return expandPathWithBase(picked, params?.cwd || params?.workdir || process.cwd());
-  }
-  return "";
-}
-
-function collectCommandStrings(value, depth = 0) {
-  if (depth > 3 || value == null) return [];
-  if (typeof value === "string") return [value];
-  if (Array.isArray(value)) return value.flatMap((item) => collectCommandStrings(item, depth + 1));
-  if (typeof value !== "object") return [];
-  const wanted = ["cmd", "command", "script", "input", "args", "argv"];
-  return wanted.flatMap((key) => collectCommandStrings(value[key], depth + 1));
-}
-
-function shellSplit(value) {
-  const tokens = [];
-  let token = "";
-  let quote = "";
-  let escaped = false;
-  for (const ch of String(value || "")) {
-    if (escaped) {
-      token += ch;
-      escaped = false;
-      continue;
-    }
-    if (ch === "\\") {
-      escaped = true;
-      continue;
-    }
-    if (quote) {
-      if (ch === quote) quote = "";
-      else token += ch;
-      continue;
-    }
-    if (ch === "'" || ch === "\"") {
-      quote = ch;
-      continue;
-    }
-    if (/\s/u.test(ch)) {
-      if (token) {
-        tokens.push(token);
-        token = "";
-      }
-      continue;
-    }
-    token += ch;
-  }
-  if (token) tokens.push(token);
-  return tokens;
-}
-
 async function requireCredentials(credentialsPath) {
   const file = expandPath(credentialsPath || DEFAULT_CREDENTIALS_PATH);
   const payload = await readCredentials(file);
@@ -445,11 +485,6 @@ function expandPath(value) {
   return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
 }
 
-function expandPathWithBase(value, base) {
-  const expanded = expandPath(value);
-  return path.isAbsolute(expanded) ? expanded : path.resolve(String(base || process.cwd()), expanded);
-}
-
 function cloneObject(value) {
   if (!value || typeof value !== "object") throw new Error("document must be an object");
   return JSON.parse(JSON.stringify(value));

package/lib/openclaw-preview.mjs

@@ -0,0 +1,101 @@
+import os from "node:os";
+import path from "node:path";
+
+export function extractScreenDocumentPathFromExecParams(params) {
+  const command = collectCommandStrings(params).join("\n");
+  if (!/weclawbotctl\s+screen\b/u.test(command)) return "";
+  for (const line of command.split(/\r?\n/u)) {
+    const match = line.match(/(?:^|\s)(?:[^\s;&|]*\/)?weclawbotctl\s+screen\b([^;&|\n]*)/u);
+    if (!match) continue;
+    const tokens = shellSplit(match[1] || "");
+    const candidates = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+      const token = tokens[index];
+      if (!token) continue;
+      if (token.startsWith("--")) {
+        const key = token.split("=", 1)[0];
+        if (!token.includes("=") && new Set(["--credentials", "--timeout"]).has(key)) index += 1;
+        continue;
+      }
+      candidates.push(token);
+    }
+    const picked = candidates.findLast((token) => token.endsWith(".json")) || candidates.at(-1) || "";
+    if (picked) return expandPathWithBase(picked, params?.cwd || params?.workdir || process.cwd());
+  }
+  return "";
+}
+
+export function collectCommandStrings(value, depth = 0) {
+  if (depth > 5 || value == null) return [];
+  if (typeof value === "string") return value.length <= 40_000 ? [value] : [];
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === "string")) return [value.join(" ")];
+    return value.flatMap((item) => collectCommandStrings(item, depth + 1));
+  }
+  if (typeof value !== "object") return [];
+  return Object.values(value).flatMap((item) => collectCommandStrings(item, depth + 1));
+}
+
+export function normalizeDeliveryContext(value) {
+  if (!value || typeof value !== "object") return null;
+  const channel = typeof value.channel === "string" ? value.channel : "";
+  const to = typeof value.to === "string"
+    ? value.to
+    : typeof value.target?.to === "string"
+      ? value.target.to
+      : "";
+  if (!channel || !to) return null;
+  return {
+    channel,
+    to,
+    accountId: typeof value.accountId === "string" ? value.accountId : undefined,
+    threadId: value.threadId,
+  };
+}
+
+function shellSplit(value) {
+  const tokens = [];
+  let token = "";
+  let quote = "";
+  let escaped = false;
+  for (const ch of String(value || "")) {
+    if (escaped) {
+      token += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = "";
+      else token += ch;
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/u.test(ch)) {
+      if (token) {
+        tokens.push(token);
+        token = "";
+      }
+      continue;
+    }
+    token += ch;
+  }
+  if (token) tokens.push(token);
+  return tokens;
+}
+
+function expandPathWithBase(value, base) {
+  const expanded = expandPath(value);
+  return path.isAbsolute(expanded) ? expanded : path.resolve(String(base || process.cwd()), expanded);
+}
+
+function expandPath(value) {
+  const raw = String(value || "");
+  return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+}

package/lib/screen-preview.mjs

@@ -1,4 +1,7 @@
 import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { deflateSync } from "node:zlib";
 
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
@@ -35,6 +38,35 @@ export function previewSummary(previewPages) {
   };
 }
 
+export async function writeScreenDocumentPreviewFiles(document, options = {}) {
+  const previewPages = renderScreenDocumentPreviewPages(document, options);
+  const outputDir = options.outputDir
+    ? expandPath(options.outputDir)
+    : await fs.mkdtemp(path.join(os.tmpdir(), "weclawbot-preview-"));
+  await fs.mkdir(outputDir, { recursive: true });
+  const basename = safeFilename(options.basename || document?.id || "screen");
+  const pages = [];
+  for (const page of previewPages) {
+    const file = path.join(outputDir, `${basename}-p${page.index + 1}.png`);
+    await fs.writeFile(file, page.png);
+    pages.push({
+      index: page.index,
+      path: file,
+      width: page.width,
+      height: page.height,
+      scale: page.scale,
+      bytes: page.bytes,
+      sha256: page.sha256,
+      mime_type: "image/png",
+    });
+  }
+  return {
+    available: pages.length > 0,
+    output_dir: outputDir,
+    pages,
+  };
+}
+
 function renderMonoPagePreview(page, options = {}) {
   const width = Number(page?.width);
   const height = Number(page?.height);
@@ -123,3 +155,12 @@ function clampInteger(value, min, max) {
   if (!Number.isFinite(parsed)) return min;
   return Math.max(min, Math.min(max, parsed));
 }
+
+function expandPath(value) {
+  const raw = String(value || "");
+  return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+}
+
+function safeFilename(value) {
+  return String(value || "screen").replace(/[^a-zA-Z0-9_.-]/gu, "_").slice(0, 80) || "screen";
+}

package/openclaw.plugin.json

@@ -28,7 +28,7 @@
       },
       "auto_preview": {
         "type": "boolean",
-        "description": "Automatically attach PNG previews after publishing a screen document from an OpenClaw session."
+        "description": "Best-effort fallback that attaches PNG previews after publishing. Agents should still send preview.pages[].path to users explicitly."
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbrt/weclawbotctl",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "WeClawBot pairing and screen-control CLI for local AI agents.",
   "type": "module",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "check": "node --check index.mjs && node --check bin/weclawbot-openclaw-bridge.mjs && node --check bin/weclawbot-byoa-bind.mjs && node --check bin/weclawbotctl.mjs && node --test test/direct-control.test.mjs test/activity.test.mjs test/screen-preview.test.mjs"
+    "check": "node --check index.mjs && node --check lib/openclaw-preview.mjs && node --check bin/weclawbot-openclaw-bridge.mjs && node --check bin/weclawbot-byoa-bind.mjs && node --check bin/weclawbotctl.mjs && node --test test/direct-control.test.mjs test/activity.test.mjs test/screen-preview.test.mjs test/openclaw-preview-hook.test.mjs"
   },
   "dependencies": {
     "mqtt": "^5.10.4",

package/skills/weclawbot-curator/SKILL.md

@@ -54,12 +54,17 @@ weclawbotctl screen /path/to/screen-document.json
 ```
 
 or call `weclawbot_publish_screen_document` with the same document. Inside
-OpenClaw Telegram/UI sessions, prefer `weclawbot_publish_screen_document`: after
-publish it can attach PNG previews of the exact mono1 pages back to the
-conversation. Do not use OpenClaw Canvas for requests that mention WeClawBot, the
-physical screen, or “屏上”; Canvas is an OpenClaw UI surface, not the ESP32
-e-paper display. Do not send raw text to firmware. The agent owns text layout,
-font choice, image rasterization, and page splitting; the device consumes pixels.
+OpenClaw Telegram/UI sessions, prefer `weclawbot_publish_screen_document`: its
+result includes `preview.pages[].path` PNG files for the exact mono1 pages. The
+agent must inspect those preview files when possible, then send the preview PNGs
+back to the user through its normal chat/media channel before or alongside the
+"已上屏" reply. If the agent used CLI instead, run `weclawbotctl preview <doc>`
+before publishing, or read the `preview` field emitted by `weclawbotctl screen`.
+Do not use OpenClaw Canvas for requests that
+mention WeClawBot, the physical screen, or “屏上”; Canvas is an OpenClaw UI
+surface, not the ESP32 e-paper display. Do not send raw text to firmware. The
+agent owns text layout, font choice, image rasterization, preview review, user
+visible proof, and page splitting; the device consumes pixels.
 
 For clear requests such as “清屏”, “清理屏幕”, “clear screen”, or removing the
 current note, call `weclawbot_clear_screen` or run `weclawbotctl clear`. Never
@@ -86,8 +91,10 @@ Before publishing, review the actual rendered bitmap pages when your runtime can
 inspect images. Judge the preview against the user's preferences and the agent's
 own learned standards: legibility, margins, crowding, page count, and continuity
 across pages. If the preview does not satisfy those standards, regenerate the
-pages before publishing. This review loop belongs in the agent/tool layer; do not
-expect firmware to fix typography or split pages after the pixels arrive.
+pages before publishing. After a successful publish, include the preview PNG in
+the user-visible response so the user can see what was sent. This review and
+proof loop belongs in the agent/tool layer; do not expect firmware to fix
+typography, show chat previews, or split pages after the pixels arrive.
 
 `weclawbotctl screen` and `weclawbot_publish_screen_document` wait for the
 device status topic by default. Treat only `applied` as success. If the device

package/test/openclaw-preview-hook.test.mjs

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+
+import { collectCommandStrings, extractScreenDocumentPathFromExecParams, normalizeDeliveryContext } from "../lib/openclaw-preview.mjs";
+
+const extracted = extractScreenDocumentPathFromExecParams({
+  command: "~/.npm-global/bin/weclawbotctl screen /tmp/weclawbot-musk.json --force --timeout 20",
+  cwd: "/home/csc/.openclaw/workspace",
+});
+
+assert.equal(extracted, "/tmp/weclawbot-musk.json");
+
+const nested = collectCommandStrings({
+  payload: {
+    args: ["weclawbotctl", "screen", "relative-doc.json", "--timeout", "20"],
+  },
+});
+
+assert.ok(nested.some((value) => value.includes("weclawbotctl screen relative-doc.json")));
+
+const relative = extractScreenDocumentPathFromExecParams({
+  payload: {
+    input: "weclawbotctl screen relative-doc.json --force",
+  },
+  cwd: "/home/csc/.openclaw/workspace",
+});
+
+assert.equal(relative, path.resolve("/home/csc/.openclaw/workspace", "relative-doc.json"));
+
+assert.deepEqual(normalizeDeliveryContext({
+  channel: "telegram",
+  target: { to: "telegram:5728815108" },
+  accountId: "default",
+}), {
+  channel: "telegram",
+  to: "telegram:5728815108",
+  accountId: "default",
+  threadId: undefined,
+});
+
+console.log("openclaw preview hook helpers: ok");

package/test/screen-preview.test.mjs

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
+import fs from "node:fs/promises";
 
-import { renderScreenDocumentPreviewPages, previewSummary } from "../lib/screen-preview.mjs";
+import { renderScreenDocumentPreviewPages, previewSummary, writeScreenDocumentPreviewFiles } from "../lib/screen-preview.mjs";
 
 const width = 16;
 const height = 8;
@@ -10,7 +11,7 @@ for (let i = 0; i < Math.min(width, height); i += 1) {
   bytes[i * stride + (i >> 3)] |= 0x80 >> (i & 7);
 }
 
-const preview = renderScreenDocumentPreviewPages({
+const document = {
   schema: "weclawbot.screen_document.v1",
   pages: [{
     format: "mono1",
@@ -19,7 +20,9 @@ const preview = renderScreenDocumentPreviewPages({
     stride,
     data_b64: bytes.toString("base64"),
   }],
-}, { scale: 2 });
+};
+
+const preview = renderScreenDocumentPreviewPages(document, { scale: 2 });
 
 assert.equal(preview.length, 1);
 assert.equal(preview[0].width, width * 2);
@@ -32,4 +35,12 @@ const summary = previewSummary(preview);
 assert.equal(summary.available, true);
 assert.equal(summary.pages[0].mime_type, "image/png");
 
+const files = await writeScreenDocumentPreviewFiles(document, { scale: 2 });
+assert.equal(files.available, true);
+assert.equal(files.pages.length, 1);
+assert.match(files.pages[0].path, /\.png$/u);
+const persisted = await fs.readFile(files.pages[0].path);
+assert.equal(persisted.subarray(0, 8).toString("hex"), "89504e470d0a1a0a");
+await fs.rm(files.output_dir, { recursive: true, force: true });
+
 console.log("screen-preview renderer: ok");

package/workspace/AGENTS.md

@@ -44,8 +44,11 @@ screen revision in `base_revision`.
 
 When running inside OpenClaw with the WeClawBot plugin tools available, prefer
 `weclawbot_publish_screen_document` over shelling out to `weclawbotctl screen`;
-the tool can attach PNG previews of the exact pages back to the chat/UI after a
-successful publish.
+the tool returns `preview.pages[].path` PNG files for the exact pages. Inspect
+those preview images when possible, and send them back to the user through the
+normal chat/media channel before or alongside the success reply. If using CLI,
+run `weclawbotctl preview <document.json>` before publishing, or read the
+`preview` field emitted by `weclawbotctl screen`.
 
 The firmware receives pixels. Do not send raw text to firmware, and do not
 answer that direct delivery is unavailable before checking the local