@openbrt/weclawbotctl 0.1.18 → 0.1.19

package/bin/weclawbotctl.mjs

@@ -10,6 +10,7 @@ import process from "node:process";
 import { validateActivity } from "../lib/activity.mjs";
 import { validateScreenDocument } from "../lib/direct-control.mjs";
 import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "../lib/mqtt-control.mjs";
+import { createPreviewArtifactDir, writePreviewManifest } from "../lib/preview-manifest.mjs";
 import { writeScreenDocumentPreviewFiles } from "../lib/screen-preview.mjs";
 
 const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
@@ -212,6 +213,7 @@ async function commandScreen(values) {
     timeout: 12,
     preview: true,
     "preview-dir": "",
+    "preview-manifest": true,
     scale: 2,
   });
   const file = String(options._[0] || "").trim();
@@ -229,9 +231,10 @@ async function commandScreen(values) {
   if (!validation.ok) {
     throw new Error(`Invalid screen document: ${validation.errors.join("; ")}`);
   }
+  const previewOutputDir = options["preview-dir"] || (options["preview-manifest"] ? await createPreviewArtifactDir(document.id || "screen") : "");
   const preview = options.preview
     ? await writeScreenDocumentPreviewFiles(document, {
-      outputDir: options["preview-dir"] || "",
+      outputDir: previewOutputDir,
       scale: Number(options.scale) || 2,
     })
     : { available: false, pages: [] };
@@ -250,6 +253,14 @@ async function commandScreen(values) {
     if (delivery.status.kind !== "applied") {
       throw new Error(`Device rejected screen document: ${delivery.status.detail || "unknown"}`);
     }
+    const manifest = options["preview-manifest"]
+      ? await writePreviewManifest({
+        document,
+        preview,
+        source: "weclawbotctl_screen",
+        status: { applied: true, mqtt_status: delivery.status },
+      })
+      : null;
     console.log(JSON.stringify({
       ok: true,
       published: true,
@@ -260,11 +271,20 @@ async function commandScreen(values) {
       warnings: validation.warnings,
       layout_guidance: validation.layout_guidance,
       preview,
+      preview_manifest: previewManifestSummary(manifest),
       status: delivery.status,
     }));
     return;
   }
   await publishControl(credentials, control);
+  const manifest = options["preview-manifest"]
+    ? await writePreviewManifest({
+      document,
+      preview,
+      source: "weclawbotctl_screen",
+      status: { applied: null },
+    })
+    : null;
   console.log(JSON.stringify({
     ok: true,
     published: true,
@@ -275,6 +295,7 @@ async function commandScreen(values) {
     warnings: validation.warnings,
     layout_guidance: validation.layout_guidance,
     preview,
+    preview_manifest: previewManifestSummary(manifest),
   }));
 }
 
@@ -767,6 +788,15 @@ function clearStatusDetail(target) {
   return target === "idle_photo" ? "clear_idle_photo" : "clear_note";
 }
 
+function previewManifestSummary(manifest) {
+  if (!manifest) return null;
+  return {
+    id: manifest.id,
+    path: manifest.path,
+    pages: manifest.preview?.pages?.length || 0,
+  };
+}
+
 function shellValue(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
@@ -785,7 +815,7 @@ function usage() {
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
   weclawbotctl preview <document.json> [--output-dir dir] [--scale 1..4]
-  weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds] [--preview-dir dir] [--no-preview]
+  weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds] [--preview-dir dir] [--no-preview] [--no-preview-manifest]
   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

@@ -10,11 +10,13 @@ import { validateActivity } from "./lib/activity.mjs";
 import { validateScreenDocument } from "./lib/direct-control.mjs";
 import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "./lib/mqtt-control.mjs";
 import { collectCommandStrings, extractScreenDocumentPathFromExecParams, normalizeDeliveryContext } from "./lib/openclaw-preview.mjs";
+import { createPreviewArtifactDir, listRecentPreviewManifests, markPreviewManifest, writePreviewManifest } from "./lib/preview-manifest.mjs";
 import { renderScreenDocumentPreviewPages, writeScreenDocumentPreviewFiles } from "./lib/screen-preview.mjs";
 
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
 const SCREEN_PROMPT_PATTERN = /weclawbot|weclaw|微笺|桌宠|墨水屏|电子墨水|屏上|上屏|发到屏|推到屏|放到屏|显示到屏|发送到屏|清屏|清理屏幕|屏幕/iu;
 const activeRunActivities = new Map();
+const activePreviewWindows = 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
@@ -136,12 +138,21 @@ const pluginEntry = defineToolPlugin({
           document: outbound,
         };
         const credentials = await requireCredentials(credentials_path);
-        const preview = await writeScreenDocumentPreviewFiles(outbound, { outputDir: preview_output_dir || "" });
+        const previewDir = preview_output_dir || await createPreviewArtifactDir(outbound.id || "screen");
+        const preview = await writeScreenDocumentPreviewFiles(outbound, { outputDir: previewDir });
         if (wait_status !== false) {
           const delivery = await publishControlAndWaitStatus(credentials, control, {
             expectedDetail: outbound.id,
             timeoutMs: Math.max(1, Number(timeout_seconds) || 12) * 1000,
           });
+          const manifest = delivery.status.kind === "applied"
+            ? await writePreviewManifest({
+              document: outbound,
+              preview,
+              source: "openclaw_tool",
+              status: { applied: true, mqtt_status: delivery.status },
+            })
+            : null;
           return {
             ok: delivery.status.kind === "applied",
             published: true,
@@ -153,10 +164,17 @@ const pluginEntry = defineToolPlugin({
             warnings: validation.warnings,
             layout_guidance: validation.layout_guidance,
             preview,
+            preview_manifest: previewManifestSummary(manifest),
             status: delivery.status,
           };
         }
         await publishControl(credentials, control);
+        const manifest = await writePreviewManifest({
+          document: outbound,
+          preview,
+          source: "openclaw_tool",
+          status: { applied: null },
+        });
         return {
           ok: true,
           published: true,
@@ -167,6 +185,7 @@ const pluginEntry = defineToolPlugin({
           warnings: validation.warnings,
           layout_guidance: validation.layout_guidance,
           preview,
+          preview_manifest: previewManifestSummary(manifest),
         };
       },
     }),
@@ -228,11 +247,11 @@ function registerOpenClawHooks(api) {
     return { outcome: "pass" };
   }, { timeoutMs: 5_000 });
   api.on("before_agent_finalize", async (event, ctx) => {
-    await finishHookActivity(api, event, ctx);
+    await finishHookActivity(api, event, ctx, { final: false });
     return { action: "continue" };
   }, { timeoutMs: 5_000 });
   api.on("agent_end", async (event, ctx) => {
-    await finishHookActivity(api, event, ctx);
+    await finishHookActivity(api, event, ctx, { final: true });
   }, { timeoutMs: 5_000 });
   api.on("after_tool_call", async (event, ctx) => {
     await attachScreenPreview(api, event, ctx);
@@ -241,10 +260,14 @@ function registerOpenClawHooks(api) {
 
 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;
+    if (!key) return;
+    if (!activePreviewWindows.has(key)) {
+      activePreviewWindows.set(key, { startedAt: Date.now() });
+    }
+    if (api.pluginConfig?.auto_activity === false) return;
+    if (activeRunActivities.has(key)) return;
     const correlationId = `openclaw-${sanitizeId(ctx?.runId || key).slice(0, 72)}`;
     await publishControl(await requireCredentials(), {
       schema: "weclawbot.control.v1",
@@ -264,10 +287,20 @@ async function startHookActivity(api, event, ctx) {
   }
 }
 
-async function finishHookActivity(api, event, ctx) {
+async function finishHookActivity(api, event, ctx, options = {}) {
+  const key = hookActivityKey(event, ctx);
+  if (!key) return;
+  const previewWindow = activePreviewWindows.get(key);
+  if (previewWindow) {
+    try {
+      await attachRecentPreviewManifests(api, event, ctx, previewWindow);
+    } catch (error) {
+      api.logger?.warn?.(`weclawbot preview manifest hook failed: ${errorMessage(error)}`);
+    } finally {
+      if (options.final) activePreviewWindows.delete(key);
+    }
+  }
   try {
-    const key = hookActivityKey(event, ctx);
-    if (!key) return;
     const active = activeRunActivities.get(key);
     if (!active) return;
     activeRunActivities.delete(key);
@@ -287,6 +320,53 @@ async function finishHookActivity(api, event, ctx) {
   }
 }
 
+async function attachRecentPreviewManifests(api, event, ctx, previewWindow) {
+  if (api.pluginConfig?.auto_preview === false) return 0;
+  if (event?.error) return 0;
+  const sessionKey = resolveHookSessionKey(event, ctx);
+  if (!sessionKey) {
+    logPreviewSkip(api, event, "missing sessionKey for manifest delivery");
+    return 0;
+  }
+  const manifests = await listRecentPreviewManifests({
+    sinceMs: Math.max(0, Number(previewWindow?.startedAt) || Date.now() - 60_000),
+    untilMs: Date.now() + 10_000,
+    limit: 5,
+  });
+  let delivered = 0;
+  for (const manifest of manifests) {
+    const result = await attachPreviewManifest(api, manifest, { ...ctx, sessionKey });
+    if (result?.ok) {
+      delivered += result.count || 1;
+      await markPreviewManifest(manifest.path, {
+        delivered_at: new Date().toISOString(),
+        delivered_session_key: sessionKey,
+        delivered_channel: result.channel,
+      });
+    } else {
+      await markPreviewManifest(manifest.path, {
+        last_delivery_error_at: new Date().toISOString(),
+        last_delivery_error: result?.error || "unknown error",
+      });
+      api.logger?.warn?.(`weclawbot preview manifest delivery failed: ${result?.error || "unknown error"}`);
+    }
+  }
+  return delivered;
+}
+
+async function attachPreviewManifest(api, manifest, ctx) {
+  const pages = Array.isArray(manifest.preview?.pages) ? manifest.preview.pages : [];
+  const files = pages
+    .map((page) => ({ path: String(page.path || "") }))
+    .filter((file) => file.path);
+  if (files.length === 0) return { ok: false, error: "manifest has no preview files" };
+  const documentId = manifest.document?.id || "screen";
+  const pageLabel = `${files.length} page${files.length === 1 ? "" : "s"}`;
+  const caption = `WeClawBot screen preview: ${documentId} (${pageLabel}, ${manifest.source || "manifest"})`;
+  const dir = manifest.preview?.output_dir || path.dirname(files[0].path);
+  return deliverPreviewFiles(api, { ctx, files, caption, dir });
+}
+
 async function attachScreenPreview(api, event, ctx) {
   try {
     if (api.pluginConfig?.auto_preview !== true) return;
@@ -343,12 +423,22 @@ async function attachPreviewForDocument(api, document, ctx, source) {
     }
     const pageLabel = `${previewPages.length} page${previewPages.length === 1 ? "" : "s"}`;
     const caption = `WeClawBot screen preview: ${document.id || "screen"} (${pageLabel}, ${source})`;
+    const result = await deliverPreviewFiles(api, { ctx, files, caption, dir });
+    if (!result?.ok) {
+      api.logger?.warn?.(`weclawbot preview delivery failed: ${result?.error || "unknown error"}`);
+    } else {
+      api.logger?.info?.(`weclawbot preview attached: ${result.channel} count=${result.count}`);
+    }
+    scheduleRemove(dir);
+}
+
+async function deliverPreviewFiles(api, params) {
     let attached = false;
     if (typeof api.session?.workflow?.sendSessionAttachment === "function") {
       const result = await api.session.workflow.sendSessionAttachment({
-        sessionKey: ctx.sessionKey,
-        files,
-        text: caption,
+        sessionKey: params.ctx.sessionKey,
+        files: params.files,
+        text: params.caption,
         maxBytes: 2_000_000,
         captionFormat: "plain",
         channelHints: { telegram: { forceDocumentMime: "image/png" } },
@@ -362,20 +452,19 @@ async function attachPreviewForDocument(api, document, ctx, source) {
     }
     if (!attached) {
       const result = await sendPreviewViaOutboundAdapter(api, {
-        ctx,
-        files,
-        document,
-        source,
-        caption,
-        dir,
+        ctx: params.ctx,
+        files: params.files,
+        caption: params.caption,
+        dir: params.dir,
       });
       if (!result?.ok) {
-        api.logger?.warn?.(`weclawbot preview outbound fallback failed: ${result?.error || "unknown error"}`);
+        return result;
       } else {
         api.logger?.info?.(`weclawbot preview attached via outbound adapter: ${result.channel} count=${result.count}`);
+        return result;
       }
     }
-    scheduleRemove(dir);
+    return { ok: true, channel: "session-workflow", count: params.files.length };
 }
 
 async function sendPreviewViaOutboundAdapter(api, params) {
@@ -502,6 +591,15 @@ function clearStatusDetail(target) {
   return target === "idle_photo" ? "clear_idle_photo" : "clear_note";
 }
 
+function previewManifestSummary(manifest) {
+  if (!manifest) return null;
+  return {
+    id: manifest.id,
+    path: manifest.path,
+    pages: manifest.preview?.pages?.length || 0,
+  };
+}
+
 function sanitizeId(value) {
   return String(value || crypto.randomUUID()).replace(/[^a-zA-Z0-9_.-]/gu, "_");
 }

package/lib/preview-manifest.mjs

@@ -0,0 +1,133 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const MANIFEST_SCHEMA = "weclawbot.preview_manifest.v1";
+
+export async function defaultPreviewManifestRoot() {
+  const override = expandPath(process.env.WECLAWBOT_PREVIEW_SPOOL_DIR || "");
+  if (override) return override;
+
+  const stateDir = expandPath(process.env.OPENCLAW_STATE_DIR || "");
+  if (stateDir) return path.join(stateDir, "media", "outbound", "weclawbot-preview");
+
+  const openClawOutbound = path.join(os.homedir(), ".openclaw", "media", "outbound");
+  if (await isDirectory(openClawOutbound)) return path.join(openClawOutbound, "weclawbot-preview");
+
+  return path.join(os.homedir(), ".cache", "weclawbot", "openclaw-preview");
+}
+
+export async function createPreviewArtifactDir(documentId = "screen") {
+  const root = await defaultPreviewManifestRoot();
+  const now = new Date();
+  const stamp = now.toISOString().replace(/[:.]/gu, "-");
+  const dir = path.join(root, "files", `${stamp}-${process.pid}-${safeFilename(documentId)}`);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+export async function writePreviewManifest({ document, preview, source = "unknown", status = {}, createdAtMs = Date.now() }) {
+  if (!preview?.available || !Array.isArray(preview.pages) || preview.pages.length === 0) return null;
+  const root = await defaultPreviewManifestRoot();
+  const dir = path.join(root, "manifests");
+  await fs.mkdir(dir, { recursive: true });
+
+  const id = `preview_${crypto.randomUUID()}`;
+  const createdAt = new Date(createdAtMs).toISOString();
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    id,
+    created_at: createdAt,
+    created_ms: createdAtMs,
+    source,
+    document: {
+      id: String(document?.id || "screen"),
+      pages: Array.isArray(document?.pages) ? document.pages.length : preview.pages.length,
+    },
+    status,
+    preview: {
+      available: true,
+      output_dir: preview.output_dir || path.dirname(preview.pages[0]?.path || ""),
+      pages: preview.pages.map((page) => ({
+        index: Number(page.index) || 0,
+        path: String(page.path || ""),
+        width: Number(page.width) || 0,
+        height: Number(page.height) || 0,
+        scale: Number(page.scale) || 1,
+        bytes: Number(page.bytes) || 0,
+        sha256: String(page.sha256 || ""),
+        mime_type: page.mime_type || "image/png",
+      })),
+    },
+  };
+
+  const file = path.join(dir, `${createdAtMs}-${safeFilename(document?.id || source)}-${id}.json`);
+  await fs.writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  return { ...manifest, path: file, root };
+}
+
+export async function listRecentPreviewManifests(options = {}) {
+  const root = await defaultPreviewManifestRoot();
+  const dir = path.join(root, "manifests");
+  const sinceMs = Number(options.sinceMs) || 0;
+  const untilMs = Number(options.untilMs) || Date.now() + 10_000;
+  const limit = Math.max(1, Number(options.limit) || 8);
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+
+  const manifests = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const file = path.join(dir, entry.name);
+    let stat;
+    let manifest;
+    try {
+      stat = await fs.stat(file);
+      if (stat.mtimeMs < sinceMs - 10_000 || stat.mtimeMs > untilMs + 10_000) continue;
+      manifest = JSON.parse(await fs.readFile(file, "utf8"));
+    } catch {
+      continue;
+    }
+    if (manifest?.schema !== MANIFEST_SCHEMA) continue;
+    if (manifest.delivered_at || manifest.consumed_at) continue;
+    const createdMs = Number(manifest.created_ms) || Date.parse(manifest.created_at || "") || stat.mtimeMs;
+    if (createdMs < sinceMs || createdMs > untilMs) continue;
+    const pages = Array.isArray(manifest.preview?.pages) ? manifest.preview.pages : [];
+    if (pages.length === 0) continue;
+    manifests.push({ ...manifest, created_ms: createdMs, path: file, root });
+  }
+
+  return manifests
+    .sort((a, b) => a.created_ms - b.created_ms)
+    .slice(0, limit);
+}
+
+export async function markPreviewManifest(file, patch) {
+  const payload = JSON.parse(await fs.readFile(file, "utf8"));
+  const updated = { ...payload, ...patch };
+  await fs.writeFile(file, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+  return updated;
+}
+
+async function isDirectory(file) {
+  try {
+    return (await fs.stat(file)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function expandPath(value) {
+  const raw = String(value || "").trim();
+  return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+}
+
+function safeFilename(value) {
+  return String(value || "screen").replace(/[^a-zA-Z0-9_.-]/gu, "_").slice(0, 80) || "screen";
+}

package/package.json

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

package/test/preview-manifest.test.mjs

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  createPreviewArtifactDir,
+  listRecentPreviewManifests,
+  markPreviewManifest,
+  writePreviewManifest,
+} from "../lib/preview-manifest.mjs";
+import { writeScreenDocumentPreviewFiles } from "../lib/screen-preview.mjs";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "weclawbot-preview-manifest-test-"));
+process.env.WECLAWBOT_PREVIEW_SPOOL_DIR = root;
+
+const width = 8;
+const height = 8;
+const stride = 1;
+const bytes = Buffer.alloc(stride * height, 0x00);
+for (let y = 0; y < height; y += 1) bytes[y * stride] = 0x80;
+
+const document = {
+  schema: "weclawbot.screen_document.v1",
+  id: "manifest-test",
+  pages: [{
+    format: "mono1",
+    width,
+    height,
+    stride,
+    data_b64: bytes.toString("base64"),
+  }],
+};
+
+const artifactDir = await createPreviewArtifactDir(document.id);
+assert.ok(artifactDir.startsWith(root));
+
+const preview = await writeScreenDocumentPreviewFiles(document, { outputDir: artifactDir });
+const manifest = await writePreviewManifest({
+  document,
+  preview,
+  source: "test",
+  status: { applied: true },
+});
+
+assert.ok(manifest.path.startsWith(root));
+assert.equal(manifest.preview.pages.length, 1);
+
+const recent = await listRecentPreviewManifests({ sinceMs: Date.now() - 10_000 });
+assert.equal(recent.length, 1);
+assert.equal(recent[0].id, manifest.id);
+
+await markPreviewManifest(manifest.path, { delivered_at: new Date().toISOString() });
+const afterDelivery = await listRecentPreviewManifests({ sinceMs: Date.now() - 10_000 });
+assert.equal(afterDelivery.length, 0);
+
+delete process.env.WECLAWBOT_PREVIEW_SPOOL_DIR;
+await fs.rm(root, { recursive: true, force: true });
+
+console.log("preview-manifest spool: ok");