@openbrt/weclawbotctl 0.1.0

package/bin/weclawbotctl.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+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";
+
+const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
+const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
+
+const [command, ...args] = process.argv.slice(2);
+const commands = new Set(["bind", "status", "doctor", "export", "unbind", "thinking", "idle", "screen"]);
+if (!commands.has(command)) {
+  usage();
+  process.exit(64);
+}
+
+try {
+  if (command === "bind") await commandBind(args);
+  else if (command === "status") await commandStatus(args);
+  else if (command === "doctor") await commandDoctor(args);
+  else if (command === "export") await commandExport(args);
+  else if (command === "unbind") await commandUnbind(args);
+  else if (command === "screen") await commandScreen(args);
+  else await commandActivity(command, args);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+async function commandBind(values) {
+  const options = parseOptions(values, {
+    name: "user-agent",
+    endpoint: process.env.WEC_BYOA_ENDPOINT || DEFAULT_ENDPOINT,
+    credentials: credentialsPath(),
+  });
+  const code = String(options._[0] || "").replace(/\D/gu, "");
+  if (!/^\d{6}$/u.test(code)) {
+    throw new Error("Usage: weclawbotctl bind <six-digit-code> [--name agent-name]");
+  }
+  const response = await fetch(options.endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({
+      schema: "weclawbot.byoa.v1",
+      operation: "claim",
+      code,
+      agent_name: String(options.name || "user-agent").slice(0, 80),
+    }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok || !payload?.ok || payload?.schema !== "weclawbot.byoa.agent_credentials.v1") {
+    throw new Error(`WeClawBot pairing failed: ${payload?.error || `HTTP ${response.status}`}`);
+  }
+
+  const file = expandPath(options.credentials);
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await fs.writeFile(file, `${JSON.stringify({
+    schema: "weclawbot.agent_credentials.v1",
+    binding: payload.binding,
+    mqtt: payload.mqtt,
+    delivery: payload.delivery,
+    created_at: new Date().toISOString(),
+  }, null, 2)}\n`, { mode: 0o600 });
+  await fs.chmod(file, 0o600);
+  console.log(`WeClawBot paired with ${payload.binding.device_id}. Credentials saved to ${file}.`);
+}
+
+async function commandStatus(values) {
+  const options = parseOptions(values, { credentials: credentialsPath(), json: false });
+  const file = expandPath(options.credentials);
+  const payload = await readCredentials(file);
+  if (!payload) {
+    const status = { ok: false, paired: false, credentials_path: file };
+    printStatus(status, options.json);
+    process.exitCode = 1;
+    return;
+  }
+  const config = normalizeCredentials(payload);
+  const stat = await fs.stat(file).catch(() => null);
+  printStatus({
+    ok: true,
+    paired: true,
+    credentials_path: file,
+    file_mode: stat ? modeString(stat.mode) : "",
+    binding: payload.binding || {},
+    mqtt: maskedMqtt(config, payload.mqtt?.topics || {}),
+    delivery: payload.delivery || {},
+  }, options.json);
+}
+
+async function commandDoctor(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    json: false,
+    online: false,
+  });
+  const file = expandPath(options.credentials);
+  const checks = [];
+  const payload = await readCredentials(file);
+  checks.push({ name: "credentials_file", ok: Boolean(payload), detail: file });
+  if (!payload) {
+    printDoctor(checks, options.json);
+    process.exitCode = 1;
+    return;
+  }
+  const stat = await fs.stat(file).catch(() => null);
+  checks.push({
+    name: "credentials_permissions",
+    ok: Boolean(stat) && (stat.mode & 0o077) === 0,
+    detail: stat ? modeString(stat.mode) : "missing",
+  });
+  let config = null;
+  try {
+    config = normalizeCredentials(payload);
+    checks.push({ name: "mqtt_profile", ok: true, detail: `${config.url} ${config.clientId}` });
+    checks.push({ name: "mqtt_url_tls", ok: config.url.startsWith("wss://"), detail: config.url });
+    checks.push({
+      name: "client_id_contains_no_secret",
+      ok: !/(token|secret|password|passwd|key)/iu.test(config.clientId),
+      detail: config.clientId,
+    });
+  } catch (error) {
+    checks.push({ name: "mqtt_profile", ok: false, detail: error.message });
+  }
+  if (options.online && config) {
+    try {
+      await testConnection(payload);
+      checks.push({ name: "mqtt_online", ok: true, detail: "connected" });
+    } catch (error) {
+      checks.push({ name: "mqtt_online", ok: false, detail: error.message });
+    }
+  }
+  printDoctor(checks, options.json);
+  if (checks.some((check) => !check.ok)) process.exitCode = 1;
+}
+
+async function commandExport(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    format: "env",
+    output: "",
+    "include-secret": false,
+  });
+  const payload = await requireCredentials(expandPath(options.credentials));
+  const config = normalizeCredentials(payload);
+  const includeSecret = Boolean(options["include-secret"]);
+  let body = "";
+  if (options.format === "json") {
+    body = `${JSON.stringify(maskedExport(payload, includeSecret), null, 2)}\n`;
+  } else if (options.format === "env") {
+    body = [
+      `WEC_MQTT_URL=${shellValue(config.url)}`,
+      `WEC_MQTT_CLIENT_ID=${shellValue(config.clientId)}`,
+      `WEC_MQTT_USERNAME=${shellValue(config.username)}`,
+      `WEC_MQTT_PASSWORD=${shellValue(includeSecret ? config.password : "********")}`,
+      `WEC_MQTT_CONTROL_TOPIC=${shellValue(config.controlTopic)}`,
+      "",
+    ].join("\n");
+  } else if (options.format === "mosquitto") {
+    body = [
+      `url ${config.url}`,
+      `id ${config.clientId}`,
+      `username ${config.username}`,
+      `password ${includeSecret ? config.password : "********"}`,
+      "protocol-version mqttv5",
+      "clean-session true",
+      "",
+    ].join("\n");
+  } else {
+    throw new Error("export format must be env, json, or mosquitto");
+  }
+  if (options.output) {
+    const file = expandPath(options.output);
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    await fs.writeFile(file, body, { mode: includeSecret ? 0o600 : 0o644 });
+    if (includeSecret) await fs.chmod(file, 0o600);
+    console.log(`Wrote ${options.format} profile to ${file}.`);
+  } else {
+    process.stdout.write(body);
+  }
+}
+
+async function commandUnbind(values) {
+  const options = parseOptions(values, { credentials: credentialsPath(), yes: false });
+  if (!options.yes) {
+    throw new Error("This only removes the local credential file. Re-run with --yes.");
+  }
+  const file = expandPath(options.credentials);
+  await fs.rm(file, { force: true });
+  console.log(`Removed local WeClawBot credentials: ${file}`);
+}
+
+async function commandScreen(values) {
+  const options = parseOptions(values, { credentials: credentialsPath() });
+  const file = String(options._[0] || "").trim();
+  if (!file || options._.length !== 1) {
+    throw new Error("Usage: weclawbotctl screen <document.json>");
+  }
+  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("; ")}`);
+  }
+  await publishControl(await requireCredentials(expandPath(options.credentials)), {
+    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 }));
+}
+
+async function commandActivity(state, values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    ttl: 45,
+    id: "",
+  });
+  const correlationId = options.id || crypto.randomUUID();
+  const activity = {
+    schema: "weclawbot.activity.v1",
+    state,
+    correlation_id: correlationId,
+    ...(state === "thinking" ? { ttl_seconds: Number(options.ttl) } : {}),
+  };
+  const validation = validateActivity(activity, { agent_transport: { available: true, activity_available: true } });
+  if (!validation.ok) {
+    throw new Error(`Invalid activity: ${validation.errors.join("; ")}`);
+  }
+
+  await publishControl(await requireCredentials(expandPath(options.credentials)), {
+    schema: "weclawbot.control.v1",
+    id: `activity_${crypto.randomUUID()}`,
+    kind: "activity",
+    activity,
+  });
+  console.log(JSON.stringify({ ok: true, state: activity.state, correlation_id: correlationId }));
+}
+
+function parseOptions(values, defaults = {}) {
+  const options = { ...defaults, _: [] };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (!value.startsWith("--")) {
+      options._.push(value);
+      continue;
+    }
+    const [rawKey, inlineValue] = value.slice(2).split("=", 2);
+    const key = rawKey.trim();
+    if (!key) continue;
+    if (typeof options[key] === "boolean") {
+      options[key] = inlineValue === undefined ? true : !/^(0|false|no|off)$/iu.test(inlineValue);
+    } else {
+      options[key] = inlineValue === undefined ? String(values[++index] || "") : inlineValue;
+    }
+  }
+  return options;
+}
+
+function credentialsPath() {
+  return process.env.WEC_AGENT_CREDENTIALS_PATH || DEFAULT_CREDENTIALS_PATH;
+}
+
+async function readCredentials(file) {
+  try {
+    const payload = JSON.parse(await fs.readFile(file, "utf8"));
+    return payload && typeof payload === "object" ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+async function requireCredentials(file) {
+  const payload = await readCredentials(file);
+  if (!payload) throw new Error(`WeClawBot is not paired. Run: weclawbotctl bind <six-digit-code>`);
+  return payload;
+}
+
+function expandPath(value) {
+  const raw = String(value || DEFAULT_CREDENTIALS_PATH);
+  return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+}
+
+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 || "",
+    },
+  };
+}
+
+function maskedExport(payload, includeSecret) {
+  const copy = JSON.parse(JSON.stringify(payload));
+  if (!includeSecret && copy?.mqtt?.password) copy.mqtt.password = "********";
+  return copy;
+}
+
+function printStatus(status, json) {
+  if (json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+  if (!status.paired) {
+    console.log(`WeClawBot not paired. Credentials: ${status.credentials_path}`);
+    return;
+  }
+  console.log(`WeClawBot paired: ${status.binding?.device_id || "device"}`);
+  console.log(`Credentials: ${status.credentials_path} (${status.file_mode || "unknown mode"})`);
+  console.log(`MQTT: ${status.mqtt.url}`);
+  console.log(`Client ID: ${status.mqtt.client_id}`);
+  console.log(`Control topic: ${status.mqtt.topics.control}`);
+}
+
+function printDoctor(checks, json) {
+  if (json) {
+    console.log(JSON.stringify({ ok: checks.every((check) => check.ok), checks }, null, 2));
+    return;
+  }
+  for (const check of checks) {
+    console.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.detail}`);
+  }
+}
+
+function shellValue(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function modeString(mode) {
+  return `0${(mode & 0o777).toString(8)}`;
+}
+
+function usage() {
+  console.error(`Usage:
+  weclawbotctl bind <six-digit-code> [--name agent-name]
+  weclawbotctl status [--json]
+  weclawbotctl doctor [--online] [--json]
+  weclawbotctl export [--format env|json|mosquitto] [--include-secret] [--output file]
+  weclawbotctl unbind --yes
+  weclawbotctl thinking [--ttl seconds] [--id correlation-id]
+  weclawbotctl idle [--id correlation-id]
+  weclawbotctl screen <document.json>`);
+}

package/index.mjs

@@ -0,0 +1,35 @@
+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";
+
+// The long-running curator bridge remains a separate service. This plugin's
+// tool is local, deterministic, and contains no credential or network access.
+export default defineToolPlugin({
+  id: "weclawbot",
+  name: "WeClawBot",
+  description: "WeClawBot screen-curation skill pack and direct-control validator.",
+  tools: (tool) => [
+    tool({
+      name: "weclawbot_validate_screen_document",
+      label: "Validate WeClawBot screen document",
+      description: "Validate a candidate direct screen document against the firmware-supplied device_context. This does not send or queue anything.",
+      parameters: Type.Object({
+        document: Type.Any(),
+        device_context: Type.Optional(Type.Any()),
+      }, { additionalProperties: false }),
+      execute: ({ document, device_context }) => validateScreenDocument(document, device_context),
+    }),
+    tool({
+      name: "weclawbot_validate_activity",
+      label: "Validate WeClawBot activity",
+      description: "Validate a temporary thinking or idle activity message. It does not send or queue anything.",
+      parameters: Type.Object({
+        activity: Type.Any(),
+        device_context: Type.Optional(Type.Any()),
+      }, { additionalProperties: false }),
+      execute: ({ activity, device_context }) => validateActivity(activity, device_context),
+    }),
+  ],
+});

package/lib/activity.mjs

@@ -0,0 +1,34 @@
+const STATES = new Set(["thinking", "idle"]);
+
+export function validateActivity(value, suppliedContext) {
+  const context = suppliedContext && typeof suppliedContext === "object" ? suppliedContext : {};
+  const transport = context.agent_transport || null;
+  const activity = value && typeof value === "object" ? value : null;
+  const errors = [];
+  if (!activity) {
+    errors.push("activity must be an object");
+  } else {
+    if (activity.schema !== "weclawbot.activity.v1") {
+      errors.push("schema must be weclawbot.activity.v1");
+    }
+    if (!STATES.has(activity.state)) {
+      errors.push("state must be thinking or idle");
+    }
+    if (typeof activity.correlation_id !== "string" || !activity.correlation_id.trim()) {
+      errors.push("correlation_id is required");
+    }
+    if (activity.state === "thinking") {
+      const ttl = Number(activity.ttl_seconds);
+      if (!Number.isInteger(ttl) || ttl < 5 || ttl > 120) {
+        errors.push("thinking ttl_seconds must be an integer from 5 to 120");
+      }
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    errors,
+    agent_transport: transport,
+    direct_delivery_ready: transport?.activity_available === true || transport?.available === true,
+    delivery: { qos: 1, retained: false, clean_start: true, session_expiry_seconds: 0 },
+  };
+}

package/lib/direct-control.mjs

@@ -0,0 +1,110 @@
+const DEFAULT_CONTEXT = {
+  schema: "weclawbot.device_context.v1",
+  canvas: { width: 400, height: 300, color: "mono1", refresh: "reflective_slow" },
+  content_viewport: {
+    id: "content", x: 16, y: 42, width: 368, height: 206,
+    format: "mono1", max_pages: 3, auto_page_seconds: 12,
+  },
+  chrome: { owner: "firmware", reserved: "status_bar,footer" },
+  agent_transport: {
+    mode: "mqtt_tls_pubsub",
+    state: "provisioning_required",
+    available: false,
+    screen_document_available: false,
+    activity_available: false,
+    queue_or_mailbox: false,
+    delivery: "live_qos1_no_offline_queue",
+    session_expiry_seconds: 0,
+    recommended_min_update_interval_ms: 60000,
+  },
+};
+
+export function resolveDeviceContext(value) {
+  if (!value || typeof value !== "object" || value.schema !== "weclawbot.device_context.v1") {
+    return structuredClone(DEFAULT_CONTEXT);
+  }
+  return value;
+}
+
+export function validateScreenDocument(value, suppliedContext) {
+  const context = resolveDeviceContext(suppliedContext);
+  const errors = [];
+  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"));
+  if (document.schema !== "weclawbot.screen_document.v1") {
+    errors.push("schema must be weclawbot.screen_document.v1");
+  }
+  if (document.target !== viewport.id) {
+    errors.push(`target must be ${viewport.id}`);
+  }
+  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 (!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`);
+  } else {
+    document.pages.forEach((page, index) => validatePage(page, index, viewport, errors));
+  }
+  return result(context, errors);
+}
+
+function validatePage(page, index, viewport, errors) {
+  if (!page || typeof page !== "object") {
+    errors.push(`pages[${index}] must be an object`);
+    return;
+  }
+  const width = Number(page.width);
+  const height = Number(page.height);
+  const stride = Number(page.stride);
+  if (page.format !== "mono1") errors.push(`pages[${index}].format must be mono1`);
+  if (!Number.isInteger(width) || width < 1 || width > viewport.width) {
+    errors.push(`pages[${index}].width exceeds viewport`);
+  }
+  if (!Number.isInteger(height) || height < 1 || height > viewport.height) {
+    errors.push(`pages[${index}].height exceeds viewport`);
+  }
+  const minStride = Number.isInteger(width) ? Math.ceil(width / 8) : 0;
+  if (!Number.isInteger(stride) || stride < minStride) {
+    errors.push(`pages[${index}].stride must be at least ceil(width / 8)`);
+  }
+  const bytes = decodeStrictBase64(page.data_b64);
+  if (!bytes) {
+    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`);
+  }
+}
+
+function result(context, errors) {
+  return {
+    ok: errors.length === 0,
+    errors,
+    viewport: context.content_viewport,
+    agent_transport: context.agent_transport || null,
+    direct_delivery_ready: context.agent_transport?.screen_document_available === true
+      || context.agent_transport?.available === true,
+  };
+}
+
+function decodeStrictBase64(value) {
+  if (!string(value) || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) {
+    return null;
+  }
+  try {
+    return Buffer.from(value, "base64");
+  } catch {
+    return null;
+  }
+}
+
+function isFutureIso(value) {
+  if (!/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{3})?Z$/u.test(String(value || ""))) return false;
+  const stamp = Date.parse(value);
+  return Number.isFinite(stamp) && stamp > Date.now();
+}
+
+function string(value) {
+  return typeof value === "string" && value.length > 0;
+}

