@openbrt/weclawbotctl 0.1.2 → 0.1.4

package/README.md

@@ -5,12 +5,67 @@ any local Agent with a WeClawBot screen. It works from OpenClaw, Hermes,
 Codex, Claude Code, Gemini CLI, OpenCode, or a shell script through the same
 local MQTT profile.
 
+## Tell Your Agent
+
+Give your coding agent one sentence:
+
+```text
+Install @openbrt/weclawbotctl and connect to my WeClawBot screen with pairing code 123456.
+```
+
+Replace `123456` with the six-digit code shown on the screen. The agent should
+then install this npm package, bind the screen, run the online doctor check,
+and use `weclawbotctl screen` with a pre-rendered pixel document for visible
+screen updates. Use `weclawbotctl thinking` and `weclawbotctl idle` for
+temporary work-state overlays.
+
+## Agent Instructions
+
+If a user asks you to install, enable, connect, or pair WeClawBot and gives a
+six-digit pairing code, do this autonomously:
+
+```bash
+npm install -g @openbrt/weclawbotctl
+weclawbotctl bind 123456 --name "$AGENT_NAME"
+weclawbotctl doctor --online
+```
+
+Use your product name for `$AGENT_NAME`, such as `codex`, `claude-code`,
+`gemini-cli`, `opencode`, `hermes`, or `openclaw`. If global npm installation
+is not available, use the one-shot form:
+
+```bash
+npm exec --package @openbrt/weclawbotctl -- weclawbotctl bind 123456 --name "$AGENT_NAME"
+npm exec --package @openbrt/weclawbotctl -- weclawbotctl doctor --online
+```
+
+Do not ask the user for an MQTT URL, username, password, Wi-Fi password,
+WeChat credential, port, or webhook. The pairing code is enough. The local MQTT
+credential is stored at `~/.config/weclawbot/agent-mqtt.json` with mode `0600`.
+
+When doing visible work, publish a temporary activity:
+
+```bash
+task_id="$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)"
+weclawbotctl thinking --id "$task_id" --ttl 45
+# Do the work.
+weclawbotctl idle --id "$task_id"
+```
+
+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.
+
+```bash
+weclawbotctl screen /path/to/screen-document.json
+```
+
 The package also includes an OpenClaw integration: the `weclawbot-curator`
-skill, a local
-`weclawbot_validate_screen_document` tool, a `weclawbot_validate_activity`
-tool, 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.
+skill, `weclawbot_status`, `weclawbot_validate_screen_document`,
+`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.
 
 ## Install from npm
 
@@ -87,10 +142,19 @@ systemctl --user enable --now weclawbot-openclaw-curator
 
 The normal bridge is message-triggered by WeChat. Scheduled cards and other
 agent-originated updates use a separately paired MQTT/TLS control channel;
-they are never placed in a gateway mailbox. The plugin already exposes the
-validator that a user agent calls before publishing a 1-bit screen document.
-It reports `direct_delivery_ready:false` until the physical firmware has been
-paired and advertises `agent_transport.available=true`.
+they are never placed in a gateway mailbox. A paired Agent can publish a
+pre-rendered screen document immediately:
+
+```bash
+weclawbotctl doctor --online
+weclawbotctl screen /path/to/screen-document.json
+```
+
+The plugin exposes both validators and publish tools. The validator reports
+`direct_delivery_ready:false` when a supplied event contract says that specific
+inbound event cannot use the live document path, but that does not disable a
+locally paired `weclawbotctl` profile. Before saying direct screen delivery is
+unavailable, run `weclawbotctl status` or `weclawbotctl doctor --online`.
 
 The pairing UX deliberately requires no user-supplied Agent endpoint: choose
 **自定义智能体** in the device configurator, then enter the six-digit code shown
@@ -141,15 +205,24 @@ weclawbotctl thinking --id "$task_id" --ttl 45
 weclawbotctl idle --id "$task_id"
 ```
 
-To put a pre-rendered monochrome document on screen, pass its JSON file to the
-same scoped MQTT credential. The document must use the live revision in the
-last `device_context` (an empty revision is valid for the first document), one
-to three `mono1` pages, and a future UTC expiry:
+To put content on screen, pass a pre-rendered monochrome document to the same
+credential. The document must use the live revision in the last
+`device_context` (an empty revision is valid for the first document), one to
+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:
 
 ```bash
 weclawbotctl screen /path/to/screen-document.json
 ```
 
