@openbrt/weclawbotctl 0.1.9 → 0.1.15

package/README.md

@@ -52,6 +52,18 @@ weclawbotctl thinking --id "$task_id" --ttl 45
 weclawbotctl idle --id "$task_id"
 ```
 
+`idle` must use the same id as the active `thinking` message. Newer firmware
+rejects stale or unrelated `idle` messages and keeps the visible thinking state.
+The bundled OpenClaw bridge publishes `thinking` before every curator job and
+`idle` after it finishes, so WeChat-origin official-mode work also gets a visible
+processing state without relying on the model to remember it.
+In OpenClaw itself, the plugin also registers hooks for direct Telegram/UI agent
+turns that mention WeClawBot or the physical screen. Those hooks show the
+thinking pet while the turn runs and clear it before the final answer. The
+installer enables `plugins.entries.weclawbot.hooks.allowConversationAccess`
+because OpenClaw blocks conversation hooks for third-party plugins unless the
+user explicitly grants that permission.
+
 To put text, status, diagrams, or images on the screen, render them into a
 pre-rendered `weclawbot.screen_document.v1` first. The firmware receives pixels;
 it does not lay out text, choose fonts, or split pages for agents.
@@ -64,10 +76,23 @@ 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.
+
+To clear the current note, use the firmware clear command:
+
+```bash
+weclawbotctl clear
+```
+
+Do not emulate clear by publishing a blank, white, or black screen document.
+That creates a new note and can leave the physical screen looking black.
 
 The package also includes an OpenClaw integration: the `weclawbot-curator`
 skill, `weclawbot_status`, `weclawbot_validate_screen_document`,
-`weclawbot_publish_screen_document`, `weclawbot_validate_activity`,
+`weclawbot_clear_screen`, `weclawbot_publish_screen_document`,
+`weclawbot_validate_activity`,
 `weclawbot_publish_activity`, and a small outbound bridge service. The bridge
 polls `weclawbot.link`; no public HTTP endpoint, port forwarding, or WeChat
 credential is required on the OpenClaw host.
@@ -109,7 +134,7 @@ openclaw plugins enable weclawbot
 
 Restart the OpenClaw gateway or app after installation so it reloads plugin
 tools. The doctor checks the OpenClaw version, plugin installation, plugin
-diagnostics, and local gateway reachability. If a local WSS gateway uses a
+diagnostics, hook permission, and local gateway reachability. If a local WSS gateway uses a
 self-signed certificate, the doctor will suggest `NODE_EXTRA_CA_CERTS`. If the
 certificate lacks `localhost` or `127.0.0.1` SANs, fix the gateway certificate
 or use a certificate trusted by Node. The package does not rewrite other
@@ -248,6 +273,24 @@ three `mono1` pages, and a future UTC expiry. Agents may use PIL, Canvas, SVG
 rasterization, screenshots, or any local renderer, but the MQTT payload must be
 pixels:
 
+There is no canonical WeClawBot renderer that agents must use. The stable
+contract is the bounded pixel document plus device feedback. Keep layout,
+typography, and page-composition decisions in the agent/tool layer so skills and
+models can improve the result without requiring users to flash firmware.
+Preserve any layout preferences, visual language, page rhythm, font choices, or
+review habits that the user and agent have already developed; package upgrades
+should add capabilities without resetting that accumulated practice.
+
+The hardware facts are stable: the content viewport is 368 x 206 mono1 pixels,
+content documents may contain one to three pages, and the firmware will not split
+a single pixel page after receiving it. If `pages.length === 1`, the physical
+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.
+
 ```bash
 weclawbotctl screen /path/to/screen-document.json
 ```

package/bin/weclawbot-openclaw-bridge.mjs

@@ -2,6 +2,7 @@
 
 import process from "node:process";
 import { spawn } from "node:child_process";
+import path from "node:path";
 
 const ACTIONS = new Set([
   "ignore",
@@ -53,6 +54,10 @@ function stop() {
 
 async function handleJob(job) {
   const started = Date.now();
+  const activityId = `openclaw-${String(job.id || cryptoRandom()).replace(/[^a-zA-Z0-9_.-]/gu, "_").slice(0, 64)}`;
+  await publishBridgeActivity("thinking", activityId, {
+    ttlSeconds: Math.min(120, Math.max(5, config.agentTimeoutSeconds + 15)),
+  });
   try {
     const decision = await curateWithOpenClaw(job);
     await gatewayJson("POST", `${config.jobsPath}/${encodeURIComponent(job.id)}/result`, {
@@ -71,6 +76,24 @@ async function handleJob(job) {
     } catch (resultError) {
       log("failure_report_failed", { job: job.id, error: errorMessage(resultError) });
     }
+  } finally {
+    await publishBridgeActivity("idle", activityId);
+  }
+}
+
+async function publishBridgeActivity(state, id, options = {}) {
+  if (!config.screenActivity) return;
+  const args = [state, "--id", id];
+  if (state === "thinking") args.push("--ttl", String(options.ttlSeconds || 45));
+  try {
+    const result = await run(config.weclawbotctlBin, args, 8000);
+    if (result.code !== 0) {
+      log("activity_failed", { state, id, error: shortText(result.stderr || result.stdout || `exit ${result.code}`) });
+    } else {
+      log("activity_sent", { state, id });
+    }
+  } catch (error) {
+    log("activity_failed", { state, id, error: errorMessage(error) });
   }
 }
 
@@ -316,8 +339,10 @@ function loadConfig(env) {
     jobsPath: String(env.WEC_GATEWAY_JOBS_PATH || "/api/agent/curator/jobs"),
     agentId: String(env.WEC_OPENCLAW_AGENT || "weclawbot"),
     openclawBin: String(env.WEC_OPENCLAW_BIN || "openclaw"),
+    weclawbotctlBin: String(env.WEC_WECLAWBOTCTL_BIN || siblingBin("weclawbotctl")),
     transport: env.WEC_OPENCLAW_TRANSPORT === "local" ? "local" : "gateway",
     thinking: String(env.WEC_OPENCLAW_THINKING || "low"),
+    screenActivity: env.WEC_SCREEN_ACTIVITY !== "0" && env.WEC_SCREEN_ACTIVITY !== "false",
     pollWaitMs: positiveInteger(env.WEC_POLL_WAIT_MS, 20000),
     retryMs: positiveInteger(env.WEC_RETRY_MS, 3000),
     agentTimeoutSeconds: positiveInteger(env.WEC_AGENT_TIMEOUT_SECONDS, 20),
@@ -326,6 +351,15 @@ function loadConfig(env) {
   };
 }
 
+function siblingBin(name) {
+  const script = process.argv[1] || "";
+  return script ? path.join(path.dirname(script), name) : name;
+}
+
+function cryptoRandom() {
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
 function positiveInteger(value, fallback) {
   const parsed = Number.parseInt(String(value || ""), 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;

package/bin/weclawbotctl.mjs

@@ -17,7 +17,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", "openclaw"]);
+const commands = new Set(["bind", "status", "doctor", "export", "unbind", "thinking", "idle", "screen", "clear", "openclaw"]);
 if (!commands.has(command)) {
   usage();
   process.exit(64);
@@ -30,6 +30,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 === "clear") await commandClear(args);
   else if (command === "openclaw") await commandOpenClaw(args);
   else await commandActivity(command, args);
 } catch (error) {
@@ -245,6 +246,8 @@ async function commandScreen(values) {
       id: document.id,
       pages: document.pages.length,
       force_replace: document.force_replace === true,
+      warnings: validation.warnings,
+      layout_guidance: validation.layout_guidance,
       status: delivery.status,
     }));
     return;
@@ -257,9 +260,50 @@ async function commandScreen(values) {
     id: document.id,
     pages: document.pages.length,
     force_replace: document.force_replace === true,
+    warnings: validation.warnings,
+    layout_guidance: validation.layout_guidance,
   }));
 }
 
+async function commandClear(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    target: "note",
+    wait: true,
+    timeout: 12,
+  });
+  if (options._.length > 1) {
+    throw new Error("Usage: weclawbotctl clear [--target note|idle_photo] [--no-wait] [--timeout seconds]");
+  }
+  const target = normalizeClearTarget(options._[0] || options.target);
+  const control = {
+    schema: "weclawbot.control.v1",
+    id: `clear_${crypto.randomUUID()}`,
+    kind: "screen_clear",
+    target,
+  };
+  const credentials = await requireCredentials(expandPath(options.credentials));
+  if (options.wait) {
+    const delivery = await publishControlAndWaitStatus(credentials, control, {
+      expectedDetail: clearStatusDetail(target),
+      timeoutMs: Math.max(1, Number(options.timeout) || 12) * 1000,
+    });
+    if (delivery.status.kind !== "applied") {
+      throw new Error(`Device rejected screen clear: ${delivery.status.detail || "unknown"}`);
+    }
+    console.log(JSON.stringify({
+      ok: true,
+      published: true,
+      applied: true,
+      target,
+      status: delivery.status,
+    }));
+    return;
+  }
+  await publishControl(credentials, control);
+  console.log(JSON.stringify({ ok: true, published: true, applied: null, target }));
+}
+
 async function commandActivity(state, values) {
   const options = parseOptions(values, {
     credentials: credentialsPath(),
@@ -317,6 +361,13 @@ async function commandOpenClawInstall(values) {
   if (options.force) installArgs.push("--force");
   await runRequired(openclaw, installArgs);
   await runRequired(openclaw, ["plugins", "enable", "weclawbot"]);
+  await runRequired(openclaw, [
+    "config",
+    "set",
+    "plugins.entries.weclawbot.hooks.allowConversationAccess",
+    "true",
+    "--strict-json",
+  ]);
   console.log("OpenClaw plugin installed and enabled. Restart the OpenClaw gateway or app so it reloads plugins.");
   if (options.doctor) {
     await commandOpenClawDoctor(["--bin", openclaw, "--gateway=false"]);
@@ -358,6 +409,22 @@ async function commandOpenClawDoctor(values) {
     hint: weclawbotIssue ? "Upgrade and reinstall: weclawbotctl openclaw install" : "",
   });
 
+  const hooksAccess = await runCaptured(openclaw, [
+    "config",
+    "get",
+    "plugins.entries.weclawbot.hooks.allowConversationAccess",
+    "--json",
+  ], { timeoutMs });
+  const hooksEnabled = hooksAccess.code === 0 && /^\s*true\s*$/iu.test(hooksAccess.stdout);
+  checks.push({
+    name: "openclaw_weclawbot_hooks",
+    ok: hooksEnabled,
+    detail: hooksEnabled
+      ? "conversation hooks enabled for automatic thinking state"
+      : compactText(hooksAccess.stderr || hooksAccess.stdout || "hooks.allowConversationAccess is not enabled"),
+    hint: hooksEnabled ? "" : "Run: openclaw config set plugins.entries.weclawbot.hooks.allowConversationAccess true --strict-json",
+  });
+
   if (options.gateway) {
     const gatewayEnv = { ...process.env };
     const defaultCert = path.join(os.homedir(), ".openclaw", "gateway", "tls", "gateway-cert.pem");
@@ -643,6 +710,18 @@ function compactText(value) {
   return String(value || "").replace(/\s+/gu, " ").trim().slice(0, 500);
 }
 
+function normalizeClearTarget(value) {
+  const target = String(value || "note").trim();
+  if (target === "note" || target === "idle_photo" || target === "photo") {
+    return target === "photo" ? "idle_photo" : target;
+  }
+  throw new Error("clear target must be note or idle_photo");
+}
+
+function clearStatusDetail(target) {
+  return target === "idle_photo" ? "clear_idle_photo" : "clear_note";
+}
+
 function shellValue(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
@@ -661,6 +740,7 @@ function usage() {
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
   weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds]
+  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,16 +9,23 @@ 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";
 
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
+const SCREEN_PROMPT_PATTERN = /weclawbot|weclaw|微笺|桌宠|墨水屏|电子墨水|屏上|上屏|发到屏|推到屏|放到屏|显示到屏|发送到屏|清屏|清理屏幕|屏幕/iu;
+const activeRunActivities = new Map();
 
 // The long-running curator bridge remains a separate service. These tools keep
 // the local agent path explicit: validate first, then publish only with the
 // user's paired MQTT credential.
-export default defineToolPlugin({
+const pluginEntry = defineToolPlugin({
   id: "weclawbot",
   name: "WeClawBot",
   description: "WeClawBot screen-curation skill pack and direct MQTT control tools.",
+  configSchema: Type.Object({
+    auto_activity: Type.Optional(Type.Boolean()),
+    auto_preview: Type.Optional(Type.Boolean()),
+  }, { additionalProperties: false }),
   tools: (tool) => [
     tool({
       name: "weclawbot_status",
@@ -59,6 +66,43 @@ export default defineToolPlugin({
       }, { additionalProperties: false }),
       execute: ({ document, device_context }) => validateScreenDocument(document, device_context),
     }),
+    tool({
+      name: "weclawbot_clear_screen",
+      label: "Clear WeClawBot screen",
+      description: "Clear the paired WeClawBot note or idle-photo state with the firmware screen_clear control. Do not emulate clearing by publishing a blank or black bitmap.",
+      parameters: Type.Object({
+        target: Type.Optional(Type.String()),
+        credentials_path: Type.Optional(Type.String()),
+        wait_status: Type.Optional(Type.Boolean()),
+        timeout_seconds: Type.Optional(Type.Number()),
+      }, { additionalProperties: false }),
+      execute: async ({ target, credentials_path, wait_status, timeout_seconds }) => {
+        const clearTarget = normalizeClearTarget(target);
+        const control = {
+          schema: "weclawbot.control.v1",
+          id: `clear_${crypto.randomUUID()}`,
+          kind: "screen_clear",
+          target: clearTarget,
+        };
+        const credentials = await requireCredentials(credentials_path);
+        if (wait_status !== false) {
+          const delivery = await publishControlAndWaitStatus(credentials, control, {
+            expectedDetail: clearStatusDetail(clearTarget),
+            timeoutMs: Math.max(1, Number(timeout_seconds) || 12) * 1000,
+          });
+          return {
+            ok: delivery.status.kind === "applied",
+            published: true,
+            applied: delivery.status.kind === "applied",
+            rejected: delivery.status.kind === "rejected",
+            target: clearTarget,
+            status: delivery.status,
+          };
+        }
+        await publishControl(credentials, control);
+        return { ok: true, published: true, applied: null, target: clearTarget };
+      },
+    }),
     tool({
       name: "weclawbot_publish_screen_document",
       label: "Publish WeClawBot screen document",
@@ -90,6 +134,8 @@ export default defineToolPlugin({
           document: outbound,
         };
         const credentials = await requireCredentials(credentials_path);
+        const previewPages = renderScreenDocumentPreviewPages(outbound);
+        const preview = previewSummary(previewPages);
         if (wait_status !== false) {
           const delivery = await publishControlAndWaitStatus(credentials, control, {
             expectedDetail: outbound.id,
@@ -103,6 +149,9 @@ export default defineToolPlugin({
             id: outbound.id,
             pages: outbound.pages.length,
             force_replace: outbound.force_replace === true,
+            warnings: validation.warnings,
+            layout_guidance: validation.layout_guidance,
+            preview,
             status: delivery.status,
           };
         }
@@ -114,6 +163,9 @@ export default defineToolPlugin({
           id: outbound.id,
           pages: outbound.pages.length,
           force_replace: outbound.force_replace === true,
+          warnings: validation.warnings,
+          layout_guidance: validation.layout_guidance,
+          preview,
         };
       },
     }),
@@ -160,6 +212,218 @@ export default defineToolPlugin({
   ],
 });
 
+const registerTools = pluginEntry.register;
+pluginEntry.register = (api) => {
+  registerTools(api);
+  registerOpenClawHooks(api);
+};
+
+export default pluginEntry;
+
+function registerOpenClawHooks(api) {
+  if (!api || typeof api.on !== "function") return;
+  api.on("before_agent_run", async (event, ctx) => {
+    await startHookActivity(api, event, ctx);
+    return { outcome: "pass" };
+  }, { timeoutMs: 5_000 });
+  api.on("before_agent_finalize", async (event, ctx) => {
+    await finishHookActivity(api, event, ctx);
+    return { action: "continue" };
+  }, { timeoutMs: 5_000 });
+  api.on("agent_end", async (event, ctx) => {
+    await finishHookActivity(api, event, ctx);
+  }, { timeoutMs: 5_000 });
+  api.on("after_tool_call", async (event, ctx) => {
+    await attachScreenPreview(api, event, ctx);
+  }, { timeoutMs: 10_000 });
+}
+
+async function startHookActivity(api, event, ctx) {
+  try {
+    if (api.pluginConfig?.auto_activity === false) return;
+    if (!shouldAutoActivity(event, ctx)) return;
+    const key = hookActivityKey(event, ctx);
+    if (!key || activeRunActivities.has(key)) return;
+    const correlationId = `openclaw-${sanitizeId(ctx?.runId || key).slice(0, 72)}`;
+    await publishControl(await requireCredentials(), {
+      schema: "weclawbot.control.v1",
+      id: `activity_${crypto.randomUUID()}`,
+      kind: "activity",
+      activity: {
+        schema: "weclawbot.activity.v1",
+        state: "thinking",
+        correlation_id: correlationId,
+        ttl_seconds: 120,
+      },
+    });
+    activeRunActivities.set(key, { correlationId, startedAt: Date.now() });
+    api.logger?.info?.(`weclawbot activity thinking sent for ${key}`);
+  } catch (error) {
+    api.logger?.debug?.(`weclawbot activity hook skipped: ${errorMessage(error)}`);
+  }
+}
+
+async function finishHookActivity(api, event, ctx) {
+  try {
+    const key = hookActivityKey(event, ctx);
+    if (!key) return;
+    const active = activeRunActivities.get(key);
+    if (!active) return;
+    activeRunActivities.delete(key);
+    await publishControl(await requireCredentials(), {
+      schema: "weclawbot.control.v1",
+      id: `activity_${crypto.randomUUID()}`,
+      kind: "activity",
+      activity: {
+        schema: "weclawbot.activity.v1",
+        state: "idle",
+        correlation_id: active.correlationId,
+      },
+    });
+    api.logger?.info?.(`weclawbot activity idle sent for ${key}`);
+  } catch (error) {
+    api.logger?.debug?.(`weclawbot activity idle hook skipped: ${errorMessage(error)}`);
+  }
+}
+
+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;
+    let document = null;
+    let source = "tool";
+    if (event?.toolName === "weclawbot_publish_screen_document") {
+      document = cloneObject(event.params?.document);
+      if (event.params?.force_replace) {
+        document.force_replace = true;
+        document.base_revision = "*";
+      }
+    } else if (isExecTool(event?.toolName)) {
+      const file = extractScreenDocumentPathFromExecParams(event.params);
+      if (!file) return;
+      document = JSON.parse(await fs.readFile(file, "utf8"));
+      source = "cli";
+    } else {
+      return;
+    }
+    await attachPreviewForDocument(api, document, ctx, source);
+  } catch (error) {
+    api.logger?.debug?.(`weclawbot preview attachment skipped: ${errorMessage(error)}`);
+  }
+}
+
+async function attachPreviewForDocument(api, document, ctx, source) {
+    const validation = validateScreenDocument(document, {
+      agent_transport: { available: true, screen_document_available: true },
+    });
+    if (!validation.ok) return;
+    const previewPages = renderScreenDocumentPreviewPages(document);
+    if (previewPages.length === 0) return;
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "weclawbot-preview-"));
+    const files = [];
+    for (const page of previewPages) {
+      const file = path.join(dir, `${safeFilename(document.id || "screen")}-p${page.index + 1}.png`);
+      await fs.writeFile(file, page.png);
+      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,
+    });
+    scheduleRemove(dir);
+}
+
+function shouldAutoActivity(event, ctx) {
+  if (String(ctx?.trigger || "").includes("curator")) return false;
+  const prompt = String(event?.prompt || "");
+  if (prompt.includes("WECLAWBOT_CURATOR_EVENT")) return false;
+  return SCREEN_PROMPT_PATTERN.test(prompt);
+}
+
+function hookActivityKey(event, ctx) {
+  if (ctx?.runId || event?.runId) return `run:${ctx?.runId || event?.runId}`;
+  if (ctx?.sessionKey) return `session:${ctx.sessionKey}`;
+  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);
@@ -181,11 +445,47 @@ 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));
 }
 
+function normalizeClearTarget(value) {
+  const target = String(value || "note").trim();
+  if (target === "note" || target === "idle_photo" || target === "photo") {
+    return target === "photo" ? "idle_photo" : target;
+  }
+  throw new Error("clear target must be note or idle_photo");
+}
+
+function clearStatusDetail(target) {
+  return target === "idle_photo" ? "clear_idle_photo" : "clear_note";
+}
+
+function sanitizeId(value) {
+  return String(value || crypto.randomUUID()).replace(/[^a-zA-Z0-9_.-]/gu, "_");
+}
+
+function safeFilename(value) {
+  return sanitizeId(value).slice(0, 80) || "screen";
+}
+
+function scheduleRemove(dir) {
+  const timer = setTimeout(() => {
+    fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+  }, 60_000);
+  timer.unref?.();
+}
+
+function errorMessage(error) {
+  return String(error instanceof Error ? error.message : error).replace(/\s+/gu, " ").trim().slice(0, 240);
+}
+
 function maskedMqtt(config, topics) {
   return {
     url: config.url,

package/lib/direct-control.mjs

@@ -29,6 +29,7 @@ export function resolveDeviceContext(value) {
 export function validateScreenDocument(value, suppliedContext) {
   const context = resolveDeviceContext(suppliedContext);
   const errors = [];
+  const pageStats = [];
   const document = value && typeof value === "object" ? value : null;
   const viewport = context.content_viewport;
   if (!document) return result(context, errors.concat("document must be an object"));
@@ -48,12 +49,15 @@ export function validateScreenDocument(value, suppliedContext) {
   if (!Array.isArray(document.pages) || document.pages.length < 1 || document.pages.length > viewport.max_pages) {
     errors.push(`pages must contain 1..${viewport.max_pages} items`);
   } else {
-    document.pages.forEach((page, index) => validatePage(page, index, viewport, errors));
+    document.pages.forEach((page, index) => validatePage(page, index, viewport, errors, pageStats));
+    if (pageStats.length > 0 && pageStats.every((stat) => stat.uniform)) {
+      errors.push("uniform_screen_document: content pages cannot all be a single color; use screen_clear for clearing");
+    }
   }
-  return result(context, errors);
+  return result(context, errors, document);
 }
 
-function validatePage(page, index, viewport, errors) {
+function validatePage(page, index, viewport, errors, pageStats) {
   if (!page || typeof page !== "object") {
     errors.push(`pages[${index}] must be an object`);
     return;
@@ -77,14 +81,35 @@ function validatePage(page, index, viewport, errors) {
     errors.push(`pages[${index}].data_b64 is not valid base64`);
   } else if (Number.isInteger(stride) && Number.isInteger(height) && bytes.length !== stride * height) {
     errors.push(`pages[${index}].data_b64 byte length does not match stride * height`);
+  } else if (bytes.length > 0) {
+    pageStats.push({ index, uniform: bytes.every((byte) => byte === bytes[0]) });
   }
 }
 
-function result(context, errors) {
+function result(context, errors, document = null) {
+  const pageCount = Array.isArray(document?.pages) ? document.pages.length : 0;
+  const warnings = [];
+  if (pageCount === 1) {
+    warnings.push("single_page_document: firmware will not split pixels; verify the page remains readable before publishing");
+  } else if (pageCount > 1) {
+    warnings.push("multi_page_document: firmware will auto-flip pages and manual left/right buttons can change pages");
+  }
   return {
     ok: errors.length === 0,
     errors,
+    warnings,
     viewport: context.content_viewport,
+    layout_guidance: {
+      hardware_contract: "agent supplies pre-rendered mono1 pixels; firmware validates geometry and does not lay out text or split pages",
+      page_contract: "pages.length is the physical page count; content documents support 1-3 pages",
+      preference_policy: "preserve user-agent learned layout preferences unless they violate hardware bounds or the user asks to change them",
+      review_policy: "agent should inspect rendered bitmap pages against user preferences and learned standards before publishing when possible",
+      max_pages: context.content_viewport?.max_pages,
+      content_viewport_px: {
+        width: context.content_viewport?.width,
+        height: context.content_viewport?.height,
+      },
+    },
     agent_transport: context.agent_transport || null,
     direct_delivery_ready: context.agent_transport?.screen_document_available === true
       || context.agent_transport?.available === true,

package/lib/screen-preview.mjs

@@ -0,0 +1,125 @@
+import crypto from "node:crypto";
+import { deflateSync } from "node:zlib";
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export function renderScreenDocumentPreviewPages(document, options = {}) {
+  const pages = Array.isArray(document?.pages) ? document.pages : [];
+  const scale = clampInteger(options.scale ?? 2, 1, 4);
+  return pages.map((page, index) => {
+    const png = renderMonoPagePreview(page, { scale });
+    return {
+      index,
+      width: Number(page.width) * scale,
+      height: Number(page.height) * scale,
+      scale,
+      png,
+      bytes: png.length,
+      sha256: crypto.createHash("sha256").update(png).digest("hex"),
+    };
+  });
+}
+
+export function previewSummary(previewPages) {
+  return {
+    available: previewPages.length > 0,
+    pages: previewPages.map((page) => ({
+      index: page.index,
+      width: page.width,
+      height: page.height,
+      scale: page.scale,
+      bytes: page.bytes,
+      sha256: page.sha256,
+      mime_type: "image/png",
+    })),
+  };
+}
+
+function renderMonoPagePreview(page, options = {}) {
+  const width = Number(page?.width);
+  const height = Number(page?.height);
+  const stride = Number(page?.stride);
+  const scale = clampInteger(options.scale ?? 2, 1, 4);
+  if (!Number.isInteger(width) || width < 1 || !Number.isInteger(height) || height < 1) {
+    throw new Error("preview page width/height must be positive integers");
+  }
+  if (!Number.isInteger(stride) || stride < Math.ceil(width / 8)) {
+    throw new Error("preview page stride is invalid");
+  }
+  const packed = Buffer.from(String(page?.data_b64 || ""), "base64");
+  if (packed.length < stride * height) {
+    throw new Error("preview page data is shorter than stride * height");
+  }
+
+  const outWidth = width * scale;
+  const outHeight = height * scale;
+  const gray = Buffer.alloc(outWidth * outHeight, 0xff);
+  for (let y = 0; y < height; y += 1) {
+    const row = y * stride;
+    for (let x = 0; x < width; x += 1) {
+      const black = (packed[row + (x >> 3)] & (0x80 >> (x & 7))) !== 0;
+      if (!black) continue;
+      for (let dy = 0; dy < scale; dy += 1) {
+        const outRow = (y * scale + dy) * outWidth;
+        for (let dx = 0; dx < scale; dx += 1) {
+          gray[outRow + x * scale + dx] = 0;
+        }
+      }
+    }
+  }
+  return encodeGrayscalePng(gray, outWidth, outHeight);
+}
+
+function encodeGrayscalePng(gray, width, height) {
+  const raw = Buffer.alloc((width + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    const row = y * (width + 1);
+    raw[row] = 0;
+    gray.copy(raw, row + 1, y * width, (y + 1) * width);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 0;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    pngChunk("IHDR", ihdr),
+    pngChunk("IDAT", deflateSync(raw)),
+    pngChunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+function pngChunk(type, data) {
+  const typeBuf = Buffer.from(type, "ascii");
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+  return Buffer.concat([len, typeBuf, data, crc]);
+}
+
+const crcTable = new Uint32Array(256).map((_, index) => {
+  let c = index;
+  for (let bit = 0; bit < 8; bit += 1) {
+    c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+  }
+  return c >>> 0;
+});
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc = crcTable[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function clampInteger(value, min, max) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed)) return min;
+  return Math.max(min, Math.min(max, parsed));
+}

package/openclaw.plugin.json

@@ -6,6 +6,7 @@
     "tools": [
       "weclawbot_status",
       "weclawbot_validate_screen_document",
+      "weclawbot_clear_screen",
       "weclawbot_publish_screen_document",
       "weclawbot_validate_activity",
       "weclawbot_publish_activity"
@@ -20,6 +21,15 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {}
+    "properties": {
+      "auto_activity": {
+        "type": "boolean",
+        "description": "Automatically show the WeClawBot thinking pet during OpenClaw turns that mention the physical screen."
+      },
+      "auto_preview": {
+        "type": "boolean",
+        "description": "Automatically attach PNG previews after publishing a screen document from an OpenClaw session."
+      }
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbrt/weclawbotctl",
-  "version": "0.1.9",
+  "version": "0.1.15",
   "description": "WeClawBot pairing and screen-control CLI for local AI agents.",
   "type": "module",
   "license": "MIT",
@@ -43,10 +43,11 @@
     "./activity": "./lib/activity.mjs",
     "./direct-control": "./lib/direct-control.mjs",
     "./mqtt-control": "./lib/mqtt-control.mjs",
+    "./screen-preview": "./lib/screen-preview.mjs",
     "./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"
+    "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"
   },
   "dependencies": {
     "mqtt": "^5.10.4",

package/skills/weclawbot-curator/SKILL.md

@@ -53,11 +53,41 @@ publish it with:
 weclawbotctl screen /path/to/screen-document.json
 ```
 
