@openbrt/weclawbotctl 0.1.8 → 0.1.9

package/README.md

@@ -60,6 +60,11 @@ it does not lay out text, choose fonts, or split pages for agents.
 weclawbotctl screen /path/to/screen-document.json
 ```
 
+`screen` waits for the device status topic by default. It exits successfully
+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.
+
 The package also includes an OpenClaw integration: the `weclawbot-curator`
 skill, `weclawbot_status`, `weclawbot_validate_screen_document`,
 `weclawbot_publish_screen_document`, `weclawbot_validate_activity`,
@@ -254,6 +259,11 @@ the firmware supports forced replacement, use:
 weclawbotctl screen /path/to/screen-document.json --force
 ```
 
+The command waits for the device's `applied`/`rejected` status by default, so
+an Agent must not tell the user the content is on the screen until the command
+returns success. If the device reports `stale_screen_revision`, regenerate the
+document with the current revision or intentionally overwrite with `--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

@@ -9,7 +9,7 @@ import process from "node:process";
 
 import { validateActivity } from "../lib/activity.mjs";
 import { validateScreenDocument } from "../lib/direct-control.mjs";
-import { normalizeCredentials, publishControl, testConnection } from "../lib/mqtt-control.mjs";
+import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "../lib/mqtt-control.mjs";
 
 const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
@@ -202,10 +202,15 @@ async function commandUnbind(values) {
 }
 
 async function commandScreen(values) {
-  const options = parseOptions(values, { credentials: credentialsPath(), force: false });
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    force: false,
+    wait: true,
+    timeout: 12,
+  });
   const file = String(options._[0] || "").trim();
   if (!file || options._.length !== 1) {
-    throw new Error("Usage: weclawbotctl screen <document.json> [--force]");
+    throw new Error("Usage: weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds]");
   }
   const document = JSON.parse(await fs.readFile(file, "utf8"));
   if (options.force) {
@@ -218,13 +223,41 @@ async function commandScreen(values) {
   if (!validation.ok) {
     throw new Error(`Invalid screen document: ${validation.errors.join("; ")}`);
   }
-  await publishControl(await requireCredentials(expandPath(options.credentials)), {
+  const control = {
     schema: "weclawbot.control.v1",
     id: `screen_${crypto.randomUUID()}`,
     kind: "screen_document",
     document,
-  });
-  console.log(JSON.stringify({ ok: true, id: document.id, pages: document.pages.length, force_replace: document.force_replace === true }));
+  };
+  const credentials = await requireCredentials(expandPath(options.credentials));
+  if (options.wait) {
+    const delivery = await publishControlAndWaitStatus(credentials, control, {
+      expectedDetail: document.id,
+      timeoutMs: Math.max(1, Number(options.timeout) || 12) * 1000,
+    });
+    if (delivery.status.kind !== "applied") {
+      throw new Error(`Device rejected screen document: ${delivery.status.detail || "unknown"}`);
+    }
+    console.log(JSON.stringify({
+      ok: true,
+      published: true,
+      applied: true,
+      id: document.id,
+      pages: document.pages.length,
+      force_replace: document.force_replace === true,
+      status: delivery.status,
+    }));
+    return;
+  }
+  await publishControl(credentials, control);
+  console.log(JSON.stringify({
+    ok: true,
+    published: true,
+    applied: null,
+    id: document.id,
+    pages: document.pages.length,
+    force_replace: document.force_replace === true,
+  }));
 }
 
 async function commandActivity(state, values) {
@@ -350,6 +383,13 @@ function parseOptions(values, defaults = {}) {
     const [rawKey, inlineValue] = value.slice(2).split("=", 2);
     const key = rawKey.trim();
     if (!key) continue;
+    if (key.startsWith("no-")) {
+      const positive = key.slice(3);
+      if (typeof options[positive] === "boolean" && inlineValue === undefined) {
+        options[positive] = false;
+        continue;
+      }
+    }
     if (typeof options[key] === "boolean") {
       options[key] = inlineValue === undefined ? true : !/^(0|false|no|off)$/iu.test(inlineValue);
     } else {
@@ -620,7 +660,7 @@ function usage() {
   weclawbotctl unbind --yes
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
-  weclawbotctl screen <document.json> [--force]
+  weclawbotctl screen <document.json> [--force] [--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

@@ -8,7 +8,7 @@ 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";
+import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "./lib/mqtt-control.mjs";
 
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
 
@@ -68,8 +68,10 @@ export default defineToolPlugin({
         device_context: Type.Optional(Type.Any()),
         credentials_path: Type.Optional(Type.String()),
         force_replace: Type.Optional(Type.Boolean()),
+        wait_status: Type.Optional(Type.Boolean()),
+        timeout_seconds: Type.Optional(Type.Number()),
       }, { additionalProperties: false }),
-      execute: async ({ document, device_context, credentials_path, force_replace }) => {
+      execute: async ({ document, device_context, credentials_path, force_replace, wait_status, timeout_seconds }) => {
         const outbound = cloneObject(document);
         if (force_replace) {
           outbound.force_replace = true;
@@ -81,15 +83,34 @@ export default defineToolPlugin({
         if (!validation.ok) {
           return { ok: false, published: false, errors: validation.errors, validation };
         }
-        await publishControl(await requireCredentials(credentials_path), {
+        const control = {
           schema: "weclawbot.control.v1",
           id: `screen_${crypto.randomUUID()}`,
           kind: "screen_document",
           document: outbound,
-        });
+        };
+        const credentials = await requireCredentials(credentials_path);
+        if (wait_status !== false) {
+          const delivery = await publishControlAndWaitStatus(credentials, control, {
+            expectedDetail: outbound.id,
+            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",
+            id: outbound.id,
+            pages: outbound.pages.length,
+            force_replace: outbound.force_replace === true,
+            status: delivery.status,
+          };
+        }
+        await publishControl(credentials, control);
         return {
           ok: true,
           published: true,
+          applied: null,
           id: outbound.id,
           pages: outbound.pages.length,
           force_replace: outbound.force_replace === true,

package/lib/mqtt-control.mjs

@@ -2,27 +2,33 @@ import mqtt from "mqtt";
 
 export async function publishControl(credentials, control) {
   const config = normalizeCredentials(credentials);
-  if (!control || typeof control !== "object" || control.schema !== "weclawbot.control.v1") {
-    throw new Error("invalid_control_message");
+  validateControl(control);
+  const client = connectMqtt(config);
+  try {
+    await onceConnected(client);
+    await publishJson(client, config.controlTopic, control);
+  } finally {
+    client.end(true);
   }
-  const client = mqtt.connect(config.url, {
-    clientId: config.clientId,
-    username: config.username,
-    password: config.password,
-    clean: true,
-    reconnectPeriod: 0,
-    connectTimeout: 12_000,
-    protocolVersion: 5,
-    properties: { sessionExpiryInterval: 0 },
-  });
+}
+
+export async function publishControlAndWaitStatus(credentials, control, options = {}) {
+  const config = normalizeCredentials(credentials);
+  validateControl(control);
+  if (!config.statusTopic) throw new Error("agent_status_topic_missing");
+  const timeoutMs = Math.max(1000, Number(options.timeoutMs || 12_000));
+  const expectedDetail = string(options.expectedDetail);
+  const client = connectMqtt(config);
   try {
     await onceConnected(client);
-    await new Promise((resolve, reject) => {
-      client.publish(config.controlTopic, JSON.stringify(control), { qos: 1, retain: false }, (error) => {
-        if (error) reject(error);
-        else resolve();
-      });
+    await subscribe(client, config.statusTopic);
+    const statusPromise = waitForStatus(client, {
+      timeoutMs,
+      expectedDetail,
     });
+    await publishJson(client, config.controlTopic, control);
+    const status = await statusPromise;
+    return { ok: status.kind === "applied", status };
   } finally {
     client.end(true);
   }
@@ -30,16 +36,7 @@ export async function publishControl(credentials, control) {
 
 export async function testConnection(credentials) {
   const config = normalizeCredentials(credentials);
-  const client = mqtt.connect(config.url, {
-    clientId: config.clientId,
-    username: config.username,
-    password: config.password,
-    clean: true,
-    reconnectPeriod: 0,
-    connectTimeout: 12_000,
-    protocolVersion: 5,
-    properties: { sessionExpiryInterval: 0 },
-  });
+  const client = connectMqtt(config);
   try {
     await onceConnected(client);
   } finally {
@@ -62,11 +59,91 @@ export function normalizeCredentials(value) {
   const password = string(mqttConfig?.password);
   const clientId = string(mqttConfig?.client_id);
   const controlTopic = string(topics?.control);
+  const statusTopic = string(topics?.status);
   if (!url || !username || !password || !clientId || !controlTopic) {
     throw new Error("agent_credentials_incomplete");
   }
   if (!/^wss:\/\//u.test(url)) throw new Error("agent_mqtt_requires_wss");
-  return { url, username, password, clientId, controlTopic };
+  return { url, username, password, clientId, controlTopic, statusTopic };
+}
+
+function connectMqtt(config) {
+  return mqtt.connect(config.url, {
+    clientId: config.clientId,
+    username: config.username,
+    password: config.password,
+    clean: true,
+    reconnectPeriod: 0,
+    connectTimeout: 12_000,
+    protocolVersion: 5,
+    properties: { sessionExpiryInterval: 0 },
+  });
+}
+
+function validateControl(control) {
+  if (!control || typeof control !== "object" || control.schema !== "weclawbot.control.v1") {
+    throw new Error("invalid_control_message");
+  }
+}
+
+function publishJson(client, topic, value) {
+  return new Promise((resolve, reject) => {
+    client.publish(topic, JSON.stringify(value), { qos: 1, retain: false }, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}
+
+function subscribe(client, topic) {
+  return new Promise((resolve, reject) => {
+    client.subscribe(topic, { qos: 1 }, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}
+
+function waitForStatus(client, { timeoutMs, expectedDetail }) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => finish(new Error("device_status_timeout")), timeoutMs);
+    const finish = (error, status) => {
+      clearTimeout(timeout);
+      client.removeListener("message", onMessage);
+      client.removeListener("error", onError);
+      if (error) reject(error);
+      else resolve(status);
+    };
+    const onError = (error) => finish(error);
+    const onMessage = (_topic, payload) => {
+      const status = parseStatus(payload);
+      if (!status) return;
+      if (status.kind === "applied") {
+        if (expectedDetail && status.detail !== expectedDetail) return;
+        finish(null, status);
+      } else if (status.kind === "rejected") {
+        finish(null, status);
+      }
+    };
+    client.on("message", onMessage);
+    client.once("error", onError);
+  });
+}
+
+function parseStatus(payload) {
+  try {
+    const status = JSON.parse(payload.toString("utf8"));
+    if (status?.schema !== "weclawbot.device_status.v1") return null;
+    if (status.kind !== "applied" && status.kind !== "rejected") return null;
+    return {
+      schema: status.schema,
+      kind: status.kind,
+      device_id: string(status.device_id),
+      detail: string(status.detail),
+    };
+  } catch {
+    return null;
+  }
 }
 
 function onceConnected(client) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbrt/weclawbotctl",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "WeClawBot pairing and screen-control CLI for local AI agents.",
   "type": "module",
   "license": "MIT",

package/skills/weclawbot-curator/SKILL.md

@@ -59,6 +59,12 @@ OpenClaw Canvas for requests that mention WeClawBot, the physical screen, or
 not send raw text to firmware. The agent owns text layout, font choice, image
 rasterization, and page splitting; the device consumes pixels.
 
+`weclawbotctl screen` and `weclawbot_publish_screen_document` wait for the
+device status topic by default. Treat only `applied` as success. If the device
+returns `rejected`, tell the user the real rejection reason. Use
+`force_replace` or `weclawbotctl screen --force` only when the user explicitly
+intends to overwrite the currently shown BYOA screen.
+
 Only return the normal WeChat decision shape below when processing an explicit
 `WECLAWBOT_CURATOR_EVENT` envelope.
 

package/workspace/AGENTS.md

@@ -37,6 +37,11 @@ content viewport, then publish it:
 weclawbotctl screen /path/to/screen-document.json
 ```
 
+This command waits for firmware `applied`/`rejected` status by default. Report
+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`.
+
 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.