+When the user explicitly asks to overwrite whatever is currently shown, and
+the firmware supports forced replacement, use:
+
+```bash
+weclawbotctl screen /path/to/screen-document.json --force
+```
+
 These commands use MQTT/TLS directly, publish QoS 1 without retain, and
 never create an offline command queue. See
 `docs/agent-direct-control-protocol.md` in the firmware repository for the

package/bin/weclawbotctl.mjs

@@ -198,12 +198,16 @@ async function commandUnbind(values) {
 }
 
 async function commandScreen(values) {
-  const options = parseOptions(values, { credentials: credentialsPath() });
+  const options = parseOptions(values, { credentials: credentialsPath(), force: false });
   const file = String(options._[0] || "").trim();
   if (!file || options._.length !== 1) {
-    throw new Error("Usage: weclawbotctl screen <document.json>");
+    throw new Error("Usage: weclawbotctl screen <document.json> [--force]");
   }
   const document = JSON.parse(await fs.readFile(file, "utf8"));
+  if (options.force) {
+    document.force_replace = true;
+    document.base_revision = "*";
+  }
   const validation = validateScreenDocument(document, {
     agent_transport: { available: true, screen_document_available: true },
   });
@@ -216,7 +220,7 @@ async function commandScreen(values) {
     kind: "screen_document",
     document,
   });
-  console.log(JSON.stringify({ ok: true, id: document.id, pages: document.pages.length }));
+  console.log(JSON.stringify({ ok: true, id: document.id, pages: document.pages.length, force_replace: document.force_replace === true }));
 }
 
 async function commandActivity(state, values) {
@@ -353,5 +357,5 @@ function usage() {
   weclawbotctl unbind --yes
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
-  weclawbotctl screen <document.json>`);
+  weclawbotctl screen <document.json> [--force]`);
 }

package/index.mjs

@@ -1,16 +1,54 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
 import { Type } from "typebox";
 import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
 
 import { validateActivity } from "./lib/activity.mjs";
 import { validateScreenDocument } from "./lib/direct-control.mjs";
+import { normalizeCredentials, publishControl, testConnection } from "./lib/mqtt-control.mjs";
+
+const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
 
-// The long-running curator bridge remains a separate service. This plugin's
-// tool is local, deterministic, and contains no credential or network access.
+// 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({
   id: "weclawbot",
   name: "WeClawBot",