-or call `weclawbot_publish_screen_document` with the same document. 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.
+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.
+
+For clear requests such as “清屏”, “清理屏幕”, “clear screen”, or removing the
+current note, call `weclawbot_clear_screen` or run `weclawbotctl clear`. Never
+simulate clearing by publishing a blank, white, or black `screen_document`; that
+creates a new note instead of clearing firmware state.
+
+## Layout, preferences, and page splitting
+
+Treat this skill as a hardware contract and starting point, not as a fixed house
+style. If the user and agent have already developed layout preferences, visual
+language, page rhythm, font choices, or review habits, preserve those choices
+unless the user asks to change them or they violate the device bounds below.
+Skill upgrades must be additive and compatible with accumulated user-agent
+practice; do not reset or overwrite local style memory just because this package
+changed.
+
+Hardware facts: the content viewport is 368 x 206 mono1 pixels, and a document
+may contain one to three content pages. The firmware will not split a single
+pixel page after receiving it; if the document has `pages.length === 1`, the
+physical screen has exactly one page. Multi-page documents can be auto-flipped by
+firmware and changed with the physical left/right buttons.
+
+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.
 
 `weclawbotctl screen` and `weclawbot_publish_screen_document` wait for the
 device status topic by default. Treat only `applied` as success. If the device
