@riddledc/riddle-proof 0.7.212 → 0.7.213

package/README.md

@@ -202,6 +202,12 @@ generic inline-script warning threshold. Use `--strict=true` when you
 deliberately want Riddle's non-critical script-safety warnings to block the run.
 Critical script-safety violations remain blocked by Riddle either way.
 
+Hosted `run-profile` checks `/v1/balance` before submitting Riddle jobs. For a
+split viewport matrix, the preflight estimates the 30-second hosted minimum per
+viewport and returns an `environment_blocked` result without starting partial
+jobs when the account balance cannot cover the intended sweep. Use
+`--balance-preflight=false` to bypass this check.
+
 Use `--viewport-name <name>` to run only one named viewport from a
 multi-viewport profile while preserving viewport-scoped setup actions and
 checks:

package/dist/{chunk-PPZ5A5MC.js → chunk-33XO7WFI.js}

@@ -23,16 +23,23 @@ function normalizeBaseUrl(value) {
 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();
+function resolveRiddleApiKeyWithSource(config = {}) {
+  if (config.apiKey?.trim()) return { apiKey: config.apiKey.trim(), source: "option" };
+  if (process.env.RIDDLE_API_KEY?.trim()) return { apiKey: process.env.RIDDLE_API_KEY.trim(), source: "env" };
   const keyFile = config.apiKeyFile || process.env.RIDDLE_API_KEY_FILE || DEFAULT_RIDDLE_API_KEY_FILE;
   if (existsSync(keyFile)) {
     const key = readFileSync(keyFile, "utf8").trim();
-    if (key) return key;
+    if (key) return { apiKey: key, source: "file", file: keyFile };
   }
   throw new Error(`Riddle API key missing. Set RIDDLE_API_KEY or write ${DEFAULT_RIDDLE_API_KEY_FILE}.`);
 }
+function resolveRiddleApiKeySource(config = {}) {
+  const { apiKey: _apiKey, ...source } = resolveRiddleApiKeyWithSource(config);
+  return source;
+}
+function resolveRiddleApiKey(config = {}) {
+  return resolveRiddleApiKeyWithSource(config).apiKey;
+}
 async function riddleRequestJson(config, pathname, init = {}) {
   const response = await fetchFor(config)(`${normalizeBaseUrl(config.apiBaseUrl)}${pathname}`, {
     ...init,
@@ -51,6 +58,9 @@ async function riddleRequestJson(config, pathname, init = {}) {
   if (!response.ok) throw new RiddleApiError(pathname, response.status, text);
   return json ?? text;
 }
+async function getRiddleBalance(config = {}) {
+  return riddleRequestJson(config, "/v1/balance", { method: "GET" });
+}
 function previewDeployResultFromRecord(input) {
   const { record, id, label, framework, expiresAt, publishRecovered, publishError } = input;
   return {
@@ -385,7 +395,9 @@ async function pollRiddleJob(config, jobId, options = {}) {
 }
 function createRiddleApiClient(config = {}) {
   return {
+    apiKeySource: () => resolveRiddleApiKeySource(config),
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
+    getBalance: () => getRiddleBalance(config),
     deployPreview: (directory, label, framework = "static") => deployRiddlePreview(config, directory, label, framework),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
@@ -398,8 +410,10 @@ export {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
   RiddleApiError,
+  resolveRiddleApiKeySource,
   resolveRiddleApiKey,
   riddleRequestJson,
+  getRiddleBalance,
   deployRiddlePreview,
   deployRiddleStaticPreview,
   parseRiddleViewport,

package/dist/{chunk-VCTXNE67.js → chunk-3RTVXIFZ.js}

@@ -3561,7 +3561,7 @@ function createRiddleProofProfileConfigurationError(name, error, runner = "riddl
 }
 function createRiddleProofProfileEnvironmentBlockedResult(input) {
   const message = input.error instanceof Error ? input.error.message : input.error ? String(input.error) : "Riddle runner did not complete successfully.";
-  const environmentBlocker = extractRiddleRunnerBlocker(message);
+  const environmentBlocker = input.environmentBlocker || extractRiddleRunnerBlocker(message);
   const warnings = collectRiddleProofProfileEnvironmentBlockedWarnings(input.profile, environmentBlocker);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,

package/dist/cli.cjs

@@ -6584,16 +6584,23 @@ function normalizeBaseUrl(value) {
 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();
+function resolveRiddleApiKeyWithSource(config = {}) {
+  if (config.apiKey?.trim()) return { apiKey: config.apiKey.trim(), source: "option" };
+  if (process.env.RIDDLE_API_KEY?.trim()) return { apiKey: process.env.RIDDLE_API_KEY.trim(), source: "env" };
   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;
+    if (key) return { apiKey: key, source: "file", file: keyFile };
   }
   throw new Error(`Riddle API key missing. Set RIDDLE_API_KEY or write ${DEFAULT_RIDDLE_API_KEY_FILE}.`);
 }
+function resolveRiddleApiKeySource(config = {}) {
+  const { apiKey: _apiKey, ...source } = resolveRiddleApiKeyWithSource(config);
+  return source;
+}
+function resolveRiddleApiKey(config = {}) {
+  return resolveRiddleApiKeyWithSource(config).apiKey;
+}
 async function riddleRequestJson(config, pathname, init = {}) {
   const response = await fetchFor(config)(`${normalizeBaseUrl(config.apiBaseUrl)}${pathname}`, {
     ...init,
@@ -6612,6 +6619,9 @@ async function riddleRequestJson(config, pathname, init = {}) {
   if (!response.ok) throw new RiddleApiError(pathname, response.status, text);
   return json ?? text;
 }
+async function getRiddleBalance(config = {}) {
+  return riddleRequestJson(config, "/v1/balance", { method: "GET" });
+}
 function previewDeployResultFromRecord(input) {
   const { record, id, label, framework, expiresAt, publishRecovered, publishError } = input;
   return {
@@ -6946,7 +6956,9 @@ async function pollRiddleJob(config, jobId, options = {}) {
 }
 function createRiddleApiClient(config = {}) {
   return {
+    apiKeySource: () => resolveRiddleApiKeySource(config),
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
+    getBalance: () => getRiddleBalance(config),
     deployPreview: (directory, label, framework = "static") => deployRiddlePreview(config, directory, label, framework),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
@@ -10502,7 +10514,7 @@ function profileStatusExitCode(profile, status) {
 }
 function createRiddleProofProfileEnvironmentBlockedResult(input) {
   const message = input.error instanceof Error ? input.error.message : input.error ? String(input.error) : "Riddle runner did not complete successfully.";
-  const environmentBlocker = extractRiddleRunnerBlocker(message);
+  const environmentBlocker = input.environmentBlocker || extractRiddleRunnerBlocker(message);
   const warnings = collectRiddleProofProfileEnvironmentBlockedWarnings(input.profile, environmentBlocker);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
@@ -16215,6 +16227,7 @@ function extractRiddleProofProfileResult(input) {
 }
 
 // src/cli.ts
+var RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB = 30;
 function usage() {
   return [
     "Usage:",
@@ -16223,7 +16236,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--balance-preflight true|false; default true] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
@@ -16282,6 +16295,9 @@ function optionBoolean(options, key) {
 function runProfileStrictOption(options) {
   return optionBoolean(options, "strict") ?? false;
 }
+function runProfileBalancePreflightOption(options) {
+  return optionBoolean(options, "balancePreflight") ?? true;
+}
 function runProfileSplitViewportsOption(options) {
   return optionBoolean(options, "splitViewports") ?? false;
 }
@@ -18204,15 +18220,25 @@ function profileEnvironmentBlockerMarkdown(result) {
   const availableSeconds = cliFiniteNumber(blocker.available_seconds);
   const deficitSeconds = cliFiniteNumber(blocker.deficit_seconds);
   const minimumPurchaseDollars = cliFiniteNumber(blocker.minimum_purchase_dollars);
+  const balancePreflight = blocker.balance_preflight === true;
+  const jobCount = cliFiniteNumber(blocker.job_count);
+  const secondsPerJob = cliFiniteNumber(blocker.seconds_per_job);
+  const apiKeySource = cliString(blocker.api_key_source);
+  const apiKeyFile = cliString(blocker.api_key_file);
   if (reason) lines.push(`- reason: ${reason}`);
   if (source || endpoint || httpStatus !== void 0) {
     lines.push(`- source: ${source || "runner"}${endpoint ? ` ${endpoint}` : ""}${httpStatus === void 0 ? "" : ` HTTP ${httpStatus}`}`);
   }
+  if (balancePreflight) lines.push("- preflight: balance");
   if (error) lines.push(`- error: ${error}`);
+  if (jobCount !== void 0 || secondsPerJob !== void 0) {
+    lines.push(`- job estimate: ${jobCount ?? "unknown"} job(s), ${secondsPerJob ?? "unknown"}s minimum per job`);
+  }
   if (requiredSeconds !== void 0 || availableSeconds !== void 0 || deficitSeconds !== void 0) {
     lines.push(`- seconds: required ${requiredSeconds ?? "unknown"}, available ${availableSeconds ?? "unknown"}, deficit ${deficitSeconds ?? "unknown"}`);
   }
   if (minimumPurchaseDollars !== void 0) lines.push(`- minimum purchase: $${minimumPurchaseDollars}`);
+  if (apiKeySource) lines.push(`- auth: ${apiKeySource}${apiKeyFile ? ` ${apiKeyFile}` : ""}`);
   return lines;
 }
 function profileCliDiagnosticLine(result) {
@@ -19349,6 +19375,100 @@ function withSplitViewportChildStatusCheck(profile, result, childRuns) {
   const summary = status === "product_regression" ? `${profile.name} failed ${failedChecks} product invariant(s) across ${viewportCount} viewport(s).` : `${profile.name} collected split viewport artifacts but needs human review.`;
   return { ...result, status, checks, summary };
 }
+function profileRiddleJobCountForCli(profile, options) {
+  return runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1 ? profile.target.viewports.length : 1;
+}
+function riddleBalanceAvailableSeconds(balance) {
+  const availableSeconds = cliFiniteNumber(balance.available_seconds);
+  if (availableSeconds !== void 0) return availableSeconds;
+  const totalSeconds = cliFiniteNumber(balance.total_seconds);
+  const reservedSeconds = cliFiniteNumber(balance.reserved_seconds) ?? 0;
+  return totalSeconds === void 0 ? void 0 : totalSeconds - reservedSeconds;
+}
+function riddleBalancePreflightMetadata(profile, options) {
+  const split = runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1;
+  if (!split) return { status: "balance_preflight_blocked", terminal: false };
+  return {
+    mode: "split-viewports",
+    job_count: profile.target.viewports.length,
+    status: "balance_preflight_blocked",
+    terminal: false,
+    split_jobs: profile.target.viewports.map((viewport) => ({ viewport: viewport.name }))
+  };
+}
+function apiKeySourceBlockerMetadata(client) {
+  try {
+    const source = client.apiKeySource();
+    return {
+      api_key_source: source.source,
+      ...source.file ? { api_key_file: source.file } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function riddleApiErrorBlockerMetadata(error) {
+  const record = error && typeof error === "object" ? error : void 0;
+  const status = cliFiniteNumber(record?.status);
+  const pathValue = cliString(record?.path);
+  const body = cliString(record?.body);
+  return {
+    ...pathValue ? { endpoint: pathValue } : {},
+    ...status === void 0 ? {} : { http_status: status },
+    ...body ? { error: body } : {}
+  };
+}
+async function preflightRiddleProfileBalanceForCli(profile, options, input) {
+  if (!runProfileBalancePreflightOption(options)) return void 0;
+  let balance;
+  try {
+    balance = await input.client.getBalance();
+  } catch (error) {
+    return createRiddleProofProfileEnvironmentBlockedResult({
+      profile,
+      runner: input.runner,
+      error,
+      environmentBlocker: {
+        source: "riddle_api",
+        endpoint: "/v1/balance",
+        reason: "balance_preflight_failed",
+        balance_preflight: true,
+        ...riddleApiErrorBlockerMetadata(error),
+        ...apiKeySourceBlockerMetadata(input.client)
+      },
+      riddle: riddleBalancePreflightMetadata(profile, options)
+    });
+  }
+  const jobCount = profileRiddleJobCountForCli(profile, options);
+  const requiredSeconds = jobCount * RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB;
+  const availableSeconds = riddleBalanceAvailableSeconds(balance);
+  if (availableSeconds === void 0 || availableSeconds >= requiredSeconds) return void 0;
+  const reservedSeconds = cliFiniteNumber(balance.reserved_seconds);
+  const totalSeconds = cliFiniteNumber(balance.total_seconds);
+  const holdsCount = cliFiniteNumber(balance.holds_count);
+  return createRiddleProofProfileEnvironmentBlockedResult({
+    profile,
+    runner: input.runner,
+    error: `Riddle balance preflight failed: ${availableSeconds}s available for ${jobCount} intended hosted job(s), minimum ${requiredSeconds}s required.`,
+    environmentBlocker: {
+      source: "riddle_api",
+      endpoint: "/v1/balance",
+      reason: "insufficient_balance",
+      error: "Insufficient available balance",
+      balance_preflight: true,
+      job_count: jobCount,
+      seconds_per_job: RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB,
+      required_seconds: requiredSeconds,
+      available_seconds: availableSeconds,
+      deficit_seconds: requiredSeconds - availableSeconds,
+      ...reservedSeconds === void 0 ? {} : { reserved_seconds: reservedSeconds },
+      ...totalSeconds === void 0 ? {} : { total_seconds: totalSeconds },
+      ...holdsCount === void 0 ? {} : { holds_count: holdsCount },
+      ...apiKeySourceBlockerMetadata(input.client)
+    },
+    riddle: riddleBalancePreflightMetadata(profile, options)
+  });
+}
 async function runSingleRiddleProfileForCli(profile, options, input) {
   const { client, runner } = input;
   const targetUrl = resolveRiddleProofProfileTargetUrl(profile);
@@ -19571,6 +19691,8 @@ async function runProfileForCli(profile, options) {
     throw new Error(`Unsupported --runner ${runner}. The current CLI supports --runner riddle.`);
   }
   const client = createRiddleApiClient(riddleClientConfig(options));
+  const balanceBlocked = await preflightRiddleProfileBalanceForCli(profile, options, { client, runner });
+  if (balanceBlocked) return balanceBlocked;
   if (runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1) {
     return runSplitViewportProfileForCli(profile, options, { client, runner });
   }

package/dist/cli.js

@@ -13,12 +13,12 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-VCTXNE67.js";
+} from "./chunk-3RTVXIFZ.js";
 import {
   createRiddleApiClient,
   isTerminalRiddleJobStatus,
   parseRiddleViewport
-} from "./chunk-PPZ5A5MC.js";
+} from "./chunk-33XO7WFI.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
@@ -40,6 +40,7 @@ import "./chunk-VY4Y5U57.js";
 // src/cli.ts
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
 import path from "path";
+var RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB = 30;
 function usage() {
   return [
     "Usage:",
@@ -48,7 +49,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--balance-preflight true|false; default true] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
@@ -107,6 +108,9 @@ function optionBoolean(options, key) {
 function runProfileStrictOption(options) {
   return optionBoolean(options, "strict") ?? false;
 }
+function runProfileBalancePreflightOption(options) {
+  return optionBoolean(options, "balancePreflight") ?? true;
+}
 function runProfileSplitViewportsOption(options) {
   return optionBoolean(options, "splitViewports") ?? false;
 }
@@ -2029,15 +2033,25 @@ function profileEnvironmentBlockerMarkdown(result) {
   const availableSeconds = cliFiniteNumber(blocker.available_seconds);
   const deficitSeconds = cliFiniteNumber(blocker.deficit_seconds);
   const minimumPurchaseDollars = cliFiniteNumber(blocker.minimum_purchase_dollars);
+  const balancePreflight = blocker.balance_preflight === true;
+  const jobCount = cliFiniteNumber(blocker.job_count);
+  const secondsPerJob = cliFiniteNumber(blocker.seconds_per_job);
+  const apiKeySource = cliString(blocker.api_key_source);
+  const apiKeyFile = cliString(blocker.api_key_file);
   if (reason) lines.push(`- reason: ${reason}`);
   if (source || endpoint || httpStatus !== void 0) {
     lines.push(`- source: ${source || "runner"}${endpoint ? ` ${endpoint}` : ""}${httpStatus === void 0 ? "" : ` HTTP ${httpStatus}`}`);
   }
+  if (balancePreflight) lines.push("- preflight: balance");
   if (error) lines.push(`- error: ${error}`);
+  if (jobCount !== void 0 || secondsPerJob !== void 0) {
+    lines.push(`- job estimate: ${jobCount ?? "unknown"} job(s), ${secondsPerJob ?? "unknown"}s minimum per job`);
+  }
   if (requiredSeconds !== void 0 || availableSeconds !== void 0 || deficitSeconds !== void 0) {
     lines.push(`- seconds: required ${requiredSeconds ?? "unknown"}, available ${availableSeconds ?? "unknown"}, deficit ${deficitSeconds ?? "unknown"}`);
   }
   if (minimumPurchaseDollars !== void 0) lines.push(`- minimum purchase: $${minimumPurchaseDollars}`);
+  if (apiKeySource) lines.push(`- auth: ${apiKeySource}${apiKeyFile ? ` ${apiKeyFile}` : ""}`);
   return lines;
 }
 function profileCliDiagnosticLine(result) {
@@ -3174,6 +3188,100 @@ function withSplitViewportChildStatusCheck(profile, result, childRuns) {
   const summary = status === "product_regression" ? `${profile.name} failed ${failedChecks} product invariant(s) across ${viewportCount} viewport(s).` : `${profile.name} collected split viewport artifacts but needs human review.`;
   return { ...result, status, checks, summary };
 }
+function profileRiddleJobCountForCli(profile, options) {
+  return runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1 ? profile.target.viewports.length : 1;
+}
+function riddleBalanceAvailableSeconds(balance) {
+  const availableSeconds = cliFiniteNumber(balance.available_seconds);
+  if (availableSeconds !== void 0) return availableSeconds;
+  const totalSeconds = cliFiniteNumber(balance.total_seconds);
+  const reservedSeconds = cliFiniteNumber(balance.reserved_seconds) ?? 0;
+  return totalSeconds === void 0 ? void 0 : totalSeconds - reservedSeconds;
+}
+function riddleBalancePreflightMetadata(profile, options) {
+  const split = runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1;
+  if (!split) return { status: "balance_preflight_blocked", terminal: false };
+  return {
+    mode: "split-viewports",
+    job_count: profile.target.viewports.length,
+    status: "balance_preflight_blocked",
+    terminal: false,
+    split_jobs: profile.target.viewports.map((viewport) => ({ viewport: viewport.name }))
+  };
+}
+function apiKeySourceBlockerMetadata(client) {
+  try {
+    const source = client.apiKeySource();
+    return {
+      api_key_source: source.source,
+      ...source.file ? { api_key_file: source.file } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function riddleApiErrorBlockerMetadata(error) {
+  const record = error && typeof error === "object" ? error : void 0;
+  const status = cliFiniteNumber(record?.status);
+  const pathValue = cliString(record?.path);
+  const body = cliString(record?.body);
+  return {
+    ...pathValue ? { endpoint: pathValue } : {},
+    ...status === void 0 ? {} : { http_status: status },
+    ...body ? { error: body } : {}
+  };
+}
+async function preflightRiddleProfileBalanceForCli(profile, options, input) {
+  if (!runProfileBalancePreflightOption(options)) return void 0;
+  let balance;
+  try {
+    balance = await input.client.getBalance();
+  } catch (error) {
+    return createRiddleProofProfileEnvironmentBlockedResult({
+      profile,
+      runner: input.runner,
+      error,
+      environmentBlocker: {
+        source: "riddle_api",
+        endpoint: "/v1/balance",
+        reason: "balance_preflight_failed",
+        balance_preflight: true,
+        ...riddleApiErrorBlockerMetadata(error),
+        ...apiKeySourceBlockerMetadata(input.client)
+      },
+      riddle: riddleBalancePreflightMetadata(profile, options)
+    });
+  }
+  const jobCount = profileRiddleJobCountForCli(profile, options);
+  const requiredSeconds = jobCount * RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB;
+  const availableSeconds = riddleBalanceAvailableSeconds(balance);
+  if (availableSeconds === void 0 || availableSeconds >= requiredSeconds) return void 0;
+  const reservedSeconds = cliFiniteNumber(balance.reserved_seconds);
+  const totalSeconds = cliFiniteNumber(balance.total_seconds);
+  const holdsCount = cliFiniteNumber(balance.holds_count);
+  return createRiddleProofProfileEnvironmentBlockedResult({
+    profile,
+    runner: input.runner,
+    error: `Riddle balance preflight failed: ${availableSeconds}s available for ${jobCount} intended hosted job(s), minimum ${requiredSeconds}s required.`,
+    environmentBlocker: {
+      source: "riddle_api",
+      endpoint: "/v1/balance",
+      reason: "insufficient_balance",
+      error: "Insufficient available balance",
+      balance_preflight: true,
+      job_count: jobCount,
+      seconds_per_job: RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB,
+      required_seconds: requiredSeconds,
+      available_seconds: availableSeconds,
+      deficit_seconds: requiredSeconds - availableSeconds,
+      ...reservedSeconds === void 0 ? {} : { reserved_seconds: reservedSeconds },
+      ...totalSeconds === void 0 ? {} : { total_seconds: totalSeconds },
+      ...holdsCount === void 0 ? {} : { holds_count: holdsCount },
+      ...apiKeySourceBlockerMetadata(input.client)
+    },
+    riddle: riddleBalancePreflightMetadata(profile, options)
+  });
+}
 async function runSingleRiddleProfileForCli(profile, options, input) {
   const { client, runner } = input;
   const targetUrl = resolveRiddleProofProfileTargetUrl(profile);
@@ -3396,6 +3504,8 @@ async function runProfileForCli(profile, options) {
     throw new Error(`Unsupported --runner ${runner}. The current CLI supports --runner riddle.`);
   }
   const client = createRiddleApiClient(riddleClientConfig(options));
+  const balanceBlocked = await preflightRiddleProfileBalanceForCli(profile, options, { client, runner });
+  if (balanceBlocked) return balanceBlocked;
   if (runProfileSplitViewportsOption(options) && profile.target.viewports.length > 1) {
     return runSplitViewportProfileForCli(profile, options, { client, runner });
   }

package/dist/index.cjs

@@ -2976,6 +2976,7 @@ __export(index_exports, {
   extractBasicGameplayEvidence: () => extractBasicGameplayEvidence,
   extractPlayabilityEvidence: () => extractPlayabilityEvidence,
   extractRiddleProofProfileResult: () => extractRiddleProofProfileResult,
+  getRiddleBalance: () => getRiddleBalance,
   isDuplicateCheckpointResponse: () => isDuplicateCheckpointResponse,
   isRiddleProofPlayabilityMode: () => isRiddleProofPlayabilityMode,
   isSuccessfulStatus: () => isSuccessfulStatus,
@@ -2999,6 +3000,7 @@ __export(index_exports, {
   redactForProofDiagnostics: () => redactForProofDiagnostics,
   resolveBasicGameplayProgressionCheckWithArtifactScreenshots: () => resolveBasicGameplayProgressionCheckWithArtifactScreenshots,
   resolveRiddleApiKey: () => resolveRiddleApiKey,
+  resolveRiddleApiKeySource: () => resolveRiddleApiKeySource,
   resolveRiddleProofProfileRouteUrl: () => resolveRiddleProofProfileRouteUrl,
   resolveRiddleProofProfileTargetUrl: () => resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec: () => resolveRiddleProofProfileTimeoutSec,
@@ -12294,7 +12296,7 @@ function createRiddleProofProfileConfigurationError(name, error, runner = "riddl
 }
 function createRiddleProofProfileEnvironmentBlockedResult(input) {
   const message = input.error instanceof Error ? input.error.message : input.error ? String(input.error) : "Riddle runner did not complete successfully.";
-  const environmentBlocker = extractRiddleRunnerBlocker(message);
+  const environmentBlocker = input.environmentBlocker || extractRiddleRunnerBlocker(message);
   const warnings = collectRiddleProofProfileEnvironmentBlockedWarnings(input.profile, environmentBlocker);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
@@ -18031,16 +18033,23 @@ function normalizeBaseUrl(value) {
 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();
+function resolveRiddleApiKeyWithSource(config = {}) {
+  if (config.apiKey?.trim()) return { apiKey: config.apiKey.trim(), source: "option" };
+  if (process.env.RIDDLE_API_KEY?.trim()) return { apiKey: process.env.RIDDLE_API_KEY.trim(), source: "env" };
   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;
+    if (key) return { apiKey: key, source: "file", file: keyFile };
   }
   throw new Error(`Riddle API key missing. Set RIDDLE_API_KEY or write ${DEFAULT_RIDDLE_API_KEY_FILE}.`);
 }
+function resolveRiddleApiKeySource(config = {}) {
+  const { apiKey: _apiKey, ...source } = resolveRiddleApiKeyWithSource(config);
+  return source;
+}
+function resolveRiddleApiKey(config = {}) {
+  return resolveRiddleApiKeyWithSource(config).apiKey;
+}
 async function riddleRequestJson(config, pathname, init = {}) {
   const response = await fetchFor(config)(`${normalizeBaseUrl(config.apiBaseUrl)}${pathname}`, {
     ...init,
@@ -18059,6 +18068,9 @@ async function riddleRequestJson(config, pathname, init = {}) {
   if (!response.ok) throw new RiddleApiError(pathname, response.status, text);
   return json ?? text;
 }
+async function getRiddleBalance(config = {}) {
+  return riddleRequestJson(config, "/v1/balance", { method: "GET" });
+}
 function previewDeployResultFromRecord(input) {
   const { record, id, label, framework, expiresAt, publishRecovered, publishError } = input;
   return {
@@ -18393,7 +18405,9 @@ async function pollRiddleJob(config, jobId, options = {}) {
 }
 function createRiddleApiClient(config = {}) {
   return {
+    apiKeySource: () => resolveRiddleApiKeySource(config),
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
+    getBalance: () => getRiddleBalance(config),
     deployPreview: (directory, label, framework = "static") => deployRiddlePreview(config, directory, label, framework),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
@@ -18480,6 +18494,7 @@ function createRiddleApiClient(config = {}) {
   extractBasicGameplayEvidence,
   extractPlayabilityEvidence,
   extractRiddleProofProfileResult,
+  getRiddleBalance,
   isDuplicateCheckpointResponse,
   isRiddleProofPlayabilityMode,
   isSuccessfulStatus,
@@ -18503,6 +18518,7 @@ function createRiddleApiClient(config = {}) {
   redactForProofDiagnostics,
   resolveBasicGameplayProgressionCheckWithArtifactScreenshots,
   resolveRiddleApiKey,
+  resolveRiddleApiKeySource,
   resolveRiddleProofProfileRouteUrl,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec,

package/dist/index.d.cts

@@ -11,4 +11,4 @@ export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_V
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.cjs';
 export { AssessBasicGameplayOptions, AttachBasicGameplayArtifactOptions, BASIC_GAMEPLAY_ACTION_TYPES, BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES, BasicGameplayActionResult, BasicGameplayActionType, BasicGameplayArtifactResolution, BasicGameplayAssessmentSummary, BasicGameplayBoundsOffender, BasicGameplayCanvasState, BasicGameplayCatchRecord, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMetric, BasicGameplayMobileEvidence, BasicGameplayProgressCheckType, BasicGameplayProgressionCheck, BasicGameplayProofArtifact, BasicGameplayResponsiveViewportEvidence, BasicGameplayRouteReference, BasicGameplaySnapshot, BasicGameplaySuiteFailure, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayProgressionCheck, assessBasicGameplayProgressionChecks, assessBasicGameplayRoute, attachBasicGameplayArtifactScreenshotHashes, augmentBasicGameplayAssessmentWithProgressionChecks, compactBasicGameplayText, createBasicGameplayCatchRecords, createBasicGameplayCatchSummary, extractBasicGameplayEvidence, resolveBasicGameplayProgressionCheckWithArtifactScreenshots, sanitizeBasicGameplayJsonString } from './basic-gameplay.cjs';
 export { NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_NETWORK_ABORT_ERROR_CODES, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, RiddleProofArtifactBodyAssertionInput, RiddleProofArtifactBodyAssertionResult, RiddleProofProfile, RiddleProofProfileArtifactRef, RiddleProofProfileBaselinePolicy, RiddleProofProfileBoundsOffender, RiddleProofProfileCheck, RiddleProofProfileCheckResult, RiddleProofProfileCheckType, RiddleProofProfileEvidence, RiddleProofProfileFailureAction, RiddleProofProfileHttpStatusBodyJsonAssertion, RiddleProofProfileHttpStatusBodyJsonAssertionResult, RiddleProofProfileHttpStatusPreflightCheckResult, RiddleProofProfileHttpStatusPreflightFetch, RiddleProofProfileHttpStatusPreflightFetchResponse, RiddleProofProfileHttpStatusPreflightOptions, RiddleProofProfileHttpStatusPreflightResult, RiddleProofProfileJsonValueType, RiddleProofProfileNetworkAbortErrorCode, RiddleProofProfileNetworkMock, RiddleProofProfileNetworkMockResponse, RiddleProofProfileResult, RiddleProofProfileReturnSummaryField, RiddleProofProfileRouteEvidence, RiddleProofProfileRouteInventoryRoute, RiddleProofProfileRunner, RiddleProofProfileSetupAction, RiddleProofProfileSetupActionType, RiddleProofProfileStatus, RiddleProofProfileTarget, RiddleProofProfileViewport, RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, collectRiddleProofProfileWarnings, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, deriveRiddleProofArtifactBodyAssertions, extractRiddleProofProfileResult, normalizeRiddleProofProfile, preflightRiddleProofProfileHttpStatusChecks, profileStatusExitCode, resolveRiddleProofProfileRouteUrl, resolveRiddleProofProfileTargetUrl, resolveRiddleProofProfileTimeoutSec, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult } from './profile.cjs';
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.cjs';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.cjs';

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_V
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.js';
 export { AssessBasicGameplayOptions, AttachBasicGameplayArtifactOptions, BASIC_GAMEPLAY_ACTION_TYPES, BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES, BasicGameplayActionResult, BasicGameplayActionType, BasicGameplayArtifactResolution, BasicGameplayAssessmentSummary, BasicGameplayBoundsOffender, BasicGameplayCanvasState, BasicGameplayCatchRecord, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMetric, BasicGameplayMobileEvidence, BasicGameplayProgressCheckType, BasicGameplayProgressionCheck, BasicGameplayProofArtifact, BasicGameplayResponsiveViewportEvidence, BasicGameplayRouteReference, BasicGameplaySnapshot, BasicGameplaySuiteFailure, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayProgressionCheck, assessBasicGameplayProgressionChecks, assessBasicGameplayRoute, attachBasicGameplayArtifactScreenshotHashes, augmentBasicGameplayAssessmentWithProgressionChecks, compactBasicGameplayText, createBasicGameplayCatchRecords, createBasicGameplayCatchSummary, extractBasicGameplayEvidence, resolveBasicGameplayProgressionCheckWithArtifactScreenshots, sanitizeBasicGameplayJsonString } from './basic-gameplay.js';
 export { NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_NETWORK_ABORT_ERROR_CODES, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, RiddleProofArtifactBodyAssertionInput, RiddleProofArtifactBodyAssertionResult, RiddleProofProfile, RiddleProofProfileArtifactRef, RiddleProofProfileBaselinePolicy, RiddleProofProfileBoundsOffender, RiddleProofProfileCheck, RiddleProofProfileCheckResult, RiddleProofProfileCheckType, RiddleProofProfileEvidence, RiddleProofProfileFailureAction, RiddleProofProfileHttpStatusBodyJsonAssertion, RiddleProofProfileHttpStatusBodyJsonAssertionResult, RiddleProofProfileHttpStatusPreflightCheckResult, RiddleProofProfileHttpStatusPreflightFetch, RiddleProofProfileHttpStatusPreflightFetchResponse, RiddleProofProfileHttpStatusPreflightOptions, RiddleProofProfileHttpStatusPreflightResult, RiddleProofProfileJsonValueType, RiddleProofProfileNetworkAbortErrorCode, RiddleProofProfileNetworkMock, RiddleProofProfileNetworkMockResponse, RiddleProofProfileResult, RiddleProofProfileReturnSummaryField, RiddleProofProfileRouteEvidence, RiddleProofProfileRouteInventoryRoute, RiddleProofProfileRunner, RiddleProofProfileSetupAction, RiddleProofProfileSetupActionType, RiddleProofProfileStatus, RiddleProofProfileTarget, RiddleProofProfileViewport, RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, collectRiddleProofProfileWarnings, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, deriveRiddleProofArtifactBodyAssertions, extractRiddleProofProfileResult, normalizeRiddleProofProfile, preflightRiddleProofProfileHttpStatusChecks, profileStatusExitCode, resolveRiddleProofProfileRouteUrl, resolveRiddleProofProfileTargetUrl, resolveRiddleProofProfileTimeoutSec, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult } from './profile.js';
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.js';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.js';

package/dist/index.js

@@ -62,7 +62,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-VCTXNE67.js";
+} from "./chunk-3RTVXIFZ.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
@@ -70,14 +70,16 @@ import {
   createRiddleApiClient,
   deployRiddlePreview,
   deployRiddleStaticPreview,
+  getRiddleBalance,
   isTerminalRiddleJobStatus,
   parseRiddleViewport,
   pollRiddleJob,
   resolveRiddleApiKey,
+  resolveRiddleApiKeySource,
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview
-} from "./chunk-PPZ5A5MC.js";
+} from "./chunk-33XO7WFI.js";
 import {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,
@@ -220,6 +222,7 @@ export {
   extractBasicGameplayEvidence,
   extractPlayabilityEvidence,
   extractRiddleProofProfileResult,
+  getRiddleBalance,
   isDuplicateCheckpointResponse,
   isRiddleProofPlayabilityMode,
   isSuccessfulStatus,
@@ -243,6 +246,7 @@ export {
   redactForProofDiagnostics,
   resolveBasicGameplayProgressionCheckWithArtifactScreenshots,
   resolveRiddleApiKey,
+  resolveRiddleApiKeySource,
   resolveRiddleProofProfileRouteUrl,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec,

package/dist/profile.cjs

@@ -3608,7 +3608,7 @@ function createRiddleProofProfileConfigurationError(name, error, runner = "riddl
 }
 function createRiddleProofProfileEnvironmentBlockedResult(input) {
   const message = input.error instanceof Error ? input.error.message : input.error ? String(input.error) : "Riddle runner did not complete successfully.";
-  const environmentBlocker = extractRiddleRunnerBlocker(message);
+  const environmentBlocker = input.environmentBlocker || extractRiddleRunnerBlocker(message);
   const warnings = collectRiddleProofProfileEnvironmentBlockedWarnings(input.profile, environmentBlocker);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,

package/dist/profile.d.cts

@@ -467,6 +467,7 @@ declare function createRiddleProofProfileEnvironmentBlockedResult(input: {
     profile: RiddleProofProfile;
     runner?: RiddleProofProfileRunner;
     error?: unknown;
+    environmentBlocker?: Record<string, JsonValue>;
     riddle?: RiddleProofProfileResult["riddle"];
     artifacts?: RiddleProofProfileArtifactRef[];
 }): RiddleProofProfileResult;

package/dist/profile.d.ts

@@ -467,6 +467,7 @@ declare function createRiddleProofProfileEnvironmentBlockedResult(input: {
     profile: RiddleProofProfile;
     runner?: RiddleProofProfileRunner;
     error?: unknown;
+    environmentBlocker?: Record<string, JsonValue>;
     riddle?: RiddleProofProfileResult["riddle"];
     artifacts?: RiddleProofProfileArtifactRef[];
 }): RiddleProofProfileResult;

package/dist/profile.js

@@ -23,7 +23,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-VCTXNE67.js";
+} from "./chunk-3RTVXIFZ.js";
 export {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,

package/dist/riddle-client.cjs

@@ -36,10 +36,12 @@ __export(riddle_client_exports, {
   createRiddleApiClient: () => createRiddleApiClient,
   deployRiddlePreview: () => deployRiddlePreview,
   deployRiddleStaticPreview: () => deployRiddleStaticPreview,
+  getRiddleBalance: () => getRiddleBalance,
   isTerminalRiddleJobStatus: () => isTerminalRiddleJobStatus,
   parseRiddleViewport: () => parseRiddleViewport,
   pollRiddleJob: () => pollRiddleJob,
   resolveRiddleApiKey: () => resolveRiddleApiKey,
+  resolveRiddleApiKeySource: () => resolveRiddleApiKeySource,
   riddleRequestJson: () => riddleRequestJson,
   runRiddleScript: () => runRiddleScript,
   runRiddleServerPreview: () => runRiddleServerPreview
@@ -69,16 +71,23 @@ function normalizeBaseUrl(value) {
 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();
+function resolveRiddleApiKeyWithSource(config = {}) {
+  if (config.apiKey?.trim()) return { apiKey: config.apiKey.trim(), source: "option" };
+  if (process.env.RIDDLE_API_KEY?.trim()) return { apiKey: process.env.RIDDLE_API_KEY.trim(), source: "env" };
   const keyFile = config.apiKeyFile || process.env.RIDDLE_API_KEY_FILE || DEFAULT_RIDDLE_API_KEY_FILE;
   if ((0, import_node_fs.existsSync)(keyFile)) {
     const key = (0, import_node_fs.readFileSync)(keyFile, "utf8").trim();
-    if (key) return key;
+    if (key) return { apiKey: key, source: "file", file: keyFile };
   }
   throw new Error(`Riddle API key missing. Set RIDDLE_API_KEY or write ${DEFAULT_RIDDLE_API_KEY_FILE}.`);
 }
+function resolveRiddleApiKeySource(config = {}) {
+  const { apiKey: _apiKey, ...source } = resolveRiddleApiKeyWithSource(config);
+  return source;
+}
+function resolveRiddleApiKey(config = {}) {
+  return resolveRiddleApiKeyWithSource(config).apiKey;
+}
 async function riddleRequestJson(config, pathname, init = {}) {
   const response = await fetchFor(config)(`${normalizeBaseUrl(config.apiBaseUrl)}${pathname}`, {
     ...init,
@@ -97,6 +106,9 @@ async function riddleRequestJson(config, pathname, init = {}) {
   if (!response.ok) throw new RiddleApiError(pathname, response.status, text);
   return json ?? text;
 }
+async function getRiddleBalance(config = {}) {
+  return riddleRequestJson(config, "/v1/balance", { method: "GET" });
+}
 function previewDeployResultFromRecord(input) {
   const { record, id, label, framework, expiresAt, publishRecovered, publishError } = input;
   return {
@@ -431,7 +443,9 @@ async function pollRiddleJob(config, jobId, options = {}) {
 }
 function createRiddleApiClient(config = {}) {
   return {
+    apiKeySource: () => resolveRiddleApiKeySource(config),
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
+    getBalance: () => getRiddleBalance(config),
     deployPreview: (directory, label, framework = "static") => deployRiddlePreview(config, directory, label, framework),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
@@ -447,10 +461,12 @@ function createRiddleApiClient(config = {}) {
   createRiddleApiClient,
   deployRiddlePreview,
   deployRiddleStaticPreview,
+  getRiddleBalance,
   isTerminalRiddleJobStatus,
   parseRiddleViewport,
   pollRiddleJob,
   resolveRiddleApiKey,
+  resolveRiddleApiKeySource,
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview

package/dist/riddle-client.d.cts

@@ -7,6 +7,23 @@ interface RiddleClientConfig {
     apiBaseUrl?: string;
     fetchImpl?: RiddleFetch;
 }
+interface RiddleApiKeySource {
+    source: "option" | "env" | "file";
+    file?: string;
+}
+interface RiddleBalanceResult {
+    available_seconds?: number;
+    reserved_seconds?: number;
+    total_seconds?: number;
+    available_time?: string;
+    total_time?: string;
+    available_dollars?: number;
+    reserved_dollars?: number;
+    total_dollars?: number;
+    currency?: string;
+    holds_count?: number;
+    rate?: Record<string, unknown>;
+}
 interface RiddlePollProgressSnapshot {
     job_id: string;
     status: string | null;
@@ -107,8 +124,10 @@ declare class RiddleApiError extends Error {
     readonly path: string;
     constructor(pathname: string, status: number, body: string);
 }
+declare function resolveRiddleApiKeySource(config?: RiddleClientConfig): RiddleApiKeySource;
 declare function resolveRiddleApiKey(config?: RiddleClientConfig): string;
 declare function riddleRequestJson<T = unknown>(config: RiddleClientConfig, pathname: string, init?: RequestInit): Promise<T>;
+declare function getRiddleBalance(config?: RiddleClientConfig): Promise<RiddleBalanceResult>;
 declare function deployRiddlePreview(config: RiddleClientConfig, directory: string, label: string, framework?: RiddlePreviewFramework): Promise<RiddlePreviewDeployResult>;
 declare function deployRiddleStaticPreview(config: RiddleClientConfig, directory: string, label: string): Promise<RiddlePreviewDeployResult>;
 declare function parseRiddleViewport(value?: string): {
@@ -120,7 +139,9 @@ declare function runRiddleScript(config: RiddleClientConfig, input: RiddleRunScr
 declare function isTerminalRiddleJobStatus(status: unknown): boolean;
 declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: RiddlePollJobOptions): Promise<RiddlePollJobResult>;
 declare function createRiddleApiClient(config?: RiddleClientConfig): {
+    apiKeySource: () => RiddleApiKeySource;
     requestJson: <T = unknown>(pathname: string, init?: RequestInit) => Promise<T>;
+    getBalance: () => Promise<RiddleBalanceResult>;
     deployPreview: (directory: string, label: string, framework?: RiddlePreviewFramework) => Promise<RiddlePreviewDeployResult>;
     deployStaticPreview: (directory: string, label: string) => Promise<RiddlePreviewDeployResult>;
     runScript: (input: RiddleRunScriptInput) => Promise<Record<string, unknown>>;
@@ -128,4 +149,4 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     pollJob: (jobId: string, options?: RiddlePollJobOptions) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleApiKeySource, type RiddleBalanceResult, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.d.ts

@@ -7,6 +7,23 @@ interface RiddleClientConfig {
     apiBaseUrl?: string;
     fetchImpl?: RiddleFetch;
 }
+interface RiddleApiKeySource {
+    source: "option" | "env" | "file";
+    file?: string;
+}
+interface RiddleBalanceResult {
+    available_seconds?: number;
+    reserved_seconds?: number;
+    total_seconds?: number;
+    available_time?: string;
+    total_time?: string;
+    available_dollars?: number;
+    reserved_dollars?: number;
+    total_dollars?: number;
+    currency?: string;
+    holds_count?: number;
+    rate?: Record<string, unknown>;
+}
 interface RiddlePollProgressSnapshot {
     job_id: string;
     status: string | null;
@@ -107,8 +124,10 @@ declare class RiddleApiError extends Error {
     readonly path: string;
     constructor(pathname: string, status: number, body: string);
 }
+declare function resolveRiddleApiKeySource(config?: RiddleClientConfig): RiddleApiKeySource;
 declare function resolveRiddleApiKey(config?: RiddleClientConfig): string;
 declare function riddleRequestJson<T = unknown>(config: RiddleClientConfig, pathname: string, init?: RequestInit): Promise<T>;
+declare function getRiddleBalance(config?: RiddleClientConfig): Promise<RiddleBalanceResult>;
 declare function deployRiddlePreview(config: RiddleClientConfig, directory: string, label: string, framework?: RiddlePreviewFramework): Promise<RiddlePreviewDeployResult>;
 declare function deployRiddleStaticPreview(config: RiddleClientConfig, directory: string, label: string): Promise<RiddlePreviewDeployResult>;
 declare function parseRiddleViewport(value?: string): {
@@ -120,7 +139,9 @@ declare function runRiddleScript(config: RiddleClientConfig, input: RiddleRunScr
 declare function isTerminalRiddleJobStatus(status: unknown): boolean;
 declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: RiddlePollJobOptions): Promise<RiddlePollJobResult>;
 declare function createRiddleApiClient(config?: RiddleClientConfig): {
+    apiKeySource: () => RiddleApiKeySource;
     requestJson: <T = unknown>(pathname: string, init?: RequestInit) => Promise<T>;
+    getBalance: () => Promise<RiddleBalanceResult>;
     deployPreview: (directory: string, label: string, framework?: RiddlePreviewFramework) => Promise<RiddlePreviewDeployResult>;
     deployStaticPreview: (directory: string, label: string) => Promise<RiddlePreviewDeployResult>;
     runScript: (input: RiddleRunScriptInput) => Promise<Record<string, unknown>>;
@@ -128,4 +149,4 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     pollJob: (jobId: string, options?: RiddlePollJobOptions) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleApiKeySource, type RiddleBalanceResult, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.js

@@ -5,14 +5,16 @@ import {
   createRiddleApiClient,
   deployRiddlePreview,
   deployRiddleStaticPreview,
+  getRiddleBalance,
   isTerminalRiddleJobStatus,
   parseRiddleViewport,
   pollRiddleJob,
   resolveRiddleApiKey,
+  resolveRiddleApiKeySource,
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview
-} from "./chunk-PPZ5A5MC.js";
+} from "./chunk-33XO7WFI.js";
 export {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
@@ -20,10 +22,12 @@ export {
   createRiddleApiClient,
   deployRiddlePreview,
   deployRiddleStaticPreview,
+  getRiddleBalance,
   isTerminalRiddleJobStatus,
   parseRiddleViewport,
   pollRiddleJob,
   resolveRiddleApiKey,
+  resolveRiddleApiKeySource,
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.7.212",
+  "version": "0.7.213",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",