@riddledc/openclaw-riddledc 0.5.5 → 0.6.0

package/CHECKSUMS.txt

@@ -1,4 +1,4 @@
-21e09d68db3add27f41481e3ef75bdffa14bc4ae496285c7df2757590104f48b  dist/index.cjs
+876e2b78ca5f38ca4da27097761bcdb99882a5724f025d5befd5ba78710c5832  dist/index.cjs
 94ce04f0e2d84bf64dd68f0500dfdd2f951287a3deccec87f197261961927f6f  dist/index.d.cts
 94ce04f0e2d84bf64dd68f0500dfdd2f951287a3deccec87f197261961927f6f  dist/index.d.ts
-63fe7e972b3fa5392e23902122409fbc6d59fa73e0751f0414fd06b9092a7fcd  dist/index.js
+c481cef6e2fd6aca8d7aef042bc7b8cb5fc12274afe9c50ba10947e398c566ce  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 ?? {};
@@ -148,6 +151,95 @@ async function applySafetySpec(result, opts) {
     }
   }
 }
+async function pollJobStatus(baseUrl, apiKey, jobId, maxWaitMs) {
+  const start = Date.now();
+  const POLL_INTERVAL = 2e3;
+  while (Date.now() - start < maxWaitMs) {
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/jobs/${jobId}`, {
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    if (!res.ok) {
+      return { status: "poll_error", error: `HTTP ${res.status}` };
+    }
+    const data = await res.json();
+    if (data.status === "completed" || data.status === "completed_timeout" || data.status === "completed_error" || data.status === "failed") {
+      return data;
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+  }
+  return { status: "poll_timeout", error: `Job ${jobId} did not complete within ${maxWaitMs}ms` };
+}
+async function fetchArtifactsAndBuild(baseUrl, apiKey, jobId, include) {
+  const res = await fetch(
+    `${baseUrl.replace(/\/$/, "")}/v1/jobs/${jobId}/artifacts?include=${include.join(",")}`,
+    { headers: { Authorization: `Bearer ${apiKey}` } }
+  );
+  if (!res.ok) {
+    return { error: `Artifacts fetch failed: HTTP ${res.status}` };
+  }
+  const data = await res.json();
+  const artifacts = data.artifacts || [];
+  const result = {};
+  if (data.status) result._artifactsStatus = data.status;
+  if (data.timeout) result._timeout = data.timeout;
+  if (data.error) result._error = data.error;
+  const screenshots = artifacts.filter((a) => a.name && /\.(png|jpg|jpeg)$/i.test(a.name));
+  if (screenshots.length > 0) {
+    result.screenshots = [];
+    for (const ss of screenshots) {
+      if (!ss.url) continue;
+      try {
+        const imgRes = await fetch(ss.url);
+        if (imgRes.ok) {
+          const buf = await imgRes.arrayBuffer();
+          result.screenshots.push({
+            name: ss.name,
+            data: `data:image/png;base64,${Buffer.from(buf).toString("base64")}`,
+            size: buf.byteLength,
+            url: ss.url
+          });
+        }
+      } catch {
+      }
+    }
+    if (result.screenshots.length > 0) {
+      result.screenshot = result.screenshots[0];
+    }
+  }
+  const consoleArtifact = artifacts.find((a) => a.name === "console.json");
+  if (consoleArtifact?.url) {
+    try {
+      const cRes = await fetch(consoleArtifact.url);
+      if (cRes.ok) {
+        result.console = await cRes.json();
+      }
+    } catch {
+    }
+  }
+  const resultArtifact = artifacts.find((a) => a.name === "result.json");
+  if (resultArtifact?.url) {
+    try {
+      const rRes = await fetch(resultArtifact.url);
+      if (rRes.ok) {
+        result.result = await rRes.json();
+      }
+    } catch {
+    }
+  }
+  if (include.includes("har")) {
+    const harArtifact = artifacts.find((a) => a.name === "network.har");
+    if (harArtifact?.url) {
+      try {
+        const hRes = await fetch(harArtifact.url);
+        if (hRes.ok) {
+          result.har = await hRes.json();
+        }
+      } catch {
+      }
+    }
+  }
+  return result;
+}
 async function runWithDefaults(api, payload, defaults) {
   const { apiKey, baseUrl } = getCfg(api);
   if (!apiKey) {
@@ -161,8 +253,12 @@ async function runWithDefaults(api, payload, defaults) {
   const userInclude = payload.include ?? [];
   const userRequestedHar = userInclude.includes("har");
   const harInline = !!payload.harInline;
+  const returnAsync = !!defaults?.returnAsync;
   const merged = { ...payload };
   delete merged.harInline;
+  if (returnAsync) {
+    merged.sync = false;
+  }
   const defaultInc = defaults?.include ?? ["screenshot", "console"];
   merged.include = Array.from(/* @__PURE__ */ new Set([...userInclude, ...defaultInc]));
   merged.inlineConsole = merged.inlineConsole ?? true;
@@ -173,6 +269,46 @@ async function runWithDefaults(api, payload, defaults) {
   const out = { ok: true, mode };
   const { contentType, body, headers, status } = await postRun(baseUrl, apiKey, merged);
   out.rawContentType = contentType ?? void 0;
+  const workspace = getWorkspacePath(api);
+  if (status === 408) {
+    let jobIdFrom408;
+    try {
+      const json408 = JSON.parse(Buffer.from(body).toString("utf8"));
+      jobIdFrom408 = json408.job_id;
+    } catch {
+    }
+    if (!jobIdFrom408) {
+      out.ok = false;
+      out.error = "Sync poll timed out but no job_id in 408 response";
+      return out;
+    }
+    out.job_id = jobIdFrom408;
+    if (returnAsync) {
+      out.status = "submitted";
+      return out;
+    }
+    const scriptTimeoutMs = (payload.timeout_sec ?? 60) * 1e3;
+    const pollMaxMs = scriptTimeoutMs + 3e4;
+    const jobStatus = await pollJobStatus(baseUrl, apiKey, jobIdFrom408, pollMaxMs);
+    if (jobStatus.status === "poll_timeout" || jobStatus.status === "poll_error" || jobStatus.status === "failed") {
+      out.ok = false;
+      out.status = jobStatus.status;
+      out.error = jobStatus.error || `Job ${jobStatus.status}`;
+      return out;
+    }
+    const artifacts = await fetchArtifactsAndBuild(baseUrl, apiKey, jobIdFrom408, merged.include);
+    Object.assign(out, artifacts);
+    out.job_id = jobIdFrom408;
+    out.status = jobStatus.status;
+    out.duration_ms = jobStatus.duration_ms;
+    if (jobStatus.status !== "completed") {
+      out.ok = false;
+      if (jobStatus.timeout) out.timeout = jobStatus.timeout;
+      if (jobStatus.error) out.error = jobStatus.error;
+    }
+    await applySafetySpec(out, { workspace, harInline });
+    return out;
+  }
   if (status >= 400) {
     try {
       const txt2 = Buffer.from(body).toString("utf8");
@@ -191,15 +327,42 @@ async function runWithDefaults(api, payload, defaults) {
     const duration = headers.get("x-duration-ms");
     out.duration_ms = duration ? Number(duration) : void 0;
     out.sync = true;
-    const workspace2 = getWorkspacePath(api);
-    await applySafetySpec(out, { workspace: workspace2, harInline });
+    await applySafetySpec(out, { workspace, harInline });
     return out;
   }
   const txt = Buffer.from(body).toString("utf8");
   const json = JSON.parse(txt);
   Object.assign(out, json);
   out.job_id = json.job_id ?? json.jobId ?? out.job_id;
-  const workspace = getWorkspacePath(api);
+  if (status === 202 && out.job_id && json.status_url) {
+    if (returnAsync) {
+      out.status = "submitted";
+      return out;
+    }
+    const scriptTimeoutMs = (payload.timeout_sec ?? 60) * 1e3;
+    const pollMaxMs = scriptTimeoutMs + 3e4;
+    const jobStatus = await pollJobStatus(baseUrl, apiKey, out.job_id, pollMaxMs);
+    if (jobStatus.status === "poll_timeout" || jobStatus.status === "poll_error" || jobStatus.status === "failed") {
+      out.ok = false;
+      out.status = jobStatus.status;
+      out.error = jobStatus.error || `Job ${jobStatus.status}`;
+      return out;
+    }
+    const artifacts = await fetchArtifactsAndBuild(baseUrl, apiKey, out.job_id, merged.include);
+    Object.assign(out, artifacts);
+    out.status = jobStatus.status;
+    out.duration_ms = jobStatus.duration_ms;
+    if (jobStatus.status !== "completed") {
+      out.ok = false;
+      if (jobStatus.timeout) out.timeout = jobStatus.timeout;
+      if (jobStatus.error) out.error = jobStatus.error;
+    }
+    await applySafetySpec(out, { workspace, harInline });
+    return out;
+  }
+  if (json.status === "completed_timeout" || json.status === "completed_error") {
+    out.ok = false;
+  }
   await applySafetySpec(out, { workspace, harInline });
   return out;
 }
@@ -207,19 +370,61 @@ function register(api) {
   api.registerTool(
     {
       name: "riddle_run",
-      description: 'Run a Riddle job (pass-through payload) against https://api.riddledc.com/v1/run. Supports url/urls/steps/script. Returns screenshot + console by default; pass include:["har"] to opt in to HAR capture.',
+      description: 'Run a Riddle job (pass-through payload) against https://api.riddledc.com/v1/run. Supports url/urls/steps/script. Returns screenshot + console by default; pass include:["har"] to opt in to HAR capture. Set async:true to return immediately with job_id (use riddle_poll to check status later).',
       parameters: import_typebox.Type.Object({
-        payload: import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.Any())
+        payload: import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.Any()),
+        async: import_typebox.Type.Optional(import_typebox.Type.Boolean({ description: "Return job_id immediately without waiting for completion. Use riddle_poll to check status." }))
       }),
       async execute(_id, params) {
         const result = await runWithDefaults(api, params.payload, {
-          include: ["screenshot", "console", "result"]
+          include: ["screenshot", "console", "result"],
+          returnAsync: !!params.async
         });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     },
     { optional: true }
   );
+  api.registerTool(
+    {
+      name: "riddle_poll",
+      description: "Poll the status of an async Riddle job. Use after submitting a job with async:true. Returns current status if still running, or full results (screenshot, console, etc.) if completed.",
+      parameters: import_typebox.Type.Object({
+        job_id: import_typebox.Type.String({ description: "Job ID returned by an async riddle_* call" }),
+        include: import_typebox.Type.Optional(import_typebox.Type.Array(import_typebox.Type.String(), { description: "Artifacts to fetch on completion (default: screenshot, console, result)" })),
+        harInline: import_typebox.Type.Optional(import_typebox.Type.Boolean())
+      }),
+      async execute(_id, params) {
+        if (!params.job_id || typeof params.job_id !== "string") throw new Error("job_id must be a string");
+        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/jobs/${params.job_id}`, {
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!res.ok) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: params.job_id, error: `HTTP ${res.status}` }, null, 2) }] };
+        }
+        const data = await res.json();
+        if (data.status !== "completed" && data.status !== "completed_timeout" && data.status !== "completed_error" && data.status !== "failed") {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: true, job_id: params.job_id, status: data.status, message: "Job still running. Call riddle_poll again later." }, null, 2) }] };
+        }
+        const include = params.include ?? ["screenshot", "console", "result"];
+        const artifacts = await fetchArtifactsAndBuild(baseUrl, apiKey, params.job_id, include);
+        const out = { ok: data.status === "completed", job_id: params.job_id, status: data.status, duration_ms: data.duration_ms, ...artifacts };
+        if (data.status !== "completed") {
+          if (data.timeout) out.timeout = data.timeout;
+          if (data.error) out.error = data.error;
+        }
+        const workspace = getWorkspacePath(api);
+        await applySafetySpec(out, { workspace, harInline: !!params.harInline });
+        return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+      }
+    },
+    { optional: true }
+  );
   api.registerTool(
     {
       name: "riddle_screenshot",
@@ -301,7 +506,7 @@ function register(api) {
   api.registerTool(
     {
       name: "riddle_steps",
-      description: `Riddle: run a workflow in steps mode (goto/click/fill/screenshot/scrape/map/crawl/etc.). Supports authenticated sessions via cookies/localStorage. Data extraction steps: { scrape: true }, { map: { max_pages?: N } }, { crawl: { max_pages?: N, format?: 'json'|'csv' } }. Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts.`,
+      description: `Riddle: run a workflow in steps mode (goto/click/fill/screenshot/scrape/map/crawl/etc.). Supports authenticated sessions via cookies/localStorage. Data extraction steps: { scrape: true }, { map: { max_pages?: N } }, { crawl: { max_pages?: N, format?: 'json'|'csv' } }. Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts. Set async:true to return immediately with job_id (use riddle_poll to check status later).`,
       parameters: import_typebox.Type.Object({
         steps: import_typebox.Type.Array(import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.Any())),
         timeout_sec: import_typebox.Type.Optional(import_typebox.Type.Number()),
@@ -318,7 +523,8 @@ function register(api) {
         options: import_typebox.Type.Optional(import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.Any())),
         include: import_typebox.Type.Optional(import_typebox.Type.Array(import_typebox.Type.String())),
         harInline: import_typebox.Type.Optional(import_typebox.Type.Boolean()),
-        sync: import_typebox.Type.Optional(import_typebox.Type.Boolean())
+        sync: import_typebox.Type.Optional(import_typebox.Type.Boolean()),
+        async: import_typebox.Type.Optional(import_typebox.Type.Boolean({ description: "Return job_id immediately without waiting for completion. Use riddle_poll to check status." }))
       }),
       async execute(_id, params) {
         if (!Array.isArray(params.steps)) throw new Error("steps must be an array");
@@ -332,7 +538,7 @@ function register(api) {
         if (Object.keys(opts).length > 0) payload.options = opts;
         if (params.include) payload.include = params.include;
         if (params.harInline) payload.harInline = params.harInline;
-        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"] });
+        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"], returnAsync: !!params.async });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     },
@@ -341,7 +547,7 @@ function register(api) {
   api.registerTool(
     {
       name: "riddle_script",
-      description: 'Riddle: run full Playwright code (script mode). Supports authenticated sessions via cookies/localStorage. In scripts, use `await injectLocalStorage()` after navigating to the origin to apply localStorage values. Available sandbox helpers: saveScreenshot(label), saveHtml(label), saveJson(name, data), scrape(opts?), map(opts?), crawl(opts?). Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts.',
+      description: 'Riddle: run full Playwright code (script mode). Supports authenticated sessions via cookies/localStorage. In scripts, use `await injectLocalStorage()` after navigating to the origin to apply localStorage values. Available sandbox helpers: saveScreenshot(label), saveHtml(label), saveJson(name, data), scrape(opts?), map(opts?), crawl(opts?). Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts. Set async:true to return immediately with job_id (use riddle_poll to check status later).',
       parameters: import_typebox.Type.Object({
         script: import_typebox.Type.String(),
         timeout_sec: import_typebox.Type.Optional(import_typebox.Type.Number()),
@@ -358,7 +564,8 @@ function register(api) {
         options: import_typebox.Type.Optional(import_typebox.Type.Record(import_typebox.Type.String(), import_typebox.Type.Any())),
         include: import_typebox.Type.Optional(import_typebox.Type.Array(import_typebox.Type.String())),
         harInline: import_typebox.Type.Optional(import_typebox.Type.Boolean()),
-        sync: import_typebox.Type.Optional(import_typebox.Type.Boolean())
+        sync: import_typebox.Type.Optional(import_typebox.Type.Boolean()),
+        async: import_typebox.Type.Optional(import_typebox.Type.Boolean({ description: "Return job_id immediately without waiting for completion. Use riddle_poll to check status." }))
       }),
       async execute(_id, params) {
         if (!params.script || typeof params.script !== "string") throw new Error("script must be a string");
@@ -372,7 +579,7 @@ function register(api) {
         if (Object.keys(opts).length > 0) payload.options = opts;
         if (params.include) payload.include = params.include;
         if (params.harInline) payload.harInline = params.harInline;
-        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"] });
+        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"], returnAsync: !!params.async });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     },
@@ -549,4 +756,108 @@ 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 }
+  );
 }

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 ?? {};
@@ -124,6 +127,95 @@ async function applySafetySpec(result, opts) {
     }
   }
 }
+async function pollJobStatus(baseUrl, apiKey, jobId, maxWaitMs) {
+  const start = Date.now();
+  const POLL_INTERVAL = 2e3;
+  while (Date.now() - start < maxWaitMs) {
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/jobs/${jobId}`, {
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    if (!res.ok) {
+      return { status: "poll_error", error: `HTTP ${res.status}` };
+    }
+    const data = await res.json();
+    if (data.status === "completed" || data.status === "completed_timeout" || data.status === "completed_error" || data.status === "failed") {
+      return data;
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+  }
+  return { status: "poll_timeout", error: `Job ${jobId} did not complete within ${maxWaitMs}ms` };
+}
+async function fetchArtifactsAndBuild(baseUrl, apiKey, jobId, include) {
+  const res = await fetch(
+    `${baseUrl.replace(/\/$/, "")}/v1/jobs/${jobId}/artifacts?include=${include.join(",")}`,
+    { headers: { Authorization: `Bearer ${apiKey}` } }
+  );
+  if (!res.ok) {
+    return { error: `Artifacts fetch failed: HTTP ${res.status}` };
+  }
+  const data = await res.json();
+  const artifacts = data.artifacts || [];
+  const result = {};
+  if (data.status) result._artifactsStatus = data.status;
+  if (data.timeout) result._timeout = data.timeout;
+  if (data.error) result._error = data.error;
+  const screenshots = artifacts.filter((a) => a.name && /\.(png|jpg|jpeg)$/i.test(a.name));
+  if (screenshots.length > 0) {
+    result.screenshots = [];
+    for (const ss of screenshots) {
+      if (!ss.url) continue;
+      try {
+        const imgRes = await fetch(ss.url);
+        if (imgRes.ok) {
+          const buf = await imgRes.arrayBuffer();
+          result.screenshots.push({
+            name: ss.name,
+            data: `data:image/png;base64,${Buffer.from(buf).toString("base64")}`,
+            size: buf.byteLength,
+            url: ss.url
+          });
+        }
+      } catch {
+      }
+    }
+    if (result.screenshots.length > 0) {
+      result.screenshot = result.screenshots[0];
+    }
+  }
+  const consoleArtifact = artifacts.find((a) => a.name === "console.json");
+  if (consoleArtifact?.url) {
+    try {
+      const cRes = await fetch(consoleArtifact.url);
+      if (cRes.ok) {
+        result.console = await cRes.json();
+      }
+    } catch {
+    }
+  }
+  const resultArtifact = artifacts.find((a) => a.name === "result.json");
+  if (resultArtifact?.url) {
+    try {
+      const rRes = await fetch(resultArtifact.url);
+      if (rRes.ok) {
+        result.result = await rRes.json();
+      }
+    } catch {
+    }
+  }
+  if (include.includes("har")) {
+    const harArtifact = artifacts.find((a) => a.name === "network.har");
+    if (harArtifact?.url) {
+      try {
+        const hRes = await fetch(harArtifact.url);
+        if (hRes.ok) {
+          result.har = await hRes.json();
+        }
+      } catch {
+      }
+    }
+  }
+  return result;
+}
 async function runWithDefaults(api, payload, defaults) {
   const { apiKey, baseUrl } = getCfg(api);
   if (!apiKey) {
@@ -137,8 +229,12 @@ async function runWithDefaults(api, payload, defaults) {
   const userInclude = payload.include ?? [];
   const userRequestedHar = userInclude.includes("har");
   const harInline = !!payload.harInline;
+  const returnAsync = !!defaults?.returnAsync;
   const merged = { ...payload };
   delete merged.harInline;
+  if (returnAsync) {
+    merged.sync = false;
+  }
   const defaultInc = defaults?.include ?? ["screenshot", "console"];
   merged.include = Array.from(/* @__PURE__ */ new Set([...userInclude, ...defaultInc]));
   merged.inlineConsole = merged.inlineConsole ?? true;
@@ -149,6 +245,46 @@ async function runWithDefaults(api, payload, defaults) {
   const out = { ok: true, mode };
   const { contentType, body, headers, status } = await postRun(baseUrl, apiKey, merged);
   out.rawContentType = contentType ?? void 0;
+  const workspace = getWorkspacePath(api);
+  if (status === 408) {
+    let jobIdFrom408;
+    try {
+      const json408 = JSON.parse(Buffer.from(body).toString("utf8"));
+      jobIdFrom408 = json408.job_id;
+    } catch {
+    }
+    if (!jobIdFrom408) {
+      out.ok = false;
+      out.error = "Sync poll timed out but no job_id in 408 response";
+      return out;
+    }
+    out.job_id = jobIdFrom408;
+    if (returnAsync) {
+      out.status = "submitted";
+      return out;
+    }
+    const scriptTimeoutMs = (payload.timeout_sec ?? 60) * 1e3;
+    const pollMaxMs = scriptTimeoutMs + 3e4;
+    const jobStatus = await pollJobStatus(baseUrl, apiKey, jobIdFrom408, pollMaxMs);
+    if (jobStatus.status === "poll_timeout" || jobStatus.status === "poll_error" || jobStatus.status === "failed") {
+      out.ok = false;
+      out.status = jobStatus.status;
+      out.error = jobStatus.error || `Job ${jobStatus.status}`;
+      return out;
+    }
+    const artifacts = await fetchArtifactsAndBuild(baseUrl, apiKey, jobIdFrom408, merged.include);
+    Object.assign(out, artifacts);
+    out.job_id = jobIdFrom408;
+    out.status = jobStatus.status;
+    out.duration_ms = jobStatus.duration_ms;
+    if (jobStatus.status !== "completed") {
+      out.ok = false;
+      if (jobStatus.timeout) out.timeout = jobStatus.timeout;
+      if (jobStatus.error) out.error = jobStatus.error;
+    }
+    await applySafetySpec(out, { workspace, harInline });
+    return out;
+  }
   if (status >= 400) {
     try {
       const txt2 = Buffer.from(body).toString("utf8");
@@ -167,15 +303,42 @@ async function runWithDefaults(api, payload, defaults) {
     const duration = headers.get("x-duration-ms");
     out.duration_ms = duration ? Number(duration) : void 0;
     out.sync = true;
-    const workspace2 = getWorkspacePath(api);
-    await applySafetySpec(out, { workspace: workspace2, harInline });
+    await applySafetySpec(out, { workspace, harInline });
     return out;
   }
   const txt = Buffer.from(body).toString("utf8");
   const json = JSON.parse(txt);
   Object.assign(out, json);
   out.job_id = json.job_id ?? json.jobId ?? out.job_id;
-  const workspace = getWorkspacePath(api);
+  if (status === 202 && out.job_id && json.status_url) {
+    if (returnAsync) {
+      out.status = "submitted";
+      return out;
+    }
+    const scriptTimeoutMs = (payload.timeout_sec ?? 60) * 1e3;
+    const pollMaxMs = scriptTimeoutMs + 3e4;
+    const jobStatus = await pollJobStatus(baseUrl, apiKey, out.job_id, pollMaxMs);
+    if (jobStatus.status === "poll_timeout" || jobStatus.status === "poll_error" || jobStatus.status === "failed") {
+      out.ok = false;
+      out.status = jobStatus.status;
+      out.error = jobStatus.error || `Job ${jobStatus.status}`;
+      return out;
+    }
+    const artifacts = await fetchArtifactsAndBuild(baseUrl, apiKey, out.job_id, merged.include);
+    Object.assign(out, artifacts);
+    out.status = jobStatus.status;
+    out.duration_ms = jobStatus.duration_ms;
+    if (jobStatus.status !== "completed") {
+      out.ok = false;
+      if (jobStatus.timeout) out.timeout = jobStatus.timeout;
+      if (jobStatus.error) out.error = jobStatus.error;
+    }
+    await applySafetySpec(out, { workspace, harInline });
+    return out;
+  }
+  if (json.status === "completed_timeout" || json.status === "completed_error") {
+    out.ok = false;
+  }
   await applySafetySpec(out, { workspace, harInline });
   return out;
 }
@@ -183,19 +346,61 @@ function register(api) {
   api.registerTool(
     {
       name: "riddle_run",
-      description: 'Run a Riddle job (pass-through payload) against https://api.riddledc.com/v1/run. Supports url/urls/steps/script. Returns screenshot + console by default; pass include:["har"] to opt in to HAR capture.',
+      description: 'Run a Riddle job (pass-through payload) against https://api.riddledc.com/v1/run. Supports url/urls/steps/script. Returns screenshot + console by default; pass include:["har"] to opt in to HAR capture. Set async:true to return immediately with job_id (use riddle_poll to check status later).',
       parameters: Type.Object({
-        payload: Type.Record(Type.String(), Type.Any())
+        payload: Type.Record(Type.String(), Type.Any()),
+        async: Type.Optional(Type.Boolean({ description: "Return job_id immediately without waiting for completion. Use riddle_poll to check status." }))
       }),
       async execute(_id, params) {
         const result = await runWithDefaults(api, params.payload, {
-          include: ["screenshot", "console", "result"]
+          include: ["screenshot", "console", "result"],
+          returnAsync: !!params.async
         });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     },
     { optional: true }
   );
+  api.registerTool(
+    {
+      name: "riddle_poll",
+      description: "Poll the status of an async Riddle job. Use after submitting a job with async:true. Returns current status if still running, or full results (screenshot, console, etc.) if completed.",
+      parameters: Type.Object({
+        job_id: Type.String({ description: "Job ID returned by an async riddle_* call" }),
+        include: Type.Optional(Type.Array(Type.String(), { description: "Artifacts to fetch on completion (default: screenshot, console, result)" })),
+        harInline: Type.Optional(Type.Boolean())
+      }),
+      async execute(_id, params) {
+        if (!params.job_id || typeof params.job_id !== "string") throw new Error("job_id must be a string");
+        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/jobs/${params.job_id}`, {
+          headers: { Authorization: `Bearer ${apiKey}` }
+        });
+        if (!res.ok) {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: false, job_id: params.job_id, error: `HTTP ${res.status}` }, null, 2) }] };
+        }
+        const data = await res.json();
+        if (data.status !== "completed" && data.status !== "completed_timeout" && data.status !== "completed_error" && data.status !== "failed") {
+          return { content: [{ type: "text", text: JSON.stringify({ ok: true, job_id: params.job_id, status: data.status, message: "Job still running. Call riddle_poll again later." }, null, 2) }] };
+        }
+        const include = params.include ?? ["screenshot", "console", "result"];
+        const artifacts = await fetchArtifactsAndBuild(baseUrl, apiKey, params.job_id, include);
+        const out = { ok: data.status === "completed", job_id: params.job_id, status: data.status, duration_ms: data.duration_ms, ...artifacts };
+        if (data.status !== "completed") {
+          if (data.timeout) out.timeout = data.timeout;
+          if (data.error) out.error = data.error;
+        }
+        const workspace = getWorkspacePath(api);
+        await applySafetySpec(out, { workspace, harInline: !!params.harInline });
+        return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+      }
+    },
+    { optional: true }
+  );
   api.registerTool(
     {
       name: "riddle_screenshot",
@@ -277,7 +482,7 @@ function register(api) {
   api.registerTool(
     {
       name: "riddle_steps",
-      description: `Riddle: run a workflow in steps mode (goto/click/fill/screenshot/scrape/map/crawl/etc.). Supports authenticated sessions via cookies/localStorage. Data extraction steps: { scrape: true }, { map: { max_pages?: N } }, { crawl: { max_pages?: N, format?: 'json'|'csv' } }. Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts.`,
+      description: `Riddle: run a workflow in steps mode (goto/click/fill/screenshot/scrape/map/crawl/etc.). Supports authenticated sessions via cookies/localStorage. Data extraction steps: { scrape: true }, { map: { max_pages?: N } }, { crawl: { max_pages?: N, format?: 'json'|'csv' } }. Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts. Set async:true to return immediately with job_id (use riddle_poll to check status later).`,
       parameters: Type.Object({
         steps: Type.Array(Type.Record(Type.String(), Type.Any())),
         timeout_sec: Type.Optional(Type.Number()),
@@ -294,7 +499,8 @@ function register(api) {
         options: Type.Optional(Type.Record(Type.String(), Type.Any())),
         include: Type.Optional(Type.Array(Type.String())),
         harInline: Type.Optional(Type.Boolean()),
-        sync: Type.Optional(Type.Boolean())
+        sync: Type.Optional(Type.Boolean()),
+        async: Type.Optional(Type.Boolean({ description: "Return job_id immediately without waiting for completion. Use riddle_poll to check status." }))
       }),
       async execute(_id, params) {
         if (!Array.isArray(params.steps)) throw new Error("steps must be an array");
@@ -308,7 +514,7 @@ function register(api) {
         if (Object.keys(opts).length > 0) payload.options = opts;
         if (params.include) payload.include = params.include;
         if (params.harInline) payload.harInline = params.harInline;
-        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"] });
+        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"], returnAsync: !!params.async });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     },
@@ -317,7 +523,7 @@ function register(api) {
   api.registerTool(
     {
       name: "riddle_script",
-      description: 'Riddle: run full Playwright code (script mode). Supports authenticated sessions via cookies/localStorage. In scripts, use `await injectLocalStorage()` after navigating to the origin to apply localStorage values. Available sandbox helpers: saveScreenshot(label), saveHtml(label), saveJson(name, data), scrape(opts?), map(opts?), crawl(opts?). Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts.',
+      description: 'Riddle: run full Playwright code (script mode). Supports authenticated sessions via cookies/localStorage. In scripts, use `await injectLocalStorage()` after navigating to the origin to apply localStorage values. Available sandbox helpers: saveScreenshot(label), saveHtml(label), saveJson(name, data), scrape(opts?), map(opts?), crawl(opts?). Returns screenshot + console by default; pass include:["har","data","urls","dataset","sitemap"] for additional artifacts. Set async:true to return immediately with job_id (use riddle_poll to check status later).',
       parameters: Type.Object({
         script: Type.String(),
         timeout_sec: Type.Optional(Type.Number()),
@@ -334,7 +540,8 @@ function register(api) {
         options: Type.Optional(Type.Record(Type.String(), Type.Any())),
         include: Type.Optional(Type.Array(Type.String())),
         harInline: Type.Optional(Type.Boolean()),
-        sync: Type.Optional(Type.Boolean())
+        sync: Type.Optional(Type.Boolean()),
+        async: Type.Optional(Type.Boolean({ description: "Return job_id immediately without waiting for completion. Use riddle_poll to check status." }))
       }),
       async execute(_id, params) {
         if (!params.script || typeof params.script !== "string") throw new Error("script must be a string");
@@ -348,7 +555,7 @@ function register(api) {
         if (Object.keys(opts).length > 0) payload.options = opts;
         if (params.include) payload.include = params.include;
         if (params.harInline) payload.harInline = params.harInline;
-        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"] });
+        const result = await runWithDefaults(api, payload, { include: ["screenshot", "console", "result", "data", "urls", "dataset", "sitemap", "visual_diff"], returnAsync: !!params.async });
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       }
     },
@@ -525,6 +732,110 @@ 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 }
+  );
 }
 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.5",
-  "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.6.0",
+  "notes": "0.6.0: Added riddle_preview and riddle_preview_delete tools for ephemeral preview hosting at preview.riddledc.com.",
   "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"
@@ -33,10 +34,13 @@
         "riddle_steps",
         "riddle_script",
         "riddle_run",
+        "riddle_poll",
         "riddle_scrape",
         "riddle_map",
         "riddle_crawl",
-        "riddle_visual_diff"
+        "riddle_visual_diff",
+        "riddle_preview",
+        "riddle_preview_delete"
       ],
       "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.5",
+  "version": "0.6.0",
   "description": "OpenClaw integration package for RiddleDC (no secrets).",
   "license": "MIT",
   "author": "RiddleDC",