@@ -92,9 +122,11 @@ For a paired device, publish `weclawbot.activity.v1` with `state: "thinking"`
 immediately before an LLM call, long retrieval, or multi-step operation, then
 always publish `state: "idle"` in a `finally` path after success or failure.
 The thinking message requires a 5-120 second `ttl_seconds` and a stable
-`correlation_id`; use `weclawbot_validate_activity` first. It is a temporary
-overlay that restores the exact prior page, not a screen document and not a
-status to leave on indefinitely. Do not publish it when
+`correlation_id`; the matching idle message must reuse the same id. Newer
+firmware rejects stale or unrelated idle messages and keeps the active thinking
+state. Use `weclawbot_validate_activity` first. It is a temporary overlay that
+restores the exact prior page, not a screen document and not a status to leave on
+indefinitely. Do not publish it when
 `agent_transport.available` is false.
 
 Return this shape:

package/systemd/weclawbot-openclaw-curator.service

@@ -7,6 +7,7 @@ Wants=network-online.target
 Type=simple
 EnvironmentFile=%h/.config/weclawbot/openclaw-curator.env
 Environment=NODE_EXTRA_CA_CERTS=%h/.openclaw/gateway/tls/gateway-cert.pem
+Environment=WEC_WECLAWBOTCTL_BIN=%h/.npm-global/bin/weclawbotctl
 ExecStart=%h/.npm-global/bin/weclawbot-openclaw-bridge
 Restart=always
 RestartSec=3