package/lib/mqtt-control.mjs

@@ -0,0 +1,91 @@
+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");
+  }
+  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 },
+  });
+  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();
+      });
+    });
+  } finally {
+    client.end(true);
+  }
+}
+
+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 },
+  });
+  try {
+    await onceConnected(client);
+  } finally {
+    client.end(true);
+  }
+  return {
+    ok: true,
+    url: config.url,
+    client_id: config.clientId,
+    username: config.username,
+    control_topic: config.controlTopic,
+  };
+}
+
+export function normalizeCredentials(value) {
+  const mqttConfig = value?.mqtt && typeof value.mqtt === "object" ? value.mqtt : value;
+  const topics = mqttConfig?.topics;
+  const url = string(mqttConfig?.url);
+  const username = string(mqttConfig?.username);
+  const password = string(mqttConfig?.password);
+  const clientId = string(mqttConfig?.client_id);
+  const controlTopic = string(topics?.control);
+  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 };
+}
+
+function onceConnected(client) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => finish(new Error("mqtt_connect_timeout")), 12_500);
+    const finish = (error) => {
+      clearTimeout(timeout);
+      client.removeListener("connect", onConnect);
+      client.removeListener("error", onError);
+      if (error) reject(error);
+      else resolve();
+    };
+    const onConnect = () => finish();
+    const onError = (error) => finish(error);
+    client.once("connect", onConnect);
+    client.once("error", onError);
+  });
+}
+
+function string(value) {
+  return typeof value === "string" ? value.trim() : "";
+}

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "weclawbot",
+  "name": "WeClawBot",
+  "description": "Lets OpenClaw curate WeChat messages and validate live screen documents for a paired WeClawBot screen.",
+  "skills": [
+    "./skills"
+  ],
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}