-  description: "WeClawBot screen-curation skill pack and direct-control validator.",
+  description: "WeClawBot screen-curation skill pack and direct MQTT control tools.",
   tools: (tool) => [
+    tool({
+      name: "weclawbot_status",
+      label: "Check WeClawBot pairing",
+      description: "Read the local WeClawBot MQTT pairing profile and optionally test the live MQTT connection.",
+      parameters: Type.Object({
+        credentials_path: Type.Optional(Type.String()),
+        online: Type.Optional(Type.Boolean()),
+      }, { additionalProperties: false }),
+      execute: async ({ credentials_path, online }) => {
+        const file = expandPath(credentials_path || DEFAULT_CREDENTIALS_PATH);
+        const payload = await readCredentials(file);
+        if (!payload) {
+          return { ok: false, paired: false, credentials_path: file, error: "not_paired" };
+        }
+        const config = normalizeCredentials(payload);
+        const result = {
+          ok: true,
+          paired: true,
+          credentials_path: file,
+          binding: payload.binding || {},
+          mqtt: maskedMqtt(config, payload.mqtt?.topics || {}),
+        };
+        if (online) {
+          await testConnection(payload);
+          result.online = true;
+        }
+        return result;
+      },
+    }),
     tool({
       name: "weclawbot_validate_screen_document",
       label: "Validate WeClawBot screen document",
@@ -21,6 +59,43 @@ export default defineToolPlugin({
       }, { additionalProperties: false }),
       execute: ({ document, device_context }) => validateScreenDocument(document, device_context),
     }),
+    tool({
+      name: "weclawbot_publish_screen_document",
+      label: "Publish WeClawBot screen document",
+      description: "Validate and publish a pre-rendered mono1 screen document through the paired local MQTT profile. The document must already contain pixels; this tool does not lay out text.",
+      parameters: Type.Object({
+        document: Type.Any(),
+        device_context: Type.Optional(Type.Any()),
+        credentials_path: Type.Optional(Type.String()),
+        force_replace: Type.Optional(Type.Boolean()),
+      }, { additionalProperties: false }),
+      execute: async ({ document, device_context, credentials_path, force_replace }) => {
+        const outbound = cloneObject(document);
+        if (force_replace) {
+          outbound.force_replace = true;
+          outbound.base_revision = "*";
+        }
+        const validation = validateScreenDocument(outbound, device_context || {
+          agent_transport: { available: true, screen_document_available: true },
+        });
+        if (!validation.ok) {
+          return { ok: false, published: false, errors: validation.errors, validation };
+        }
+        await publishControl(await requireCredentials(credentials_path), {
+          schema: "weclawbot.control.v1",
+          id: `screen_${crypto.randomUUID()}`,
+          kind: "screen_document",
+          document: outbound,
+        });
+        return {
+          ok: true,
+          published: true,
+          id: outbound.id,
+          pages: outbound.pages.length,
+          force_replace: outbound.force_replace === true,
+        };
+      },
+    }),
     tool({
       name: "weclawbot_validate_activity",
       label: "Validate WeClawBot activity",
@@ -31,5 +106,75 @@ export default defineToolPlugin({
       }, { additionalProperties: false }),
       execute: ({ activity, device_context }) => validateActivity(activity, device_context),
     }),
+    tool({
+      name: "weclawbot_publish_activity",
+      label: "Publish WeClawBot activity",
+      description: "Validate and publish a short-lived thinking or idle activity through the paired local MQTT profile.",
+      parameters: Type.Object({
+        activity: Type.Any(),
+        device_context: Type.Optional(Type.Any()),
+        credentials_path: Type.Optional(Type.String()),
+      }, { additionalProperties: false }),
+      execute: async ({ activity, device_context, credentials_path }) => {
+        const validation = validateActivity(activity, device_context || {
+          agent_transport: { available: true, activity_available: true },
+        });
+        if (!validation.ok) {
+          return { ok: false, published: false, errors: validation.errors, validation };
+        }
+        await publishControl(await requireCredentials(credentials_path), {
+          schema: "weclawbot.control.v1",
+          id: `activity_${crypto.randomUUID()}`,
+          kind: "activity",
+          activity,
+        });
+        return {
+          ok: true,
+          published: true,
+          state: activity.state,
+          correlation_id: activity.correlation_id,
+        };
+      },
+    }),
   ],
 });