package/test/direct-control.test.mjs

@@ -5,6 +5,7 @@ import { resolveDeviceContext, validateScreenDocument } from "../lib/direct-cont
 const context = resolveDeviceContext();
 const viewport = context.content_viewport;
 const bytes = Buffer.alloc(Math.ceil(viewport.width / 8) * viewport.height, 0xff);
+bytes[0] = 0x00;
 const valid = validateScreenDocument({
   schema: "weclawbot.screen_document.v1",
   id: "test-card",
@@ -33,4 +34,22 @@ const invalid = validateScreenDocument({
 assert.equal(invalid.ok, false);
 assert.ok(invalid.errors.some((error) => error.includes("width")));
 
+const uniform = validateScreenDocument({
+  schema: "weclawbot.screen_document.v1",
+  id: "bad-clear",
+  base_revision: "",
+  expires_at: new Date(Date.now() + 60_000).toISOString(),
+  target: "content",
+  kind: "replace",
+  pages: [{
+    format: "mono1",
+    width: viewport.width,
+    height: viewport.height,
+    stride: Math.ceil(viewport.width / 8),
+    data_b64: Buffer.alloc(Math.ceil(viewport.width / 8) * viewport.height, 0x00).toString("base64"),
+  }],
+}, context);
+assert.equal(uniform.ok, false);
+assert.ok(uniform.errors.some((error) => error.includes("uniform_screen_document")));
+
 console.log("direct-control validator: ok");

package/test/screen-preview.test.mjs

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+
+import { renderScreenDocumentPreviewPages, previewSummary } from "../lib/screen-preview.mjs";
+
+const width = 16;
+const height = 8;
+const stride = 2;
+const bytes = Buffer.alloc(stride * height, 0x00);
+for (let i = 0; i < Math.min(width, height); i += 1) {
+  bytes[i * stride + (i >> 3)] |= 0x80 >> (i & 7);
+}
+
+const preview = renderScreenDocumentPreviewPages({
+  schema: "weclawbot.screen_document.v1",
+  pages: [{
+    format: "mono1",
+    width,
+    height,
+    stride,
+    data_b64: bytes.toString("base64"),
+  }],
+}, { scale: 2 });
+
+assert.equal(preview.length, 1);
+assert.equal(preview[0].width, width * 2);
+assert.equal(preview[0].height, height * 2);
+assert.equal(preview[0].png.subarray(0, 8).toString("hex"), "89504e470d0a1a0a");
+assert.ok(preview[0].bytes > 50);
+assert.match(preview[0].sha256, /^[0-9a-f]{64}$/u);
+
+const summary = previewSummary(preview);
+assert.equal(summary.available, true);
+assert.equal(summary.pages[0].mime_type, "image/png");
+
+console.log("screen-preview renderer: ok");

package/workspace/AGENTS.md

@@ -42,6 +42,17 @@ success only after it exits with success. If the user explicitly asks to
 replace whatever is currently shown, use `--force`; otherwise use the current
 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 firmware receives pixels. Do not send raw text to firmware, and do not
 answer that direct delivery is unavailable before checking the local
 `weclawbotctl` profile.
+
+The content viewport is 368 x 206 mono1 pixels, with one to three content pages.
+The firmware will not split a single pixel page after receiving it; `pages.length`
+is the page count on the physical screen. Preserve user-agent layout preferences,
+visual language, and review habits across plugin upgrades unless they violate
+the hardware limits or the user asks to change them.