@riddledc/riddle-proof 0.5.53 → 0.5.55

package/dist/index.cjs

@@ -363,6 +363,7 @@ function visualDeltaRequiredForState(state = {}) {
   const bundle = objectValue(state?.evidence_bundle);
   const contract = objectValue(bundle.artifact_contract);
   const required = objectValue(contract.required);
+  if (required.visual_delta === false) return false;
   return required.visual_delta === true || VISUAL_FIRST_MODES.has(normalizedVerificationMode(state));
 }
 function visualDeltaForState(state = {}) {
@@ -1407,9 +1408,9 @@ function cleanupMergedProofRun(state, repoDir, params, prState) {
   const baseBranch = stringValue(prState.base_branch) || stringValue(state?.base_branch) || "main";
   let fetchedBase = params.fetch_base === false;
   if (params.fetch_base !== false && baseBranch) {
-    const fetch = commandResult("git", ["fetch", "origin", baseBranch], repoDir, 12e4);
-    cleanup.fetch = fetch.ok ? { ok: true, base_branch: baseBranch } : { ok: false, base_branch: baseBranch, error: fetch.stderr.slice(0, 300) };
-    if (fetch.ok) {
+    const fetch2 = commandResult("git", ["fetch", "origin", baseBranch], repoDir, 12e4);
+    cleanup.fetch = fetch2.ok ? { ok: true, base_branch: baseBranch } : { ok: false, base_branch: baseBranch, error: fetch2.stderr.slice(0, 300) };
+    if (fetch2.ok) {
       fetchedBase = true;
       state.base_synced_at = (/* @__PURE__ */ new Date()).toISOString();
       state.base_branch = baseBranch;
@@ -2775,6 +2776,10 @@ __export(index_exports, {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT: () => DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT: () => DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,
   DEFAULT_DIAGNOSTIC_STRING_LIMIT: () => DEFAULT_DIAGNOSTIC_STRING_LIMIT,
+  DEFAULT_RIDDLE_API_BASE_URL: () => DEFAULT_RIDDLE_API_BASE_URL,
+  DEFAULT_RIDDLE_API_KEY_FILE: () => DEFAULT_RIDDLE_API_KEY_FILE,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION: () => RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: () => RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: () => RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
@@ -2784,11 +2789,14 @@ __export(index_exports, {
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_VERSION: () => RIDDLE_PROOF_VISUAL_SESSION_VERSION,
+  RiddleApiError: () => RiddleApiError,
   appendCaptureDiagnostic: () => appendCaptureDiagnostic,
   appendRunEvent: () => appendRunEvent,
   appendStageHeartbeat: () => appendStageHeartbeat,
   applyPrLifecycleState: () => applyPrLifecycleState,
   applyTerminalMetadata: () => applyTerminalMetadata,
+  assessBasicGameplayEvidence: () => assessBasicGameplayEvidence,
+  assessBasicGameplayRoute: () => assessBasicGameplayRoute,
   assessPlayabilityEvidence: () => assessPlayabilityEvidence,
   authorPacketPayloadFromCheckpointResponse: () => authorPacketPayloadFromCheckpointResponse,
   buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
@@ -2807,14 +2815,18 @@ __export(index_exports, {
   createDisabledRiddleProofAgentAdapter: () => createDisabledRiddleProofAgentAdapter,
   createLocalAgentAdapter: () => createCodexExecAgentAdapter,
   createLocalAgentJsonRunner: () => createCodexExecJsonRunner,
+  createRiddleApiClient: () => createRiddleApiClient,
   createRiddleProofRunCard: () => createRiddleProofRunCard,
   createRunResult: () => createRunResult,
   createRunState: () => createRunState,
   createRunStatusSnapshot: () => createRunStatusSnapshot,
+  deployRiddleStaticPreview: () => deployRiddleStaticPreview,
+  extractBasicGameplayEvidence: () => extractBasicGameplayEvidence,
   extractPlayabilityEvidence: () => extractPlayabilityEvidence,
   isDuplicateCheckpointResponse: () => isDuplicateCheckpointResponse,
   isRiddleProofPlayabilityMode: () => isRiddleProofPlayabilityMode,
   isSuccessfulStatus: () => isSuccessfulStatus,
+  isTerminalRiddleJobStatus: () => isTerminalRiddleJobStatus,
   isTerminalStatus: () => isTerminalStatus,
   nonEmptyString: () => nonEmptyString,
   normalizeCheckpointResponse: () => normalizeCheckpointResponse,
@@ -2822,15 +2834,20 @@ __export(index_exports, {
   normalizePrLifecycleState: () => normalizePrLifecycleState,
   normalizeRunParams: () => normalizeRunParams,
   normalizeTerminalMetadata: () => normalizeTerminalMetadata,
+  parseRiddleViewport: () => parseRiddleViewport,
   parseVisualProofSession: () => parseVisualProofSession,
+  pollRiddleJob: () => pollRiddleJob,
   proofContractFromAuthorCheckpointResponse: () => proofContractFromAuthorCheckpointResponse,
   readRiddleProofRunStatus: () => readRiddleProofRunStatus,
   recordValue: () => recordValue,
   redactForProofDiagnostics: () => redactForProofDiagnostics,
+  resolveRiddleApiKey: () => resolveRiddleApiKey,
+  riddleRequestJson: () => riddleRequestJson,
   runCodexExecAgentDoctor: () => runCodexExecAgentDoctor,
   runLocalAgentDoctor: () => runCodexExecAgentDoctor,
   runRiddleProof: () => runRiddleProof,
   runRiddleProofEngineHarness: () => runRiddleProofEngineHarness,
+  runRiddleScript: () => runRiddleScript,
   setRunStatus: () => setRunStatus,
   statePathsForRunState: () => statePathsForRunState,
   summarizeCaptureArtifacts: () => summarizeCaptureArtifacts,
@@ -3495,8 +3512,8 @@ function buildProofAssessmentCheckpointPacket(input) {
   const artifactContract = recordValue(proofAssessmentRequest.artifact_contract) || recordValue(bundle?.artifact_contract);
   const requiredSignals = recordValue(recordValue(artifactContract)?.required);
   const visualDelta = visualDeltaFromState(fullState);
-  const verificationMode = nonEmptyString(input.request.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(bundle?.verification_mode) || "proof";
-  const visualDeltaRequired = requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode);
+  const verificationMode = nonEmptyString(bundle?.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(input.request.verification_mode) || "proof";
+  const visualDeltaRequired = requiredSignals?.visual_delta !== false && (requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode));
   const evidenceIssueCode2 = visualDeltaIssueCode(visualDelta, visualDeltaRequired);
   const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.verify_summary) || "Verify captured evidence and needs a supervising proof assessment.";
   const recoveryHint = evidenceIssueCode2 ? "Required visual_delta evidence is incomplete. Keep this same run in verify/evidence recovery with decision=revise_capture and continue_with_stage=verify unless the evidence proves an implementation or recon problem." : "Assess whether the current artifacts prove the requested change, then choose the next stage.";
@@ -4073,6 +4090,7 @@ function normalizeRunParams(input) {
     leave_draft: input.leave_draft,
     engine_state_path: input.engine_state_path,
     harness_state_path: input.harness_state_path,
+    riddle_engine_module_url: input.riddle_engine_module_url,
     max_iterations: input.max_iterations,
     auto_approve: input.auto_approve,
     dry_run: input.dry_run,
@@ -7597,11 +7615,385 @@ function parseJson(value) {
     return null;
   }
 }
+
+// src/basic-gameplay.ts
+var RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
+var RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+var BASIC_GAMEPLAY_CONTAINER_KEYS = [
+  "basic_gameplay",
+  "basicGameplay",
+  "basic_gameplay_evidence",
+  "basicGameplayEvidence",
+  "gameplay_proof",
+  "gameplayProof"
+];
+function assessBasicGameplayEvidence(evidence, options = {}) {
+  const run = extractBasicGameplayEvidence(evidence);
+  if (!run) {
+    return {
+      version: RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+      evidence_present: false,
+      passed: false,
+      checked_routes: 0,
+      passing_routes: 0,
+      failing_routes: [],
+      failure_counts: {},
+      warning_counts: {},
+      route_results: []
+    };
+  }
+  const routeResults = (run.results || []).map((route) => assessBasicGameplayRoute(route, options));
+  const failingRoutes = routeResults.filter((result) => !result.ok).map((result) => ({
+    name: result.name,
+    path: result.path,
+    failures: result.failures,
+    warnings: result.warnings
+  }));
+  return {
+    version: RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+    evidence_present: true,
+    passed: failingRoutes.length === 0,
+    checked_routes: routeResults.length,
+    passing_routes: routeResults.filter((result) => result.ok).length,
+    failing_routes: failingRoutes,
+    failure_counts: countCodes(routeResults.flatMap((result) => result.failures)),
+    warning_counts: countCodes(routeResults.flatMap((result) => result.warnings)),
+    route_results: routeResults
+  };
+}
+function assessBasicGameplayRoute(route, options = {}) {
+  const maxMobileOverflowPx = options.maxMobileOverflowPx ?? 4;
+  const minBodyTextLength = options.minBodyTextLength ?? 20;
+  const minVisibleLargeNodes = options.minVisibleLargeNodes ?? 3;
+  const minSurfaceLargeNodes = options.minSurfaceLargeNodes ?? 8;
+  const warnOnMissingResetPath = options.warnOnMissingResetPath ?? true;
+  const warnOnConsoleError = options.warnOnConsoleError ?? true;
+  const failOnConsoleError = options.failOnConsoleError ?? false;
+  const failures = [];
+  const warnings = [];
+  const initial = route.initial || {};
+  const timed = route.timed || {};
+  const afterAction = route.after_action || route.afterAction || {};
+  const mobile = route.mobile || {};
+  const timedChange = changed(initial, timed);
+  const actionChange = changed(timed, afterAction);
+  const surfaceVisible = numberValue2(initial.visible_canvas_count) > 0 || numberValue2(initial.enabled_clickable_count) > 0 || numberValue2(initial.visible_large_node_count) >= minSurfaceLargeNodes;
+  const actionResults = listValue2(route.action_results || route.actionResults);
+  const actionAttempted = actionResults.some((result) => result.ok === true && result.action !== "wait");
+  const actionFailed = actionResults.some((result) => result.ok === false && result.action !== "wait");
+  const stateChangeObserved = actionChange.changed || timedChange.changed;
+  const resetPathPresent = numberValue2(initial.reset_control_count) > 0 || numberValue2(timed.reset_control_count) > 0 || numberValue2(afterAction.reset_control_count) > 0;
+  const responseStatus = firstNumber(route.http_status, route.response_status, route.status);
+  const pageErrorCount = numberValue2(route.page_error_count);
+  const consoleErrorCount = numberValue2(route.console_error_count);
+  const mobileOverflowPx = numberValue2(mobile.overflow_px);
+  if (responseStatus !== null && responseStatus >= 400) failures.push("route_http_error");
+  if (pageErrorCount > 0) failures.push("fatal_page_error");
+  if (numberValue2(initial.body_text_length) < minBodyTextLength && numberValue2(initial.visible_large_node_count) < minVisibleLargeNodes) {
+    failures.push("route_blank_or_thin");
+  }
+  if (!surfaceVisible) failures.push("no_game_surface");
+  if (mobileOverflowPx > maxMobileOverflowPx) failures.push("mobile_horizontal_overflow");
+  if (!actionAttempted && !timedChange.changed) failures.push("primary_control_missing");
+  if (actionAttempted && !stateChangeObserved) failures.push("primary_control_inert");
+  if (failOnConsoleError && consoleErrorCount > 0) failures.push("fatal_page_error");
+  if (numberValue2(initial.visible_canvas_count) > 0 && actionAttempted && !timedChange.canvas_changed && !actionChange.canvas_changed && !actionChange.screenshot_changed) {
+    warnings.push("canvas_inert");
+  }
+  if (actionFailed) warnings.push("some_actions_failed");
+  if (warnOnMissingResetPath && !resetPathPresent && route.requires_reset !== false && actionAttempted && stateChangeObserved) {
+    warnings.push("missing_reset_path");
+  }
+  if (warnOnConsoleError && consoleErrorCount > 0) warnings.push("critical_console_error");
+  return {
+    name: route.name,
+    path: route.path,
+    ok: failures.length === 0,
+    failures,
+    warnings,
+    signals: {
+      route_loaded: !failures.includes("route_http_error") && !failures.includes("route_blank_or_thin"),
+      surface_visible: surfaceVisible,
+      action_attempted: actionAttempted,
+      timed_progression_observed: timedChange.changed,
+      first_interaction_observed: actionChange.changed,
+      state_change_observed: stateChangeObserved,
+      mobile_overflow_absent: mobileOverflowPx <= maxMobileOverflowPx,
+      reset_path_present: resetPathPresent,
+      fatal_errors_absent: pageErrorCount === 0
+    },
+    diffs: {
+      timed: timedChange,
+      after_action: actionChange
+    }
+  };
+}
+function extractBasicGameplayEvidence(...sources) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    const found = findBasicGameplayEvidence(source, seen);
+    if (found) return found;
+  }
+  return null;
+}
+function findBasicGameplayEvidence(value, seen, depth = 0) {
+  if (depth > 6 || value === null || value === void 0) return null;
+  if (typeof value === "string") {
+    const parsed = parseJson2(value);
+    return parsed === null ? null : findBasicGameplayEvidence(parsed, seen, depth + 1);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return null;
+    seen.add(value);
+    if (value.some((item) => hasRouteShape(recordValue3(item)))) {
+      return { results: value.filter((item) => hasRouteShape(recordValue3(item))) };
+    }
+    for (const item of value) {
+      const found = findBasicGameplayEvidence(item, seen, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  const record = recordValue3(value);
+  if (!record || seen.has(record)) return null;
+  seen.add(record);
+  if (record.version === RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION || Array.isArray(record.results)) {
+    return {
+      ...record,
+      results: listValue2(record.results).filter((item) => Boolean(recordValue3(item)))
+    };
+  }
+  if (hasRouteShape(record)) {
+    return { results: [record] };
+  }
+  for (const key of BASIC_GAMEPLAY_CONTAINER_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(record, key)) {
+      const nested = findBasicGameplayEvidence(record[key], seen, depth + 1);
+      if (nested) return nested;
+    }
+  }
+  for (const item of Object.values(record)) {
+    const found = findBasicGameplayEvidence(item, seen, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+function hasRouteShape(record) {
+  return Boolean(record && (record.initial || record.after_action || record.afterAction || record.action_results || record.actionResults) && (record.path || record.name));
+}
+function changed(before, after) {
+  const bodyTextChanged = Boolean(before.body_text_hash && after.body_text_hash && before.body_text_hash !== after.body_text_hash);
+  const screenshotChanged = Boolean(before.screenshot_hash && after.screenshot_hash && before.screenshot_hash !== after.screenshot_hash);
+  const beforeCanvasHashes = canvasHashes(before.canvases);
+  const afterCanvasHashes = canvasHashes(after.canvases);
+  const canvasChanged = Boolean(beforeCanvasHashes && afterCanvasHashes && beforeCanvasHashes !== afterCanvasHashes);
+  return {
+    body_text_changed: bodyTextChanged,
+    screenshot_changed: screenshotChanged,
+    canvas_changed: canvasChanged,
+    changed: bodyTextChanged || screenshotChanged || canvasChanged
+  };
+}
+function canvasHashes(canvases) {
+  return (canvases || []).map((canvas) => canvas.hash).filter(Boolean).join("|");
+}
+function countCodes(codes) {
+  const counts = {};
+  for (const code of codes) counts[code] = (counts[code] || 0) + 1;
+  return counts;
+}
+function firstNumber(...values) {
+  for (const value of values) {
+    const number = numericValue3(value);
+    if (number !== null) return number;
+  }
+  return null;
+}
+function numberValue2(value) {
+  return numericValue3(value) ?? 0;
+}
+function numericValue3(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function recordValue3(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function listValue2(value) {
+  return Array.isArray(value) ? value : [];
+}
+function parseJson2(value) {
+  const trimmed = value.trim();
+  if (!trimmed || !/^[{[]/.test(trimmed)) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+// src/riddle-client.ts
+var import_node_child_process4 = require("child_process");
+var import_node_fs5 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path5 = __toESM(require("path"), 1);
+var DEFAULT_RIDDLE_API_BASE_URL = "https://api.riddledc.com";
+var DEFAULT_RIDDLE_API_KEY_FILE = "/tmp/riddle-api-key";
+var RiddleApiError = class extends Error {
+  constructor(pathname, status, body) {
+    super(`Riddle API ${pathname} failed HTTP ${status}: ${body}`);
+    this.name = "RiddleApiError";
+    this.status = status;
+    this.body = body;
+    this.path = pathname;
+  }
+};
+function normalizeBaseUrl(value) {
+  return (value || DEFAULT_RIDDLE_API_BASE_URL).replace(/\/$/, "");
+}
+function fetchFor(config = {}) {
+  return config.fetchImpl || fetch;
+}
+function resolveRiddleApiKey(config = {}) {
+  if (config.apiKey?.trim()) return config.apiKey.trim();
+  if (process.env.RIDDLE_API_KEY?.trim()) return process.env.RIDDLE_API_KEY.trim();
+  const keyFile = config.apiKeyFile || process.env.RIDDLE_API_KEY_FILE || DEFAULT_RIDDLE_API_KEY_FILE;
+  if ((0, import_node_fs5.existsSync)(keyFile)) {
+    const key = (0, import_node_fs5.readFileSync)(keyFile, "utf8").trim();
+    if (key) return key;
+  }
+  throw new Error(`Riddle API key missing. Set RIDDLE_API_KEY or write ${DEFAULT_RIDDLE_API_KEY_FILE}.`);
+}
+async function riddleRequestJson(config, pathname, init = {}) {
+  const response = await fetchFor(config)(`${normalizeBaseUrl(config.apiBaseUrl)}${pathname}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${resolveRiddleApiKey(config)}`,
+      "Content-Type": "application/json",
+      ...init.headers || {}
+    }
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+  }
+  if (!response.ok) throw new RiddleApiError(pathname, response.status, text);
+  return json ?? text;
+}
+async function deployRiddleStaticPreview(config, directory, label) {
+  if (!directory?.trim()) throw new Error("directory is required");
+  if (!label?.trim()) throw new Error("label is required");
+  const created = await riddleRequestJson(config, "/v1/preview", {
+    method: "POST",
+    body: JSON.stringify({ framework: "spa", label })
+  });
+  const id = String(created.id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!id || !uploadUrl) throw new Error("Riddle preview create response was missing id or upload_url.");
+  const scratch = (0, import_node_fs5.mkdtempSync)(import_node_path5.default.join((0, import_node_os2.tmpdir)(), "riddle-preview-upload-"));
+  const tarball = import_node_path5.default.join(scratch, `${id}.tar.gz`);
+  try {
+    (0, import_node_child_process4.execFileSync)("tar", ["czf", tarball, "-C", directory, "."], { stdio: "pipe" });
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: (0, import_node_fs5.readFileSync)(tarball)
+    });
+    if (!upload.ok) {
+      throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+    }
+  } finally {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+  }
+  const published = await riddleRequestJson(config, `/v1/preview/${id}/publish`, {
+    method: "POST"
+  });
+  return {
+    ok: true,
+    id: String(published.id || id),
+    label,
+    preview_url: String(published.preview_url || ""),
+    file_count: typeof published.file_count === "number" ? published.file_count : void 0,
+    total_bytes: typeof published.total_bytes === "number" ? published.total_bytes : void 0,
+    expires_at: typeof created.expires_at === "string" ? created.expires_at : void 0,
+    raw: published
+  };
+}
+function parseRiddleViewport(value) {
+  if (!value) return void 0;
+  const match = /^(\d+)x(\d+)$/.exec(value.trim());
+  if (!match) throw new Error("viewport must look like 1280x720");
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+async function runRiddleScript(config, input) {
+  if (!input.url?.trim()) throw new Error("url is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const payload = {
+    url: input.url,
+    script: input.script,
+    sync: input.sync ?? false,
+    timeout_sec: input.timeoutSec || 120
+  };
+  if (input.viewport) payload.viewport = input.viewport;
+  if (input.include) payload.include = input.include;
+  if (input.options) payload.options = input.options;
+  return riddleRequestJson(config, "/v1/run", {
+    method: "POST",
+    body: JSON.stringify(payload)
+  });
+}
+function isTerminalRiddleJobStatus(status) {
+  return ["completed", "complete", "completed_error", "completed_timeout", "failed"].includes(String(status || ""));
+}
+async function pollRiddleJob(config, jobId, options = {}) {
+  if (!jobId?.trim()) throw new Error("jobId is required");
+  const attempts = options.attempts || (options.wait ? 60 : 1);
+  const intervalMs = options.intervalMs || 2e3;
+  let job = null;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/jobs/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+  const status = job?.status ? String(job.status) : null;
+  if (!isTerminalRiddleJobStatus(status)) {
+    return { ok: true, job_id: jobId, status, terminal: false, job };
+  }
+  const artifacts = await riddleRequestJson(config, `/v1/jobs/${jobId}/artifacts`);
+  return {
+    ok: status === "completed" || status === "complete",
+    job_id: jobId,
+    status,
+    terminal: true,
+    job,
+    artifacts
+  };
+}
+function createRiddleApiClient(config = {}) {
+  return {
+    requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
+    deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
+    runScript: (input) => runRiddleScript(config, input),
+    pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,
   DEFAULT_DIAGNOSTIC_STRING_LIMIT,
+  DEFAULT_RIDDLE_API_BASE_URL,
+  DEFAULT_RIDDLE_API_KEY_FILE,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
@@ -7611,11 +8003,14 @@ function parseJson(value) {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
   RIDDLE_PROOF_VISUAL_SESSION_VERSION,
+  RiddleApiError,
   appendCaptureDiagnostic,
   appendRunEvent,
   appendStageHeartbeat,
   applyPrLifecycleState,
   applyTerminalMetadata,
+  assessBasicGameplayEvidence,
+  assessBasicGameplayRoute,
   assessPlayabilityEvidence,
   authorPacketPayloadFromCheckpointResponse,
   buildAuthorCheckpointPacket,
@@ -7634,14 +8029,18 @@ function parseJson(value) {
   createDisabledRiddleProofAgentAdapter,
   createLocalAgentAdapter,
   createLocalAgentJsonRunner,
+  createRiddleApiClient,
   createRiddleProofRunCard,
   createRunResult,
   createRunState,
   createRunStatusSnapshot,
+  deployRiddleStaticPreview,
+  extractBasicGameplayEvidence,
   extractPlayabilityEvidence,
   isDuplicateCheckpointResponse,
   isRiddleProofPlayabilityMode,
   isSuccessfulStatus,
+  isTerminalRiddleJobStatus,
   isTerminalStatus,
   nonEmptyString,
   normalizeCheckpointResponse,
@@ -7649,15 +8048,20 @@ function parseJson(value) {
   normalizePrLifecycleState,
   normalizeRunParams,
   normalizeTerminalMetadata,
+  parseRiddleViewport,
   parseVisualProofSession,
+  pollRiddleJob,
   proofContractFromAuthorCheckpointResponse,
   readRiddleProofRunStatus,
   recordValue,
   redactForProofDiagnostics,
+  resolveRiddleApiKey,
+  riddleRequestJson,
   runCodexExecAgentDoctor,
   runLocalAgentDoctor,
   runRiddleProof,
   runRiddleProofEngineHarness,
+  runRiddleScript,
   setRunStatus,
   statePathsForRunState,
   summarizeCaptureArtifacts,

package/dist/index.d.cts

@@ -9,3 +9,5 @@ export { CodexExecAgentConfig, CodexJsonRequest, CodexJsonResult, CodexJsonRunne
 export { CreateCaptureDiagnosticInput, DEFAULT_DIAGNOSTIC_ARRAY_LIMIT, DEFAULT_DIAGNOSTIC_HISTORY_LIMIT, DEFAULT_DIAGNOSTIC_STRING_LIMIT, RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION, RiddleProofArtifactSummary, RiddleProofCaptureArtifactSummary, RiddleProofCaptureDiagnostic, RiddleProofDiagnosticRedactionOptions, appendCaptureDiagnostic, createCaptureDiagnostic, redactForProofDiagnostics, summarizeCaptureArtifacts } from './diagnostics.cjs';
 export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis } from './proof-session.cjs';
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.cjs';
+export { AssessBasicGameplayOptions, BasicGameplayActionResult, BasicGameplayCanvasState, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayMobileEvidence, BasicGameplaySnapshot, BasicGameplayWarningCode, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, extractBasicGameplayEvidence } from './basic-gameplay.cjs';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript } from './riddle-client.cjs';

package/dist/index.d.ts

@@ -9,3 +9,5 @@ export { CodexExecAgentConfig, CodexJsonRequest, CodexJsonResult, CodexJsonRunne
 export { CreateCaptureDiagnosticInput, DEFAULT_DIAGNOSTIC_ARRAY_LIMIT, DEFAULT_DIAGNOSTIC_HISTORY_LIMIT, DEFAULT_DIAGNOSTIC_STRING_LIMIT, RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION, RiddleProofArtifactSummary, RiddleProofCaptureArtifactSummary, RiddleProofCaptureDiagnostic, RiddleProofDiagnosticRedactionOptions, appendCaptureDiagnostic, createCaptureDiagnostic, redactForProofDiagnostics, summarizeCaptureArtifacts } from './diagnostics.js';
 export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis } from './proof-session.js';
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.js';
+export { AssessBasicGameplayOptions, BasicGameplayActionResult, BasicGameplayCanvasState, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayMobileEvidence, BasicGameplaySnapshot, BasicGameplayWarningCode, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, extractBasicGameplayEvidence } from './basic-gameplay.js';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript } from './riddle-client.js';