pixelkiln 0.13.0 → 0.14.0

package/dist/cli.js

@@ -2315,7 +2315,494 @@ function retroError(value) {
   return JSON.stringify(value);
 }
 
+// src/providers/scenario.ts
+var DEFAULT_BASE_URL3 = "https://api.cloud.scenario.com/v1";
+var SOURCE_PROTOCOL2 = "scenario:";
+var PROTECTED_PARAMETERS = /* @__PURE__ */ new Set([
+  "dryRun",
+  "height",
+  "maxComputeUnits",
+  "numOutputs",
+  "projectId",
+  "prompt",
+  "seed",
+  "width"
+]);
+var ScenarioClient = class {
+  constructor(apiKey, apiSecret, baseUrl = DEFAULT_BASE_URL3, request = fetch) {
+    this.apiKey = apiKey;
+    this.apiSecret = apiSecret;
+    this.baseUrl = baseUrl;
+    this.request = request;
+  }
+  apiKey;
+  apiSecret;
+  baseUrl;
+  request;
+  async quote(modelId, body, projectId) {
+    const response = await this.call(
+      `/generate/custom/${encodeURIComponent(modelId)}`,
+      { method: "POST", body: JSON.stringify(body) },
+      { dryRun: "true", projectId }
+    );
+    const creativeUnitsCost = finiteNonnegative(
+      response?.creativeUnitsCost,
+      "Scenario dry run returned an invalid creativeUnitsCost"
+    );
+    const costDetails = numericRecord(response?.costDetails);
+    const ipDetectionCost = optionalFiniteNonnegative(
+      response?.ipDetection?.creativeUnitsCharged,
+      "Scenario dry run returned an invalid IP-detection cost"
+    );
+    return {
+      total: creativeUnitsCost + ipDetectionCost,
+      creativeUnitsCost,
+      costDetails,
+      ipDetectionCost
+    };
+  }
+  async submit(modelId, body, projectId) {
+    const response = await this.call(
+      `/generate/custom/${encodeURIComponent(modelId)}`,
+      { method: "POST", body: JSON.stringify(body) },
+      { projectId }
+    );
+    const job = response?.job;
+    const jobId = readJobId(job);
+    if (!jobId) throw new Error("Scenario did not return an async job id");
+    return jobId;
+  }
+  async job(id, projectId) {
+    const response = await this.call(`/jobs/${encodeURIComponent(id)}`, {}, { projectId });
+    const raw = response?.job;
+    if (!raw || typeof raw !== "object") throw new Error("Scenario returned an invalid job");
+    const record = raw;
+    const jobId = readJobId(raw);
+    if (!jobId || typeof record.status !== "string") {
+      throw new Error("Scenario returned an invalid job");
+    }
+    return {
+      jobId,
+      status: record.status,
+      ...typeof record.progress === "number" ? { progress: record.progress } : {},
+      ...record.metadata && typeof record.metadata === "object" ? { metadata: record.metadata } : {},
+      ...record.billing && typeof record.billing === "object" ? { billing: record.billing } : {}
+    };
+  }
+  async asset(id, projectId) {
+    const response = await this.call(
+      `/assets/${encodeURIComponent(id)}`,
+      {},
+      { originalAssets: "true", projectId }
+    );
+    const raw = response?.asset;
+    if (!raw || typeof raw !== "object") throw new Error(`Scenario returned an invalid asset ${id}`);
+    const asset = raw;
+    const assetId = typeof asset.id === "string" && asset.id ? asset.id : id;
+    const url = typeof asset.url === "string" ? asset.url : "";
+    const originalFileUrl = typeof asset.originalFileUrl === "string" ? asset.originalFileUrl : void 0;
+    if (!originalFileUrl && !url) throw new Error(`Scenario asset ${assetId} has no download URL`);
+    const metadata = isRecord(asset.metadata) ? asset.metadata : {};
+    const rawOutputIndex = asset.outputIndex ?? metadata.outputIndex;
+    const outputIndex = Number.isInteger(rawOutputIndex) && Number(rawOutputIndex) >= 0 ? Number(rawOutputIndex) : Number.MAX_SAFE_INTEGER;
+    const originalMimeType = typeof asset.originalMimeType === "string" ? asset.originalMimeType : typeof asset.mimeType === "string" ? asset.mimeType : void 0;
+    return {
+      id: assetId,
+      url,
+      ...originalFileUrl ? { originalFileUrl } : {},
+      ...originalMimeType ? { originalMimeType } : {},
+      outputIndex
+    };
+  }
+  async download(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error("Scenario downloads must use HTTP or HTTPS");
+    }
+    const response = await this.request(parsed);
+    if (!response.ok) throw new Error(`Scenario download failed (${response.status})`);
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_DOWNLOAD_BYTES) {
+      throw new Error(`Scenario download exceeds the ${MAX_DOWNLOAD_BYTES}-byte safety limit`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > MAX_DOWNLOAD_BYTES) {
+      throw new Error(`Scenario download exceeds the ${MAX_DOWNLOAD_BYTES}-byte safety limit`);
+    }
+    return bytes;
+  }
+  async checkConnection() {
+    await this.call("/models", {}, { pageSize: "1" });
+  }
+  async call(pathname, init = {}, query = {}) {
+    if (!this.apiKey || !this.apiSecret) {
+      const missing = [
+        !this.apiKey ? "SCENARIO_SDK_API_KEY" : null,
+        !this.apiSecret ? "SCENARIO_SDK_API_SECRET" : null
+      ].filter(Boolean);
+      throw new Error(`${missing.join(" and ")} ${missing.length > 1 ? "are" : "is"} not set`);
+    }
+    const url = new URL(`${this.baseUrl.replace(/\/$/, "")}${pathname}`);
+    for (const [key, value2] of Object.entries(query)) {
+      if (value2 != null) url.searchParams.set(key, value2);
+    }
+    const auth = Buffer.from(`${this.apiKey}:${this.apiSecret}`).toString("base64");
+    const response = await this.request(url, {
+      ...init,
+      headers: {
+        Accept: "application/json",
+        Authorization: `Basic ${auth}`,
+        ...init.body ? { "Content-Type": "application/json" } : {},
+        ...init.headers
+      }
+    });
+    const text = await response.text();
+    let value = null;
+    try {
+      value = text ? JSON.parse(text) : null;
+    } catch {
+      value = text;
+    }
+    if (!response.ok) {
+      const retry = response.headers.get("retry-after");
+      const detail = redactScenarioError(value, [this.apiKey, this.apiSecret, auth]);
+      throw new Error(
+        `Scenario request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : "")
+      );
+    }
+    return value;
+  }
+};
+var ScenarioProvider = class _ScenarioProvider {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  id = "scenario";
+  static fromEnv() {
+    return new _ScenarioProvider(new ScenarioClient(
+      process.env.SCENARIO_SDK_API_KEY,
+      process.env.SCENARIO_SDK_API_SECRET,
+      scenarioBaseUrl(process.env.SCENARIO_API_BASE_URL ?? DEFAULT_BASE_URL3)
+    ));
+  }
+  static forOffline() {
+    return new _ScenarioProvider(new ScenarioClient(void 0, void 0));
+  }
+  static forDownloads() {
+    return _ScenarioProvider.fromEnv();
+  }
+  supports(generator) {
+    return generator === "map";
+  }
+  estimate(spec) {
+    const options = scenarioOptions(spec);
+    return {
+      unit: "compute-units",
+      amount: options.maxComputeUnits,
+      candidates: options.numOutputs ?? 1
+    };
+  }
+  validate(spec, styleImages) {
+    const options = scenarioOptions(spec);
+    if (typeof options.modelId !== "string" || !options.modelId.trim()) {
+      throw new Error("Scenario modelId is required");
+    }
+    if (!Number.isFinite(options.maxComputeUnits) || options.maxComputeUnits <= 0) {
+      throw new Error("Scenario maxComputeUnits must be a positive number");
+    }
+    const count = options.numOutputs ?? 1;
+    if (!Number.isInteger(count) || count < 1 || count > 4) {
+      throw new Error("Scenario numOutputs must be a whole number from 1 to 4");
+    }
+    if (spec.width < 128 || spec.width > 2048 || spec.width % 16 !== 0 || spec.height < 128 || spec.height > 2048 || spec.height % 16 !== 0) {
+      throw new Error("Scenario width and height must be multiples of 16 from 128 to 2048");
+    }
+    if (styleImages.length) {
+      throw new Error("Scenario styleImages are not supported yet; use a reusable Scenario model");
+    }
+    if (options.projectId != null && (typeof options.projectId !== "string" || !options.projectId.trim())) {
+      throw new Error("Scenario projectId must be a non-empty string");
+    }
+    validateParameters(options.parameters ?? {});
+  }
+  rateLimit() {
+    return { spacingMs: 1e3, maxInFlight: 4 };
+  }
+  async submit(spec, styleImages) {
+    this.validate(spec, styleImages);
+    const options = scenarioOptions(spec);
+    const body = requestBody(spec, options);
+    const quote = await this.client.quote(options.modelId, body, options.projectId);
+    if (quote.total > options.maxComputeUnits + Number.EPSILON) {
+      throw new Error(
+        `Scenario quoted ${quote.total} compute-units, above maxComputeUnits ${options.maxComputeUnits}; no paid request was sent`
+      );
+    }
+    const apiJobId = await this.client.submit(options.modelId, body, options.projectId);
+    return {
+      jobId: jobRef(apiJobId, options.projectId),
+      metadata: {
+        modelId: options.modelId,
+        projectId: options.projectId ?? null,
+        maxComputeUnits: options.maxComputeUnits,
+        quotedComputeUnits: quote.total,
+        creativeUnitsCost: quote.creativeUnitsCost,
+        costDetails: quote.costDetails,
+        ipDetectionCost: quote.ipDetectionCost
+      }
+    };
+  }
+  async poll(jobReference, _generator, context) {
+    const reference = parseJobRef(jobReference);
+    const job = await this.client.job(reference.jobId, reference.projectId);
+    const metadata = jobMetadata(job, context?.spec ? scenarioOptions(context.spec) : void 0);
+    if (["pending", "queued", "warming-up", "in-progress", "finalizing", "processing"].includes(job.status)) {
+      return {
+        status: "processing",
+        progressPercent: validProgress(job.progress)
+      };
+    }
+    if (["failure", "failed", "canceled"].includes(job.status)) {
+      return { status: "failed", error: scenarioJobError(job) };
+    }
+    if (job.status !== "success") {
+      return { status: "failed", error: `Scenario returned unknown job status "${job.status}"` };
+    }
+    const assetIds = scenarioAssetIds(job);
+    if (!assetIds.length) return { status: "failed", error: "Scenario job returned no asset IDs" };
+    const assets = await this.assets(assetIds, reference.projectId);
+    if (assets.length > 1) {
+      return {
+        status: "review",
+        candidateUrls: assets.map(assetDownloadUrl),
+        metadata: { ...metadata, assetIds: assets.map((asset2) => asset2.id) }
+      };
+    }
+    const asset = assets[0];
+    return {
+      status: "ready",
+      objectId: asset.id,
+      sourceUrl: assetRef(asset.id, reference.projectId),
+      sources: [{ url: assetRef(asset.id, reference.projectId), mediaType: MediaType.PNG }],
+      metadata: {
+        ...metadata,
+        assetId: asset.id,
+        outputIndex: asset.outputIndex === Number.MAX_SAFE_INTEGER ? null : asset.outputIndex
+      }
+    };
+  }
+  async selectCandidate(jobReference, index) {
+    const reference = parseJobRef(jobReference);
+    const job = await this.client.job(reference.jobId, reference.projectId);
+    if (job.status !== "success") throw new Error(`Scenario job ${reference.jobId} is not ready`);
+    const assets = await this.assets(scenarioAssetIds(job), reference.projectId);
+    const asset = assets[index];
+    if (!asset) throw new Error(`Scenario job ${reference.jobId} has no candidate at index ${index}`);
+    return {
+      objectId: asset.id,
+      sourceUrl: assetRef(asset.id, reference.projectId),
+      metadata: {
+        ...jobMetadata(job),
+        assetId: asset.id,
+        outputIndex: asset.outputIndex === Number.MAX_SAFE_INTEGER ? null : asset.outputIndex
+      }
+    };
+  }
+  async download(source) {
+    if (!source.startsWith(`${SOURCE_PROTOCOL2}//`)) return this.client.download(source);
+    const reference = parseAssetRef(source);
+    const asset = await this.client.asset(reference.assetId, reference.projectId);
+    assertPngAsset(asset);
+    return this.client.download(assetDownloadUrl(asset));
+  }
+  async checkConnection() {
+    await this.client.checkConnection();
+  }
+  async assets(ids, projectId) {
+    const assets = await Promise.all(ids.map((id) => this.client.asset(id, projectId)));
+    const jobOrder = new Map(ids.map((id, index) => [id, index]));
+    for (const asset of assets) assertPngAsset(asset);
+    return assets.sort((left, right) => left.outputIndex - right.outputIndex || (jobOrder.get(left.id) ?? Number.MAX_SAFE_INTEGER) - (jobOrder.get(right.id) ?? Number.MAX_SAFE_INTEGER) || left.id.localeCompare(right.id));
+  }
+};
+function scenarioOptions(spec) {
+  return spec.providerOptions;
+}
+function scenarioBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("SCENARIO_API_BASE_URL must be an absolute HTTP(S) URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("SCENARIO_API_BASE_URL must use HTTP or HTTPS");
+  }
+  return url.href.replace(/\/$/, "");
+}
+function requestBody(spec, options) {
+  return {
+    ...options.parameters ?? {},
+    prompt: spec.prompt,
+    width: spec.width,
+    height: spec.height,
+    numOutputs: options.numOutputs ?? 1,
+    ...spec.seed != null ? { seed: spec.seed } : {}
+  };
+}
+function validateParameters(parameters) {
+  if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
+    throw new Error("Scenario parameters must be a JSON object");
+  }
+  for (const key of Object.keys(parameters)) {
+    if (PROTECTED_PARAMETERS.has(key)) {
+      throw new Error(`Scenario parameters.${key} is managed by PixelKiln and cannot be overridden`);
+    }
+  }
+  assertJsonValue(parameters, "Scenario parameters");
+}
+function assertJsonValue(value, label, seen = /* @__PURE__ */ new Set()) {
+  if (value == null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite number`);
+    return;
+  }
+  if (typeof value !== "object") throw new Error(`${label} must contain only JSON values`);
+  if (!Array.isArray(value)) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error(`${label} must contain only plain JSON objects`);
+    }
+  }
+  if (seen.has(value)) throw new Error(`${label} contains a circular value`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonValue(item, `${label}[${index}]`, seen));
+  } else {
+    for (const [key, item] of Object.entries(value)) {
+      assertJsonValue(item, `${label}.${key}`, seen);
+    }
+  }
+  seen.delete(value);
+}
+function jobRef(jobId, projectId) {
+  const url = new URL("scenario://job");
+  url.searchParams.set("id", jobId);
+  if (projectId) url.searchParams.set("projectId", projectId);
+  return url.href;
+}
+function parseJobRef(value) {
+  if (!value.startsWith(`${SOURCE_PROTOCOL2}//`)) return { jobId: value };
+  const url = new URL(value);
+  const jobId = url.searchParams.get("id");
+  if (url.protocol !== SOURCE_PROTOCOL2 || url.hostname !== "job" || !jobId) {
+    throw new Error("Invalid durable Scenario job reference");
+  }
+  const projectId = url.searchParams.get("projectId") || void 0;
+  return { jobId, ...projectId ? { projectId } : {} };
+}
+function assetRef(assetId, projectId) {
+  const url = new URL("scenario://asset");
+  url.searchParams.set("id", assetId);
+  if (projectId) url.searchParams.set("projectId", projectId);
+  return url.href;
+}
+function parseAssetRef(value) {
+  const url = new URL(value);
+  const assetId = url.searchParams.get("id");
+  if (url.protocol !== SOURCE_PROTOCOL2 || url.hostname !== "asset" || !assetId) {
+    throw new Error("Invalid durable Scenario asset reference");
+  }
+  const projectId = url.searchParams.get("projectId") || void 0;
+  return { assetId, ...projectId ? { projectId } : {} };
+}
+function readJobId(value) {
+  if (!value || typeof value !== "object") return null;
+  const job = value;
+  const id = job.jobId ?? job.id;
+  return typeof id === "string" && id ? id : null;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function scenarioAssetIds(job) {
+  const ids = job.metadata?.assetIds;
+  return Array.isArray(ids) ? [...new Set(ids.filter((id) => typeof id === "string" && id.length > 0))] : [];
+}
+function assetDownloadUrl(asset) {
+  return asset.originalFileUrl || asset.url;
+}
+function assertPngAsset(asset) {
+  if (asset.originalMimeType && asset.originalMimeType !== MediaType.PNG) {
+    throw new Error(
+      `Scenario asset ${asset.id} is ${asset.originalMimeType}; PixelKiln's Scenario MVP requires PNG output`
+    );
+  }
+}
+function jobMetadata(job, options) {
+  const billing = job.billing;
+  const billedMain = optionalFiniteNonnegative(billing?.cuCost, "Scenario job returned invalid CU billing");
+  const billedAddons = Object.values(numericRecord(billing?.cuCostDetails)).reduce((sum, amount) => sum + amount, 0);
+  return {
+    ...options ? {
+      modelId: options.modelId,
+      projectId: options.projectId ?? null,
+      maxComputeUnits: options.maxComputeUnits
+    } : {},
+    apiJobId: job.jobId,
+    billedComputeUnits: billedMain + billedAddons,
+    billing: billing ?? null
+  };
+}
+function scenarioJobError(job) {
+  const raw = job.metadata?.error;
+  const detail = typeof raw === "string" ? raw : raw && typeof raw === "object" && typeof raw.message === "string" ? String(raw.message) : "job did not complete";
+  return `Scenario job ${job.status}: ${detail.slice(0, 500)}`;
+}
+function validProgress(progress) {
+  if (typeof progress !== "number" || !Number.isFinite(progress) || progress < 0 || progress > 1) {
+    return null;
+  }
+  return Math.round(progress * 100);
+}
+function finiteNonnegative(value, message5) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(message5);
+  return value;
+}
+function optionalFiniteNonnegative(value, message5) {
+  if (value == null) return 0;
+  return finiteNonnegative(value, message5);
+}
+function numericRecord(value) {
+  if (value == null) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Scenario returned invalid cost details");
+  }
+  const out = {};
+  for (const [key, amount] of Object.entries(value)) {
+    out[key] = finiteNonnegative(amount, `Scenario returned invalid cost detail "${key}"`);
+  }
+  return out;
+}
+function redactScenarioError(value, secrets) {
+  let detail;
+  if (typeof value === "string") detail = value;
+  else if (value && typeof value === "object") {
+    const record = value;
+    const nested = record.error && typeof record.error === "object" ? record.error.message : null;
+    detail = typeof record.message === "string" ? record.message : typeof nested === "string" ? nested : typeof record.detail === "string" ? record.detail : "request failed";
+  } else detail = "request failed";
+  for (const secret of secrets) {
+    if (secret) detail = detail.split(secret).join("[redacted]");
+  }
+  return detail.slice(0, 500);
+}
+
 // src/providers/registry.ts
