@riddledc/openclaw-riddledc 0.5.6 → 0.7.0

package/CHECKSUMS.txt

@@ -1,4 +1,4 @@
-041dfffc9dfaaa099cb6243c3512574254b91a80d19e64a68b078d3fc97bd4c8  dist/index.cjs
+921867120c7149d34d965a56ab0b727b2ecd2f0abf4ea9980171aefd4e11c39f  dist/index.cjs
 94ce04f0e2d84bf64dd68f0500dfdd2f951287a3deccec87f197261961927f6f  dist/index.d.cts
 94ce04f0e2d84bf64dd68f0500dfdd2f951287a3deccec87f197261961927f6f  dist/index.d.ts
-b4d87078938b29cd38097688ac435c4fe328a561963212b53c678a2525c8b86a  dist/index.js
+06f7ee46883239b2b9e1180a0f82d70b62f03fb2b73c032ff4ae7dafb65ab8e1  dist/index.js

package/dist/index.cjs

@@ -26,6 +26,9 @@ module.exports = __toCommonJS(index_exports);
 var import_typebox = require("@sinclair/typebox");
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var execFile = (0, import_node_util.promisify)(import_node_child_process.execFile);
 var INLINE_CAP = 50 * 1024;
 function getCfg(api) {
   const cfg = api?.config ?? {};
@@ -753,4 +756,248 @@ function register(api) {
     },
     { optional: true }
   );