+
+async function requireCredentials(credentialsPath) {
+  const file = expandPath(credentialsPath || DEFAULT_CREDENTIALS_PATH);
+  const payload = await readCredentials(file);
+  if (!payload) throw new Error(`WeClawBot is not paired. Run: weclawbotctl bind <six-digit-code>`);
+  return payload;
+}
+
+async function readCredentials(file) {
+  try {
+    const payload = JSON.parse(await fs.readFile(file, "utf8"));
+    return payload && typeof payload === "object" ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+function expandPath(value) {
+  const raw = String(value || DEFAULT_CREDENTIALS_PATH);
+  return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+}
+
+function cloneObject(value) {
+  if (!value || typeof value !== "object") throw new Error("document must be an object");
+  return JSON.parse(JSON.stringify(value));
+}
+
+function maskedMqtt(config, topics) {
+  return {
+    url: config.url,
+    client_id: config.clientId,
+    username: config.username,
+    password: "********",
+    topics: {
+      control: config.controlTopic,
+      events: topics.events || "",
+      status: topics.status || "",
+    },
+  };
+}

package/lib/direct-control.mjs

@@ -41,6 +41,9 @@ export function validateScreenDocument(value, suppliedContext) {
   if (document.kind !== "replace") errors.push("kind must be replace");
   if (!string(document.id)) errors.push("id is required");
   if (typeof document.base_revision !== "string") errors.push("base_revision must be a string (empty for the first document)");
+  if ("force_replace" in document && typeof document.force_replace !== "boolean") {
+    errors.push("force_replace must be a boolean when present");
+  }
   if (!isFutureIso(document.expires_at)) errors.push("expires_at must be a future UTC RFC3339 timestamp");
   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`);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "weclawbot",
   "name": "WeClawBot",
-  "description": "Lets OpenClaw curate WeChat messages and validate live screen documents for a paired WeClawBot screen.",
+  "description": "Lets OpenClaw pair with and push content to a WeClawBot screen over MQTT.",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openbrt/weclawbotctl",
-  "version": "0.1.2",
-  "description": "WeClawBot MQTT pairing CLI and direct-control tools for local AI agents.",
+  "version": "0.1.4",
+  "description": "WeClawBot pairing and screen-control CLI for local AI agents.",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -10,7 +10,11 @@
     "esp32",
     "e-paper",
     "openclaw",
-    "agent"
+    "agent",
+    "codex",
+    "claude-code",
+    "gemini-cli",
+    "hermes"
   ],
   "engines": {
     "node": ">=20"

package/skills/weclawbot-curator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weclawbot-curator
-description: Curate WeChat messages into thoughtful monochrome WeClawBot screen decisions when a WeClawBot curator event is supplied.
+description: Curate WeClawBot screen events and guide direct MQTT pushes for paired physical screens.
 metadata: { "openclaw": { "always": true } }
 ---
 
@@ -35,11 +35,32 @@ away the relationship.
 
 ## Direct agent control
 
-`wechat_transport` describes the existing iLink long-poll event path. It is
-inbound only. Never claim it lets an agent push a periodic or scheduled card.
+`wechat_transport` describes the official-mode iLink long-poll event path. It
+is inbound only. In BYOA mode it may be advertised as `mode=disabled` and
+`direction=ignored`; do not use firmware WeChat as an ingress or reply channel.
+Never claim it lets an agent push a periodic or scheduled card.
+
+`agent_transport.available` inside an inbound curator event is the live
+firmware contract for that event. It is not the authority for a locally paired
+`weclawbotctl` profile. If a user directly asks to send text, a status card, a
+timer, or other agent-originated content to the screen, first run
+`weclawbotctl status` or `weclawbotctl doctor --online`, or call
+`weclawbot_status` with `online:true`. If the profile is paired and online,
+render the content into a `weclawbot.screen_document.v1` pixel document and
+publish it with:
+
+```bash
+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.
 
-When `agent_transport.available` is `false`, return the normal WeChat decision
-shape below. Do not claim that a direct update reached the device.
+Only return the normal WeChat decision shape below when processing an explicit
+`WECLAWBOT_CURATOR_EVENT` envelope.
 
 When a paired device advertises `agent_transport.available=true`, an external
 agent may publish a complete `weclawbot.screen_document.v1` over the live
@@ -56,8 +77,8 @@ model API key.
 Treat “发到屏上” as one capability regardless of its origin. A WeChat event
 has a reply target: return `user_reply` only when it genuinely helps the
 sender. A timer, automation, or direct Agent request has no WeChat reply
-target: publish the same screen document and use the device `applied` or
-`rejected` event as its result.
+target: publish a validated screen document and use the device `applied` or
+`rejected` event as the result.
 
 ## Thinking activity
 

package/workspace/AGENTS.md

@@ -17,3 +17,26 @@ details in `note.body`; do not replace `note` with `content`, `note_name`, or a
 wrapper object. For a list, preserve existing categories and group new items by
 meaning. For greetings, acknowledgements, or content with no future value, use
 `ignore` or `reply_only`.
+
+## Direct Screen Requests
+
+When the user asks to put something on the WeClawBot screen, treat WeClawBot
+as the physical ESP32 e-paper display, not OpenClaw Canvas. First check the
+local pairing:
+
+```bash
+weclawbotctl status
+weclawbotctl doctor --online
+```
+
+If it is paired and online, render the requested text, status, image, or chart
+into a `weclawbot.screen_document.v1` with 1-bit pages for the firmware
+content viewport, then publish it:
+
+```bash
+weclawbotctl screen /path/to/screen-document.json
+```
+
+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.