@riddledc/openclaw-riddledc 0.5.4 → 0.5.6

package/CHECKSUMS.txt

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

package/dist/index.cjs

@@ -99,7 +99,8 @@ async function applySafetySpec(result, opts) {
     }
     if (base64Data) {
       const ref = await writeArtifactBinary(opts.workspace, "screenshots", `${jobId}.png`, base64Data);
-      result.screenshot = { saved: ref.path, sizeBytes: ref.sizeBytes };
+      const cdnUrl = typeof result.screenshot === "object" ? result.screenshot.url : void 0;
+      result.screenshot = { saved: ref.path, sizeBytes: ref.sizeBytes, ...cdnUrl ? { url: cdnUrl } : {} };
     }
   }
   if (Array.isArray(result.screenshots)) {
@@ -107,6 +108,7 @@ async function applySafetySpec(result, opts) {
     for (let i = 0; i < result.screenshots.length; i++) {
       const ss = result.screenshots[i];
       let base64Data = null;
+      const cdnUrl = typeof ss === "object" ? ss.url : void 0;
       if (typeof ss === "string") {
         base64Data = ss;
       } else if (typeof ss === "object" && ss.data) {
@@ -114,7 +116,7 @@ async function applySafetySpec(result, opts) {
       }
       if (base64Data) {
         const ref = await writeArtifactBinary(opts.workspace, "screenshots", `${jobId}-${i}.png`, base64Data);
-        savedRefs.push({ saved: ref.path, sizeBytes: ref.sizeBytes });
+        savedRefs.push({ saved: ref.path, sizeBytes: ref.sizeBytes, ...cdnUrl ? { url: cdnUrl } : {} });
       }
     }
     result.screenshots = savedRefs;
@@ -146,6 +148,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) {
@@ -159,8 +250,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;
@@ -171,6 +266,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");
@@ -189,15 +324,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;
 }
@@ -205,19 +367,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",
@@ -299,7 +503,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()),
@@ -316,7 +520,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");
@@ -330,7 +535,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) }] };
       }
     },
@@ -339,7 +544,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()),
@@ -356,7 +561,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");
@@ -370,7 +576,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) }] };
       }
     },

package/dist/index.js

@@ -75,7 +75,8 @@ async function applySafetySpec(result, opts) {
     }
     if (base64Data) {
       const ref = await writeArtifactBinary(opts.workspace, "screenshots", `${jobId}.png`, base64Data);
-      result.screenshot = { saved: ref.path, sizeBytes: ref.sizeBytes };
+      const cdnUrl = typeof result.screenshot === "object" ? result.screenshot.url : void 0;
+      result.screenshot = { saved: ref.path, sizeBytes: ref.sizeBytes, ...cdnUrl ? { url: cdnUrl } : {} };
     }
   }
   if (Array.isArray(result.screenshots)) {
@@ -83,6 +84,7 @@ async function applySafetySpec(result, opts) {
     for (let i = 0; i < result.screenshots.length; i++) {
       const ss = result.screenshots[i];
       let base64Data = null;
+      const cdnUrl = typeof ss === "object" ? ss.url : void 0;
       if (typeof ss === "string") {
         base64Data = ss;
       } else if (typeof ss === "object" && ss.data) {
@@ -90,7 +92,7 @@ async function applySafetySpec(result, opts) {
       }
       if (base64Data) {
         const ref = await writeArtifactBinary(opts.workspace, "screenshots", `${jobId}-${i}.png`, base64Data);
-        savedRefs.push({ saved: ref.path, sizeBytes: ref.sizeBytes });
+        savedRefs.push({ saved: ref.path, sizeBytes: ref.sizeBytes, ...cdnUrl ? { url: cdnUrl } : {} });
       }
     }
     result.screenshots = savedRefs;
@@ -122,6 +124,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) {
@@ -135,8 +226,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;
@@ -147,6 +242,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");
@@ -165,15 +300,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;
 }
@@ -181,19 +343,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",
@@ -275,7 +479,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()),
@@ -292,7 +496,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");
@@ -306,7 +511,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) }] };
       }
     },
@@ -315,7 +520,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()),
@@ -332,7 +537,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");
@@ -346,7 +552,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) }] };
       }
     },

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-riddledc",
   "name": "Riddle",
   "description": "Riddle (riddledc.com) hosted browser API tools for OpenClaw agents.",
-  "version": "0.5.4",
+  "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.",
   "type": "plugin",
   "bundledSkills": [],
@@ -33,6 +33,7 @@
         "riddle_steps",
         "riddle_script",
         "riddle_run",
+        "riddle_poll",
         "riddle_scrape",
         "riddle_map",
         "riddle_crawl",

package/package.json

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