+function providerCredentialEnvs(factory) {
+  return factory.credentialEnvs ?? (factory.credentialEnv ? [factory.credentialEnv] : []);
+}
 var factories = /* @__PURE__ */ new Map();
 function registerProvider(factory) {
   const id = factory.id.trim();
@@ -2360,6 +2847,15 @@ registerProvider({
     return ComfyUIProvider.forOffline();
   }
 });
+registerProvider({
+  id: "scenario",
+  credentialEnvs: ["SCENARIO_SDK_API_KEY", "SCENARIO_SDK_API_SECRET"],
+  create(mode2) {
+    if (mode2 === "online") return ScenarioProvider.fromEnv();
+    if (mode2 === "downloads") return ScenarioProvider.forDownloads();
+    return ScenarioProvider.forOffline();
+  }
+});
 
 // src/manifest.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -3333,13 +3829,14 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     lastSubmitAt = Date.now();
     try {
       const refs = styleImages.get(spec.styleId) ?? [];
-      const { jobId } = await provider.submit(spec, refs);
+      const { jobId, metadata } = await provider.submit(spec, refs);
       upsert(lock, key, {
         jobId,
         // A multi-candidate generator routes through review; record the parent
         // so `pick` knows where to look.
         reviewObjectId: estimate.candidates > 1 && !spec.tileFeature ? jobId : null,
-        status: "processing"
+        status: "processing",
+        providerMetadata: metadata ? { ...lock.entries[key].providerMetadata, [provider.id]: metadata } : lock.entries[key].providerMetadata
       });
       inFlight.set(jobId, spec);
       submitted++;
@@ -3389,7 +3886,13 @@ async function poll(provider, lock, lockPath, opts = {}) {
           upsert(lock, key, {
             status: "review",
             reviewObjectId: entry.jobId,
-            providerMetadata: state.metadata ? { ...entry.providerMetadata, [provider.id]: state.metadata } : entry.providerMetadata
+            providerMetadata: state.metadata ? {
+              ...entry.providerMetadata,
+              [provider.id]: {
+                ...entry.providerMetadata[provider.id],
+                ...state.metadata
+              }
+            } : entry.providerMetadata
           });
           result.review++;
           log2(`  review  ${key} (${state.candidateUrls.length} candidates)`);
@@ -3400,7 +3903,13 @@ async function poll(provider, lock, lockPath, opts = {}) {
             objectId: state.objectId,
             sourceUrl: sourceUrls[0]?.url ?? null,
             sourceUrls,
-            providerMetadata: state.metadata ? { ...entry.providerMetadata, [provider.id]: state.metadata } : entry.providerMetadata,
+            providerMetadata: state.metadata ? {
+              ...entry.providerMetadata,
+              [provider.id]: {
+                ...entry.providerMetadata[provider.id],
+                ...state.metadata
+              }
+            } : entry.providerMetadata,
             error: null
           });
           result.completed++;
@@ -3760,7 +4269,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
       add(
         checkId,
         "error",
-        !target.apiKeyPresent ? `${target.credentialEnv ?? (legacyTarget ? "PIXELLAB_API_KEY" : `${target.id} credential`)} is not configured` : `${target.id} is not configured`
+        !target.apiKeyPresent ? `${target.missingCredentialEnvs?.length ? target.missingCredentialEnvs.join(", ") : target.credentialEnv ?? (legacyTarget ? "PIXELLAB_API_KEY" : `${target.id} credential`)} ${target.missingCredentialEnvs && target.missingCredentialEnvs.length > 1 ? "are" : "is"} not configured` : `${target.id} is not configured`
       );
     } else if (!target.provider.balance && !target.provider.checkConnection) {
       add(checkId, "ok", `${target.id} configured; connectivity check unavailable`);
@@ -4381,7 +4890,7 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
         const entry = lock.entries[key];
         if (!group || !entry?.reviewObjectId) continue;
         if (!Number.isInteger(index) || index < 0 || index >= group.frameUrls.length) continue;
-        const { objectId, sourceUrl } = await requireSelectCandidate(provider)(
+        const { objectId, sourceUrl, metadata } = await requireSelectCandidate(provider)(
           entry.reviewObjectId,
           index,
           `asset:${entry.assetId}`,
@@ -4393,7 +4902,14 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
           candidateIndex: index,
           sourceUrl: sourceUrl ?? group.frameUrls[index] ?? null,
           sourceUrls: [],
-          provider: provider.id
+          provider: provider.id,
+          providerMetadata: metadata ? {
+            ...entry.providerMetadata,
+            [provider.id]: {
+              ...entry.providerMetadata[provider.id],
+              ...metadata
+            }
+          } : entry.providerMetadata
         });
         selected++;
         log2(`  picked  ${key} \u2192 candidate ${index + 1}`);
@@ -6038,16 +6554,16 @@ async function approveQualityRecord(recordPath, approval) {
 
 // src/pipeline/tileset-export.ts
 function normalizeTileRules(raw) {
-  if (!isRecord(raw)) return null;
+  if (!isRecord2(raw)) return null;
   const ruleType = raw.rule_type;
   const arity = raw.arity;
   if (ruleType !== "edge" && ruleType !== "corner" && ruleType !== "outline") return null;
   if (arity !== 4 && arity !== 6) return null;
   const masks = {};
-  if (isRecord(raw.tiles)) {
+  if (isRecord2(raw.tiles)) {
     for (const [key, value] of Object.entries(raw.tiles)) {
       const index = tileIndex(key);
-      const mask = typeof value === "number" ? value : isRecord(value) && typeof value.bitmask === "number" ? value.bitmask : isRecord(value) && typeof value.mask === "number" ? value.mask : null;
+      const mask = typeof value === "number" ? value : isRecord2(value) && typeof value.bitmask === "number" ? value.bitmask : isRecord2(value) && typeof value.mask === "number" ? value.mask : null;
       if (index !== null && mask !== null && Number.isInteger(mask) && mask >= 0) masks[index] = mask;
     }
   }
@@ -6078,7 +6594,7 @@ function exportTileset(entry, spec, options) {
     );
   }
   const metadata = entry.providerMetadata?.[entry.provider];
-  const rawRules = isRecord(metadata) ? metadata.tileRules : void 0;
+  const rawRules = isRecord2(metadata) ? metadata.tileRules : void 0;
   const rules = normalizeTileRules(rawRules);
   const frames = packed.atlas.frames;
   const generic = buildGeneric(
@@ -6086,7 +6602,7 @@ function exportTileset(entry, spec, options) {
     options.imageName,
     packed.atlas,
     frames,
-    isRecord(rawRules) ? rawRules : null,
+    isRecord2(rawRules) ? rawRules : null,
     rules
   );
   if (options.format === "generic") {
@@ -6288,7 +6804,7 @@ function tileIndex(key) {
   const match = key.match(/(?:^|[_-])(\d+)$/);
   return match ? Number(match[1]) : null;
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -8330,11 +8846,14 @@ async function main() {
     )].sort();
     const providers2 = providerIds.map((id) => {
       const factory = providerFactory(id);
-      const apiKeyPresent = !factory.credentialEnv || Boolean(process.env[factory.credentialEnv]);
+      const credentialEnvs = providerCredentialEnvs(factory);
+      const missingCredentialEnvs = credentialEnvs.filter((name) => !process.env[name]);
+      const apiKeyPresent = missingCredentialEnvs.length === 0;
       return {
         id,
         apiKeyPresent,
         credentialEnv: factory.credentialEnv,
+        missingCredentialEnvs,
         provider: !args.dryRun && apiKeyPresent ? createProvider(id, "online") : void 0
       };
     });