+  api.registerTool(
+    {
+      name: "riddle_preview",
+      description: "Deploy a local build directory as an ephemeral preview site. Tars the directory, uploads to Riddle, and returns a live URL at preview.riddledc.com that can be screenshotted with other riddle_* tools. Previews auto-expire after 24 hours.",
+      parameters: import_typebox.Type.Object({
+        directory: import_typebox.Type.String({ description: "Absolute path to the build output directory (e.g. /path/to/build or /path/to/dist)" }),
+        framework: import_typebox.Type.Optional(import_typebox.Type.String({ description: "Framework hint: 'spa' (default) or 'static'" }))
+      }),
+      async execute(_id, params) {
+        const { apiKey, baseUrl } = getCfg(api);
+        if (!apiKey) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Missing Riddle API key." }, null, 2) }] };
+        }
+        assertAllowedBaseUrl(baseUrl);
+        const dir = params.directory;
+        if (!dir || typeof dir !== "string") throw new Error("directory must be an absolute path");
+        try {
+          const st = await (0, import_promises.stat)(dir);
+          if (!st.isDirectory()) throw new Error(`Not a directory: ${dir}`);
+        } catch (e) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Cannot access directory: ${e.message}` }, null, 2) }] };
+        }
+        const endpoint = baseUrl.replace(/\/$/, "");
+        const createRes = await fetch(`${endpoint}/v1/preview`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify({ framework: params.framework || "spa" })
+        });
+        if (!createRes.ok) {
+          const err = await createRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Create failed: HTTP ${createRes.status} ${err}` }, null, 2) }] };
+        }
+        const created = await createRes.json();
+        const tarball = `/tmp/riddle-preview-${created.id}.tar.gz`;
+        try {
+          await execFile("tar", ["czf", tarball, "-C", dir, "."], { timeout: 6e4 });
+          const tarData = await (0, import_promises.readFile)(tarball);
+          const uploadRes = await fetch(created.upload_url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/gzip" },
+            body: tarData
+          });
+          if (!uploadRes.ok) {
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, id: created.id, error: `Upload failed: HTTP ${uploadRes.status}` }, null, 2) }] };
+          }
+        } finally {
+          try {
+            await (0, import_promises.rm)(tarball, { force: true });
+          } catch {
+          }
+        }
+        const publishRes = await fetch(`${endpoint}/v1/preview/${created.id}/publish`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!publishRes.ok) {
+          const err = await publishRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, id: created.id, error: `Publish failed: HTTP ${publishRes.status} ${err}` }, null, 2) }] };
+        }
+        const published = await publishRes.json();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ok: true,
+              id: published.id,
+              preview_url: published.preview_url,
+              file_count: published.file_count,
+              total_bytes: published.total_bytes,
+              expires_at: created.expires_at
+            }, null, 2)
+          }]
+        };
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "riddle_preview_delete",
+      description: "Delete an ephemeral preview site created by riddle_preview. Removes all files and frees the preview ID immediately instead of waiting for auto-expiry.",
+      parameters: import_typebox.Type.Object({
+        id: import_typebox.Type.String({ description: "Preview ID (e.g. pv_a1b2c3d4)" })
+      }),
+      async execute(_id, params) {
+        const { apiKey, baseUrl } = getCfg(api);
+        if (!apiKey) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Missing Riddle API key." }, null, 2) }] };
+        }
+        assertAllowedBaseUrl(baseUrl);
+        const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/preview/${params.id}`, {
+          method: "DELETE",
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!res.ok) {
+          const err = await res.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Delete failed: HTTP ${res.status} ${err}` }, null, 2) }] };
+        }
+        const data = await res.json();
+        return { content: [{ type: "text", text: JSON.stringify({ ok: true, deleted: true, files_removed: data.files_removed }, null, 2) }] };
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "riddle_server_preview",
+      description: "Run a server-side app (Next.js, Express, Django, etc.) in an isolated Docker container and screenshot it. Tars the build directory, uploads to Riddle, starts the container with the specified image and command, waits for readiness, then takes a Playwright screenshot. Use for apps that need a running server process (not static sites \u2014 use riddle_preview for those).",
+      parameters: import_typebox.Type.Object({
+        directory: import_typebox.Type.String({ description: "Absolute path to the project/build directory to deploy into the container" }),
+        image: import_typebox.Type.String({ description: "Docker image to run (e.g. 'node:20-slim', 'python:3.12-slim')" }),
+        command: import_typebox.Type.String({ description: "Command to start the server inside the container (e.g. 'npm start', 'python manage.py runserver 0.0.0.0:3000')" }),
+        port: import_typebox.Type.Number({ description: "Port the server listens on inside the container" }),
+        path: import_typebox.Type.Optional(import_typebox.Type.String({ description: "URL path to screenshot (default: '/')" })),
+        env: import_typebox.Type.Optional(import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.String(), { description: "Non-sensitive environment variables" })),
+        sensitive_env: import_typebox.Type.Optional(import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.String(), { description: "Sensitive environment variables (API keys, DB passwords). Stored securely and deleted after use." })),
+        timeout: import_typebox.Type.Optional(import_typebox.Type.Number({ description: "Max execution time in seconds (default: 120, max: 600)" })),
+        readiness_path: import_typebox.Type.Optional(import_typebox.Type.String({ description: "Path to poll for readiness (default: same as path)" })),
+        readiness_timeout: import_typebox.Type.Optional(import_typebox.Type.Number({ description: "Max seconds to wait for server readiness (default: 30)" })),
+        script: import_typebox.Type.Optional(import_typebox.Type.String({ description: `Optional Playwright script to run after server is ready (e.g. 'await page.click("button")')` }))
+      }),
+      async execute(_id, params) {
+        const { apiKey, baseUrl } = getCfg(api);
+        if (!apiKey) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Missing Riddle API key." }, null, 2) }] };
+        }
+        assertAllowedBaseUrl(baseUrl);
+        const dir = params.directory;
+        if (!dir || typeof dir !== "string") throw new Error("directory must be an absolute path");
+        try {
+          const st = await (0, import_promises.stat)(dir);
+          if (!st.isDirectory()) throw new Error(`Not a directory: ${dir}`);
+        } catch (e) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Cannot access directory: ${e.message}` }, null, 2) }] };
+        }
+        const endpoint = baseUrl.replace(/\/$/, "");
+        let envRef = null;
+        if (params.sensitive_env && Object.keys(params.sensitive_env).length > 0) {
+          const envRes = await fetch(`${endpoint}/v1/server-preview/env`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ env: params.sensitive_env })
+          });
+          if (!envRes.ok) {
+            const err = await envRes.text();
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Store env failed: HTTP ${envRes.status} ${err}` }, null, 2) }] };
+          }
+          const envData = await envRes.json();
+          envRef = envData.env_ref;
+        }
+        const createBody = {
+          image: params.image,
+          command: params.command,
+          port: params.port
+        };
+        if (params.path) createBody.path = params.path;
+        if (params.env) createBody.env = params.env;
+        if (envRef) createBody.env_ref = envRef;
+        if (params.timeout) createBody.timeout = params.timeout;
+        if (params.readiness_path) createBody.readiness_path = params.readiness_path;
+        if (params.readiness_timeout) createBody.readiness_timeout = params.readiness_timeout;
+        if (params.script) createBody.script = params.script;
+        const createRes = await fetch(`${endpoint}/v1/server-preview`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify(createBody)
+        });
+        if (!createRes.ok) {
+          const err = await createRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Create failed: HTTP ${createRes.status} ${err}` }, null, 2) }] };
+        }
+        const created = await createRes.json();
+        const tarball = `/tmp/riddle-sp-${created.job_id}.tar.gz`;
+        try {
+          await execFile("tar", ["czf", tarball, "-C", dir, "."], { timeout: 12e4 });
+          const tarData = await (0, import_promises.readFile)(tarball);
+          const uploadRes = await fetch(created.upload_url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/gzip" },
+            body: tarData
+          });
+          if (!uploadRes.ok) {
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Upload failed: HTTP ${uploadRes.status}` }, null, 2) }] };
+          }
+        } finally {
+          try {
+            await (0, import_promises.rm)(tarball, { force: true });
+          } catch {
+          }
+        }
+        const startRes = await fetch(`${endpoint}/v1/server-preview/${created.job_id}/start`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!startRes.ok) {
+          const err = await startRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Start failed: HTTP ${startRes.status} ${err}` }, null, 2) }] };
+        }
+        const timeoutMs = ((params.timeout || 120) + 60) * 1e3;
+        const pollStart = Date.now();
+        const POLL_INTERVAL = 3e3;
+        while (Date.now() - pollStart < timeoutMs) {
+          const statusRes = await fetch(`${endpoint}/v1/server-preview/${created.job_id}`, {
+            headers: { Authorization: `Bearer ${apiKey}` }
+          });
+          if (!statusRes.ok) {
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Poll failed: HTTP ${statusRes.status}` }, null, 2) }] };
+          }
+          const statusData = await statusRes.json();
+          if (statusData.status === "completed" || statusData.status === "failed") {
+            const result = {
+              ok: statusData.status === "completed",
+              job_id: created.job_id,
+              status: statusData.status,
+              outputs: statusData.outputs || [],
+              compute_seconds: statusData.compute_seconds,
+              egress_bytes: statusData.egress_bytes
+            };
+            if (statusData.error) result.error = statusData.error;
+            const workspace = getWorkspacePath(api);
+            for (const output of result.outputs) {
+              if (output.name && /\.(png|jpg|jpeg)$/i.test(output.name) && output.url) {
+                try {
+                  const imgRes = await fetch(output.url);
+                  if (imgRes.ok) {
+                    const buf = await imgRes.arrayBuffer();
+                    const base64 = Buffer.from(buf).toString("base64");
+                    const ref = await writeArtifactBinary(workspace, "screenshots", `${created.job_id}-${output.name}`, base64);
+                    output.saved = ref.path;
+                    output.sizeBytes = ref.sizeBytes;
+                  }
+                } catch {
+                }
+              }
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+          }
+          await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Job did not complete within ${timeoutMs / 1e3}s` }, null, 2) }] };
+      }
+    },
+    { optional: true }
+  );
 }

package/dist/index.js

@@ -1,7 +1,10 @@
 // src/index.ts
 import { Type } from "@sinclair/typebox";
-import { writeFile, mkdir } from "fs/promises";
+import { writeFile, mkdir, readFile, stat, rm } from "fs/promises";
 import { join } from "path";
+import { execFile as execFileCb } from "child_process";
+import { promisify } from "util";
+var execFile = promisify(execFileCb);
 var INLINE_CAP = 50 * 1024;
 function getCfg(api) {
   const cfg = api?.config ?? {};
@@ -729,6 +732,250 @@ function register(api) {
     },
     { optional: true }
   );
+  api.registerTool(
+    {
+      name: "riddle_preview",
+      description: "Deploy a local build directory as an ephemeral preview site. Tars the directory, uploads to Riddle, and returns a live URL at preview.riddledc.com that can be screenshotted with other riddle_* tools. Previews auto-expire after 24 hours.",
+      parameters: Type.Object({
+        directory: Type.String({ description: "Absolute path to the build output directory (e.g. /path/to/build or /path/to/dist)" }),
+        framework: Type.Optional(Type.String({ description: "Framework hint: 'spa' (default) or 'static'" }))
+      }),
+      async execute(_id, params) {
+        const { apiKey, baseUrl } = getCfg(api);
+        if (!apiKey) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Missing Riddle API key." }, null, 2) }] };
+        }
+        assertAllowedBaseUrl(baseUrl);
+        const dir = params.directory;
+        if (!dir || typeof dir !== "string") throw new Error("directory must be an absolute path");
+        try {
+          const st = await stat(dir);
+          if (!st.isDirectory()) throw new Error(`Not a directory: ${dir}`);
+        } catch (e) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Cannot access directory: ${e.message}` }, null, 2) }] };
+        }
+        const endpoint = baseUrl.replace(/\/$/, "");
+        const createRes = await fetch(`${endpoint}/v1/preview`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify({ framework: params.framework || "spa" })
+        });
+        if (!createRes.ok) {
+          const err = await createRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Create failed: HTTP ${createRes.status} ${err}` }, null, 2) }] };
+        }
+        const created = await createRes.json();
+        const tarball = `/tmp/riddle-preview-${created.id}.tar.gz`;
+        try {
+          await execFile("tar", ["czf", tarball, "-C", dir, "."], { timeout: 6e4 });
+          const tarData = await readFile(tarball);
+          const uploadRes = await fetch(created.upload_url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/gzip" },
+            body: tarData
+          });
+          if (!uploadRes.ok) {
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, id: created.id, error: `Upload failed: HTTP ${uploadRes.status}` }, null, 2) }] };
+          }
+        } finally {
+          try {
+            await rm(tarball, { force: true });
+          } catch {
+          }
+        }
+        const publishRes = await fetch(`${endpoint}/v1/preview/${created.id}/publish`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!publishRes.ok) {
+          const err = await publishRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, id: created.id, error: `Publish failed: HTTP ${publishRes.status} ${err}` }, null, 2) }] };
+        }
+        const published = await publishRes.json();
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ok: true,
+              id: published.id,
+              preview_url: published.preview_url,
+              file_count: published.file_count,
+              total_bytes: published.total_bytes,
+              expires_at: created.expires_at
+            }, null, 2)
+          }]
+        };
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "riddle_preview_delete",
+      description: "Delete an ephemeral preview site created by riddle_preview. Removes all files and frees the preview ID immediately instead of waiting for auto-expiry.",
+      parameters: Type.Object({
+        id: Type.String({ description: "Preview ID (e.g. pv_a1b2c3d4)" })
+      }),
+      async execute(_id, params) {
+        const { apiKey, baseUrl } = getCfg(api);
+        if (!apiKey) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Missing Riddle API key." }, null, 2) }] };
+        }
+        assertAllowedBaseUrl(baseUrl);
+        const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/preview/${params.id}`, {
+          method: "DELETE",
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!res.ok) {
+          const err = await res.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Delete failed: HTTP ${res.status} ${err}` }, null, 2) }] };
+        }
+        const data = await res.json();
+        return { content: [{ type: "text", text: JSON.stringify({ ok: true, deleted: true, files_removed: data.files_removed }, null, 2) }] };
+      }
+    },
+    { optional: true }
+  );
+  api.registerTool(
+    {
+      name: "riddle_server_preview",
+      description: "Run a server-side app (Next.js, Express, Django, etc.) in an isolated Docker container and screenshot it. Tars the build directory, uploads to Riddle, starts the container with the specified image and command, waits for readiness, then takes a Playwright screenshot. Use for apps that need a running server process (not static sites \u2014 use riddle_preview for those).",
+      parameters: Type.Object({
+        directory: Type.String({ description: "Absolute path to the project/build directory to deploy into the container" }),
+        image: Type.String({ description: "Docker image to run (e.g. 'node:20-slim', 'python:3.12-slim')" }),
+        command: Type.String({ description: "Command to start the server inside the container (e.g. 'npm start', 'python manage.py runserver 0.0.0.0:3000')" }),
+        port: Type.Number({ description: "Port the server listens on inside the container" }),
+        path: Type.Optional(Type.String({ description: "URL path to screenshot (default: '/')" })),
+        env: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Non-sensitive environment variables" })),
+        sensitive_env: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Sensitive environment variables (API keys, DB passwords). Stored securely and deleted after use." })),
+        timeout: Type.Optional(Type.Number({ description: "Max execution time in seconds (default: 120, max: 600)" })),
+        readiness_path: Type.Optional(Type.String({ description: "Path to poll for readiness (default: same as path)" })),
+        readiness_timeout: Type.Optional(Type.Number({ description: "Max seconds to wait for server readiness (default: 30)" })),
+        script: Type.Optional(Type.String({ description: `Optional Playwright script to run after server is ready (e.g. 'await page.click("button")')` }))
+      }),
+      async execute(_id, params) {
+        const { apiKey, baseUrl } = getCfg(api);
+        if (!apiKey) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: "Missing Riddle API key." }, null, 2) }] };
+        }
+        assertAllowedBaseUrl(baseUrl);
+        const dir = params.directory;
+        if (!dir || typeof dir !== "string") throw new Error("directory must be an absolute path");
+        try {
+          const st = await stat(dir);
+          if (!st.isDirectory()) throw new Error(`Not a directory: ${dir}`);
+        } catch (e) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Cannot access directory: ${e.message}` }, null, 2) }] };
+        }
+        const endpoint = baseUrl.replace(/\/$/, "");
+        let envRef = null;
+        if (params.sensitive_env && Object.keys(params.sensitive_env).length > 0) {
+          const envRes = await fetch(`${endpoint}/v1/server-preview/env`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ env: params.sensitive_env })
+          });
+          if (!envRes.ok) {
+            const err = await envRes.text();
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Store env failed: HTTP ${envRes.status} ${err}` }, null, 2) }] };
+          }
+          const envData = await envRes.json();
+          envRef = envData.env_ref;
+        }
+        const createBody = {
+          image: params.image,
+          command: params.command,
+          port: params.port
+        };
+        if (params.path) createBody.path = params.path;
+        if (params.env) createBody.env = params.env;
+        if (envRef) createBody.env_ref = envRef;
+        if (params.timeout) createBody.timeout = params.timeout;
+        if (params.readiness_path) createBody.readiness_path = params.readiness_path;
+        if (params.readiness_timeout) createBody.readiness_timeout = params.readiness_timeout;
+        if (params.script) createBody.script = params.script;
+        const createRes = await fetch(`${endpoint}/v1/server-preview`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+          body: JSON.stringify(createBody)
+        });
+        if (!createRes.ok) {
+          const err = await createRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: `Create failed: HTTP ${createRes.status} ${err}` }, null, 2) }] };
+        }
+        const created = await createRes.json();
+        const tarball = `/tmp/riddle-sp-${created.job_id}.tar.gz`;
+        try {
+          await execFile("tar", ["czf", tarball, "-C", dir, "."], { timeout: 12e4 });
+          const tarData = await readFile(tarball);
+          const uploadRes = await fetch(created.upload_url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/gzip" },
+            body: tarData
+          });
+          if (!uploadRes.ok) {
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Upload failed: HTTP ${uploadRes.status}` }, null, 2) }] };
+          }
+        } finally {
+          try {
+            await rm(tarball, { force: true });
+          } catch {
+          }
+        }
+        const startRes = await fetch(`${endpoint}/v1/server-preview/${created.job_id}/start`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!startRes.ok) {
+          const err = await startRes.text();
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Start failed: HTTP ${startRes.status} ${err}` }, null, 2) }] };
+        }
+        const timeoutMs = ((params.timeout || 120) + 60) * 1e3;
+        const pollStart = Date.now();
+        const POLL_INTERVAL = 3e3;
+        while (Date.now() - pollStart < timeoutMs) {
+          const statusRes = await fetch(`${endpoint}/v1/server-preview/${created.job_id}`, {
+            headers: { Authorization: `Bearer ${apiKey}` }
+          });
+          if (!statusRes.ok) {
+            return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Poll failed: HTTP ${statusRes.status}` }, null, 2) }] };
+          }
+          const statusData = await statusRes.json();
+          if (statusData.status === "completed" || statusData.status === "failed") {
+            const result = {
+              ok: statusData.status === "completed",
+              job_id: created.job_id,
+              status: statusData.status,
+              outputs: statusData.outputs || [],
+              compute_seconds: statusData.compute_seconds,
+              egress_bytes: statusData.egress_bytes
+            };
+            if (statusData.error) result.error = statusData.error;
+            const workspace = getWorkspacePath(api);
+            for (const output of result.outputs) {
+              if (output.name && /\.(png|jpg|jpeg)$/i.test(output.name) && output.url) {
+                try {
+                  const imgRes = await fetch(output.url);
+                  if (imgRes.ok) {
+                    const buf = await imgRes.arrayBuffer();
+                    const base64 = Buffer.from(buf).toString("base64");
+                    const ref = await writeArtifactBinary(workspace, "screenshots", `${created.job_id}-${output.name}`, base64);
+                    output.saved = ref.path;
+                    output.sizeBytes = ref.sizeBytes;
+                  }
+                } catch {
+                }
+              }
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+          }
+          await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: created.job_id, error: `Job did not complete within ${timeoutMs / 1e3}s` }, null, 2) }] };
+      }
+    },
+    { optional: true }
+  );
 }
 export {
   register as default

package/openclaw.plugin.json

@@ -2,14 +2,15 @@
   "id": "openclaw-riddledc",
   "name": "Riddle",
   "description": "Riddle (riddledc.com) hosted browser API tools for OpenClaw agents.",
-  "version": "0.5.6",
-  "notes": "0.4.0: Added riddle_scrape, riddle_map, riddle_crawl convenience tools. Updated riddle_steps and riddle_script descriptions with data extraction capabilities.",
+  "version": "0.7.0",
+  "notes": "0.7.0: Added riddle_server_preview tool for running server-side apps in isolated Docker containers.",
   "type": "plugin",
   "bundledSkills": [],
   "capabilities": {
     "network": {
       "egress": [
-        "api.riddledc.com"
+        "api.riddledc.com",
+        "preview.riddledc.com"
       ],
       "enforced": true,
       "note": "Hardcoded allowlist in assertAllowedBaseUrl() - cannot be overridden by config"
@@ -37,7 +38,10 @@
         "riddle_scrape",
         "riddle_map",
         "riddle_crawl",
-        "riddle_visual_diff"
+        "riddle_visual_diff",
+        "riddle_preview",
+        "riddle_preview_delete",
+        "riddle_server_preview"
       ],
       "invokes": [],
       "note": "Provides tools for agent use; does not invoke other agent tools"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/openclaw-riddledc",
-  "version": "0.5.6",
+  "version": "0.7.0",
   "description": "OpenClaw integration package for RiddleDC (no secrets).",
   "license": "MIT",
   "author": "RiddleDC",