pixelkiln 0.47.1 → 0.49.0

package/dist/cli.js

@@ -1374,6 +1374,8 @@ var LockHistoryEntrySchema = z.object({
   downloadedAt: z.string().nullable().default(null),
   cost: z.number().finite().nonnegative().default(0),
   costUnit: z.string().min(1).default("generations"),
+  /** What the provider actually billed, read from the completed job; null when never read. */
+  billed: z.object({ amount: z.number(), unit: z.string() }).nullable().default(null),
   provider: z.string().default("pixellab"),
   postprocess: PostprocessSchema.optional(),
   /** When the replacement was submitted. */
@@ -1465,6 +1467,14 @@ var LockEntrySchema = z.object({
   cost: z.number().finite().nonnegative().default(0),
   /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
   costUnit: z.string().min(1).default("generations"),
+  /**
+   * What the provider actually billed, read from the completed job rather
+   * than estimated at submit time. Null until a poll reads it, and for a
+   * provider or generator `poll` does not read it from at all; `cost` above
+   * is still what a wave budget spends against, since the real number is
+   * only known after the fact.
+   */
+  billed: z.object({ amount: z.number(), unit: z.string() }).nullable().default(null),
   /** Which provider produced this. Absent on entries written before providers. */
   provider: z.string().default("pixellab"),
   /** Generations this entry replaced, newest first; see LockHistoryEntrySchema. */
@@ -5115,6 +5125,10 @@ var TilesProSchema = z2.object({
   kind: z2.string().nullable().default(null),
   tile_rules: z2.record(z2.unknown()).nullable().optional()
 }).passthrough();
+var RevisionJobSubmitSchema = z2.object({
+  background_job_id: z2.string().min(1),
+  status: z2.string().default("processing")
+}).passthrough();
 var PixelLabObjectSchema = z2.object({
   id: z2.string().min(1),
   name: z2.string().nullable().default(null),
@@ -5193,7 +5207,13 @@ var CharacterListSchema = z2.object({ characters: z2.array(CharacterSchema), tot
 var BackgroundJobSchema = z2.object({
   id: z2.string(),
   status: z2.string(),
-  last_response: z2.record(z2.unknown()).nullable().optional()
+  last_response: z2.record(z2.unknown()).nullable().optional(),
+  /**
+   * The billed amount, confirmed live for a `map` object and a standard
+   * character base (docs/ENDPOINTS.md, "Limits and billing"); duplicated at
+   * `last_response.billing_usage` on the jobs observed so far.
+   */
+  usage: UsageSchema
 }).passthrough();
 var DeleteAnimationsSchema = z2.object({ success: z2.boolean(), deleted_count: z2.number().int().default(0), error: z2.string().nullable().optional() }).passthrough();
 function validateResponse(schema, raw, operation) {
@@ -5580,6 +5600,59 @@ var PixelLabClient = class {
       if (page.characters.length === 0 || offset >= page.total) return;
     }
   }
+  /**
+   * Masked inpaint, PixelLab's `/inpaint-v3` (the endpoint its own docs list
+   * first in the Inpaint section, its convention for "reach for this by
+   * default"). Unlike the rest of this client, this method's shape is taken
+   * from the OpenAPI spec, not exercised against a live account: the request
+   * side is exact (`InpaintV3Request`), but a completed job's `last_response`
+   * has no documented example for this endpoint (the spec's only worked
+   * example is a character job's shape). `pollRevision` in pixellab.ts reads
+   * it defensively and fails loudly on an unrecognized shape rather than
+   * guessing.
+   *
+   * `crop_to_mask` defaults true upstream (confirmed in the schema): PixelLab
+   * otherwise blends generated pixels outside the mask edge to "fit
+   * naturally," which is the opposite of what a mask boundary is for.
+   */
+  async inpaintV3(args) {
+    const size = { width: args.width, height: args.height };
+    const body = {
+      description: args.description,
+      inpainting_image: { image: args.image, size },
+      mask_image: { image: args.maskImage, size }
+    };
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.cropToMask != null) body.crop_to_mask = args.cropToMask;
+    if (args.seed != null) body.seed = args.seed;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/inpaint-v3", { method: "POST", body: JSON.stringify(body) }),
+      "inpaint-v3"
+    );
+  }
+  /**
+   * Whole-image edit with no mask, PixelLab's `/edit-images-v2`. Same
+   * not-yet-live-verified caveat as `inpaintV3` above. `edit_images` takes an
+   * array (the endpoint supports editing several images with one
+   * instruction); pixelkiln's `revision` model is one parent per child, so
+   * this always sends exactly one.
+   */
+  async editImagesV2(args) {
+    const body = {
+      method: "edit_with_text",
+      description: args.description,
+      edit_images: [{ image: args.image, width: args.width, height: args.height }],
+      image_size: { width: args.width, height: args.height }
+    };
+    if (args.noBackground != null) body.no_background = args.noBackground;
+    if (args.seed != null) body.seed = args.seed;
+    return validateResponse(
+      RevisionJobSubmitSchema,
+      await this.request("/edit-images-v2", { method: "POST", body: JSON.stringify(body) }),
+      "edit-images-v2"
+    );
+  }
   async getBackgroundJob(jobId) {
     const raw = await this.request(`/background-jobs/${encodeURIComponent(jobId)}`);
     return validateResponse(BackgroundJobSchema, raw, "background-jobs/{id}");
@@ -5647,6 +5720,14 @@ function pixelLabObjectUrl(generator, objectId) {
   }
   return null;
 }
+function billedFromUsage(usage) {
+  if (!usage) return null;
+  if (usage.type === "usd" || usage.type === void 0 && typeof usage.usd === "number") {
+    return typeof usage.usd === "number" ? { amount: usage.usd, unit: "usd" } : null;
+  }
+  if (typeof usage.generations === "number") return { amount: usage.generations, unit: "generations" };
+  return null;
+}
 function characterCost(spec) {
   const character = spec.character;
   if (!character) return generationCost(spec.width, spec.height, "1dir");
@@ -5712,6 +5793,15 @@ var PixelLabProvider = class _PixelLabProvider {
   supports(generator) {
     return generator === "1dir" || generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "character";
   }
+  /**
+   * `inpaint` (`/inpaint-v3`, a mask) and `image-to-image` (`/edit-images-v2`,
+   * no mask) both exist on PixelLab. `outpaint` does not: there is no
+   * canvas-expansion endpoint in the API, matching docs/REVISIONS.md's note
+   * that no provider ships a tested outpaint path yet.
+   */
+  supportsRevision(mode2) {
+    return mode2 === "inpaint" || mode2 === "image-to-image";
+  }
   /** PixelLab's own constraints: submissions must be >2s apart, and
    *  background jobs in flight are capped by subscription tier (Tier 1=8,
    *  Tier 2=10, Tier 3=20); 8 is the safe floor across every tier. */
@@ -5732,6 +5822,11 @@ var PixelLabProvider = class _PixelLabProvider {
     return dir;
   }
   estimate(spec) {
+    if (spec.revision) {
+      const width = spec.revision.sourceWidth ?? spec.width;
+      const height = spec.revision.sourceHeight ?? spec.height;
+      return { unit: "generations", amount: generationCost(width, height, "1dir"), candidates: 1 };
+    }
     if (spec.generator === "tiles") {
       return { unit: "generations", amount: spec.cost, candidates: spec.candidates };
     }
@@ -5745,6 +5840,12 @@ var PixelLabProvider = class _PixelLabProvider {
     };
   }
   validate(spec, styleImages) {
+    if (spec.revision?.mode === "inpaint") {
+      const { sourceWidth: width, sourceHeight: height } = spec.revision;
+      if (width != null && height != null && (width < 32 || height < 32 || width > 512 || height > 512)) {
+        throw new Error(`PixelLab inpaint source is ${width}x${height}; the API takes 32 to 512 pixels per side`);
+      }
+    }
     if (spec.generator === "1dir" && (spec.width < 32 || spec.width > 256)) {
       throw new Error("PixelLab 1dir dimensions must be between 32 and 256 pixels");
     }
@@ -6017,6 +6118,7 @@ var PixelLabProvider = class _PixelLabProvider {
     if (character.status !== "completed" || !character.rotation_urls) return { status: "processing" };
     const sources = rotationSources(character);
     if (!sources.length) return { status: "failed", error: "character completed with no rotation images" };
+    const backgroundJobId = context?.metadata?.character?.backgroundJobId;
     return {
       status: "ready",
       objectId: character.id,
@@ -6032,7 +6134,8 @@ var PixelLabProvider = class _PixelLabProvider {
           size: character.size,
           updatedAt: character.updated_at ?? null
         }
-      }
+      },
+      billed: await this.billedForJob(backgroundJobId)
     };
   }
   /**
@@ -6044,7 +6147,7 @@ var PixelLabProvider = class _PixelLabProvider {
    */
   async pollCharacterAnimation(job, context) {
     const fps = context?.spec?.character?.animation?.fps ?? 8;
-    const review = (frames, animationId, groupId) => ({
+    const review = (frames, animationId, groupId, billed) => ({
       status: "review-set",
       objectId: `${job.characterId}#${groupId ?? animationId ?? job.name}`,
       frameUrls: frames,
@@ -6060,7 +6163,8 @@ var PixelLabProvider = class _PixelLabProvider {
           animationName: job.name,
           direction: job.direction
         }
-      }
+      },
+      billed
     });
     let cleanedUp = job.jobIds.length === 0;
     for (const id of job.jobIds) {
@@ -6080,17 +6184,18 @@ var PixelLabProvider = class _PixelLabProvider {
       if (Array.isArray(frames) && frames.length && frames.every((f) => typeof f === "string")) {
         const character2 = await this.client.getCharacter(job.characterId);
         const group = findAnimation(character2, job.name, job.direction, animationId);
-        return review(frames, animationId, group?.groupId ?? null);
+        return review(frames, animationId, group?.groupId ?? null, billedFromUsage(status.usage));
       }
     }
     const recorded = context?.metadata?.character?.animationId ?? null;
     const character = await this.client.getCharacter(job.characterId);
     const found = findAnimation(character, job.name, job.direction, recorded);
-    if (found) return review(found.frames, found.animationId, found.groupId);
+    if (found) return review(found.frames, found.animationId, found.groupId, null);
     return cleanedUp ? { status: "failed", error: `animation job is gone upstream and no "${job.name}" ${job.direction} animation exists on the character` } : { status: "processing" };
   }
   async submit(spec, styleImages, context) {
     this.validate(spec, styleImages);
+    if (spec.revision) return this.submitRevision(spec);
     if (spec.generator === "character") return this.submitCharacter(spec, styleImages, context);
     if (spec.generator === "pixflux") {
       const swatch = spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0;
@@ -6119,7 +6224,7 @@ var PixelLabProvider = class _PixelLabProvider {
         // unlike 1dir's {type, base64, format} payload.
         styleImages: styleImages.map(({ base64, width, height }) => ({ base64, width, height }))
       });
-      return { jobId: res2.tile_id };
+      return { jobId: res2.tile_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
     if (spec.generator === "1dir") {
       const res2 = await this.client.create1Direction({
@@ -6128,7 +6233,7 @@ var PixelLabProvider = class _PixelLabProvider {
         view: spec.view === "sidescroller" ? "sidescroller" : "top-down",
         styleImages
       });
-      return { jobId: res2.object_id };
+      return { jobId: res2.object_id, metadata: { backgroundJobId: res2.background_job_id } };
     }
     const res = await this.client.createMapObject({
       description: spec.prompt,
@@ -6140,9 +6245,79 @@ var PixelLabProvider = class _PixelLabProvider {
       detail: spec.detail,
       seed: spec.seed
     });
-    return { jobId: res.object_id };
+    return { jobId: res.object_id, metadata: { backgroundJobId: res.background_job_id } };
+  }
+  /**
+   * `inpaint` reads the mask as PixelLab's own convention: white marks the
+   * area to generate, black the area to preserve (`InpaintV3Request`'s own
+   * field description). Unlike ComfyUI's revision graph, there is no
+   * configurable side to this — document it as fixed rather than leave an
+   * agent to guess, the way docs/REVISIONS.md tells a ComfyUI author to test
+   * their own graph.
+   */
+  async submitRevision(spec) {
+    const revision = spec.revision;
+    if (!revision.sourceSha256 || !revision.sourceFormat || revision.sourceWidth == null || revision.sourceHeight == null) {
+      throw new Error(`${spec.styleId}/${spec.assetId}: revision source is not ready`);
+    }
+    const sourceBytes = readFileSync2(revision.sourceFile);
+    if (sha256(sourceBytes) !== revision.sourceSha256) {
+      throw new Error(`${spec.styleId}/${spec.assetId}: revision source changed after the manifest was resolved`);
+    }
+    const image = { base64: sourceBytes.toString("base64"), format: revision.sourceFormat };
+    const width = revision.sourceWidth;
+    const height = revision.sourceHeight;
+    if (revision.mode === "inpaint") {
+      if (!revision.maskFile || !revision.maskSha256 || !revision.maskFormat) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: revision mask is not ready`);
+      }
+      const maskBytes = readFileSync2(revision.maskFile);
+      if (sha256(maskBytes) !== revision.maskSha256) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: revision mask changed after the manifest was resolved`);
+      }
+      const res2 = await this.client.inpaintV3({
+        description: spec.prompt,
+        image,
+        width,
+        height,
+        maskImage: { base64: maskBytes.toString("base64"), format: revision.maskFormat },
+        noBackground: spec.noBackground,
+        seed: spec.seed
+      });
+      return { jobId: res2.background_job_id };
+    }
+    if (revision.strength != null) {
+      throw new Error(
+        `${spec.styleId}/${spec.assetId}: PixelLab image-to-image revisions take no strength; edit-images-v2 always applies the full instruction`
+      );
+    }
+    const res = await this.client.editImagesV2({
+      description: spec.prompt,
+      image,
+      width,
+      height,
+      noBackground: spec.noBackground,
+      seed: spec.seed
+    });
+    return { jobId: res.background_job_id };
+  }
+  /**
+   * What a background job actually billed, once its own record is still
+   * around to ask; see `billedFromUsage`. A stale or already-cleaned-up job
+   * (a map object's record expires in hours; see `pollMap`) means "not
+   * known", not a failure worth surfacing.
+   */
+  async billedForJob(backgroundJobId) {
+    if (!backgroundJobId) return null;
+    try {
+      const job = await this.client.getBackgroundJob(backgroundJobId);
+      return billedFromUsage(job.usage);
+    } catch {
+      return null;
+    }
   }
   async poll(jobId, generator, context) {
+    if (context?.spec?.revision) return this.pollRevision(jobId);
     if (generator === "pixflux") {
       const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
       if (existsSync7(file)) {
@@ -6154,16 +6329,17 @@ var PixelLabProvider = class _PixelLabProvider {
         error: "pixflux result is no longer cached locally; re-run submit for this asset"
       };
     }
-    if (generator === "map") return this.pollMap(jobId);
-    if (generator === "tiles") return this.pollTiles(jobId, Boolean(context?.tileFeature));
+    if (generator === "map") return this.pollMap(jobId, context);
+    if (generator === "tiles") return this.pollTiles(jobId, Boolean(context?.tileFeature), context);
     if (generator === "character") return this.pollCharacter(jobId, context);
+    const backgroundJobId = context?.metadata?.backgroundJobId;
     const obj = await this.client.getObject(jobId);
     if (obj.status === "review") {
-      return { status: "review", candidateUrls: obj.frame_urls ?? [] };
+      return { status: "review", candidateUrls: obj.frame_urls ?? [], billed: await this.billedForJob(backgroundJobId) };
     }
     if (obj.status === "completed") {
       const url = firstUrl(obj.rotation_urls) ?? obj.preview_url ?? null;
-      return { status: "ready", objectId: obj.id, sourceUrl: url, sources: url ? [{ url }] : [] };
+      return { status: "ready", objectId: obj.id, sourceUrl: url, sources: url ? [{ url }] : [], billed: await this.billedForJob(backgroundJobId) };
     }
     if (obj.status === "failed") return { status: "failed", error: "generation failed upstream" };
     return {
@@ -6172,6 +6348,58 @@ var PixelLabProvider = class _PixelLabProvider {
       etaSeconds: obj.eta_seconds ?? null
     };
   }
+  /**
+   * `/inpaint-v3` and `/edit-images-v2` both hand back a plain background
+   * job with no resource of its own, polled generically at
+   * `GET /background-jobs/{id}`. What a *completed* job's `last_response`
+   * actually contains is not documented for either endpoint: the OpenAPI
+   * spec's only worked example of that field is a character job's shape
+   * (`character_id`, `uploaded_directions`, ...), not an inpaint or edit
+   * job's. This reads every image shape seen elsewhere in this client
+   * (a nested `{image: {base64, format}}`, a bare `{base64, format}`, or a
+   * hosted URL under a handful of plausible keys) and fails loudly, naming
+   * the keys it actually got, rather than guess wrong silently. Fixing a
+   * real completed response into this list is a one-line change once one is
+   * seen live.
+   */
+  async pollRevision(jobId) {
+    const job = await this.client.getBackgroundJob(jobId);
+    if (job.status === "failed") return { status: "failed", error: "revision job failed upstream" };
+    if (job.status !== "completed") return { status: "processing" };
+    const billed = billedFromUsage(job.usage);
+    const done = job.last_response ?? {};
+    const urlKeys = ["image_url", "download_url", "url", "output_url"];
+    for (const key of urlKeys) {
+      const url = done[key];
+      if (typeof url === "string" && url) {
+        return { status: "ready", objectId: jobId, sourceUrl: url, sources: [{ url }], billed };
+      }
+    }
+    const imageKeys = ["image", "output_image", "result_image", "edited_image"];
+    for (const key of imageKeys) {
+      const candidate = done[key];
+      const base64 = extractBase64(candidate);
+      if (base64) {
+        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        writeFileSync(file, Buffer.from(base64, "base64"));
+        const sourceUrl = `file://${file}`;
+        return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
+      }
+    }
+    if (Array.isArray(done.images) && done.images.length) {
+      const base64 = extractBase64(done.images[0]);
+      if (base64) {
+        const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+        writeFileSync(file, Buffer.from(base64, "base64"));
+        const sourceUrl = `file://${file}`;
+        return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }], billed };
+      }
+    }
+    return {
+      status: "failed",
+      error: `Invalid PixelLab response for revision job ${jobId}: completed with no recognized image field (got: ${Object.keys(done).join(", ") || "no keys"}); update pollRevision in src/providers/pixellab.ts with the real shape`
+    };
+  }
   /**
    * Map objects need their own path because the `/map-objects/{id}` record is
    * deleted upstream roughly 8 hours after creation while the image survives in
@@ -6179,7 +6407,8 @@ var PixelLabProvider = class _PixelLabProvider {
    * `/objects` four months on, with `/map-objects` returning 404 for the same
    * id. So a 404 here is not evidence the work is lost.
    */
-  async pollMap(jobId) {
+  async pollMap(jobId, context) {
+    const backgroundJobId = context?.metadata?.backgroundJobId;
     try {
       const obj = await this.client.getMapObject(jobId);
       if (obj.status === "completed" && obj.download_url) {
@@ -6187,7 +6416,8 @@ var PixelLabProvider = class _PixelLabProvider {
           status: "ready",
           objectId: jobId,
           sourceUrl: obj.download_url,
-          sources: [{ url: obj.download_url }]
+          sources: [{ url: obj.download_url }],
+          billed: await this.billedForJob(backgroundJobId)
         };
       }
       if (obj.status === "failed") return { status: "failed", error: "generation failed upstream" };
@@ -6198,7 +6428,7 @@ var PixelLabProvider = class _PixelLabProvider {
       const survivor = await this.client.getObject(jobId).catch(() => null);
       const url = firstUrl(survivor?.rotation_urls) ?? survivor?.preview_url ?? null;
       if (survivor?.status === "completed" && url) {
-        return { status: "ready", objectId: survivor.id, sourceUrl: url, sources: [{ url }] };
+        return { status: "ready", objectId: survivor.id, sourceUrl: url, sources: [{ url }], billed: null };
       }
       return {
         status: "failed",
@@ -6211,12 +6441,14 @@ var PixelLabProvider = class _PixelLabProvider {
    * `storage_urls` once finished. There is no `status` field to read and no
    * progress percentage on offer, so "processing" here carries no ETA.
    */
-  async pollTiles(tileId, connectable) {
+  async pollTiles(tileId, connectable, context) {
     try {
       const set = await this.client.getTilesPro(tileId);
       const tiles = tilesInIndexOrder(set.storage_urls);
       if (!tiles.length) return { status: "failed", error: "tiles job returned no storage urls" };
-      if (!connectable) return { status: "review", candidateUrls: tiles.map((tile) => tile.url) };
+      const backgroundJobId = context?.metadata?.backgroundJobId;
+      const billed = await this.billedForJob(backgroundJobId);
+      if (!connectable) return { status: "review", candidateUrls: tiles.map((tile) => tile.url), billed };
       return {
         status: "ready",
         objectId: tileId,
@@ -6228,7 +6460,8 @@ var PixelLabProvider = class _PixelLabProvider {
         metadata: {
           tileKind: set.kind,
           ...set.tile_rules ? { tileRules: set.tile_rules } : {}
-        }
+        },
+        billed
       };
     } catch (err) {
       if (err instanceof PixelLabError && err.status === 423) return { status: "processing" };
@@ -6358,6 +6591,15 @@ function firstUrl(urls) {
   if (!urls) return null;
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
+function extractBase64(value) {
+  if (typeof value === "string" && value) return value;
+  if (value && typeof value === "object") {
+    const obj = value;
+    if (typeof obj.base64 === "string" && obj.base64) return obj.base64;
+    if (obj.image) return extractBase64(obj.image);
+  }
+  return null;
+}
 function readReference(spec, reference) {
   const images = {};
   for (const [direction, image] of Object.entries(reference)) {
@@ -10722,6 +10964,7 @@ function retireGeneration(entry, retiredAt) {
     downloadedAt: entry.downloadedAt,
     cost: entry.cost,
     costUnit: entry.costUnit,
+    billed: entry.billed,
     provider: entry.provider,
     postprocess: entry.postprocess,
     retiredAt
@@ -10812,6 +11055,7 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     downloadedAt: generation.downloadedAt,
     cost: generation.cost,
     costUnit: generation.costUnit,
+    billed: generation.billed,
     provider: generation.provider,
     postprocess: generation.postprocess,
     history
@@ -10870,12 +11114,15 @@ function describeHistory(media, entry, cacheDir) {
       height: generation.height,
       cost: generation.cost,
       costUnit: generation.costUnit,
+      billed: generation.billed,
       submittedAt: generation.submittedAt,
       downloadedAt: generation.downloadedAt,
       retiredAt: generation.retiredAt,
       outputs,
       cached: outputs.length > 0 && outputs.every((output) => output.url !== null),
-      upstreamUrl: generation.provider === "pixellab" ? pixelLabObjectUrl(generation.generator, generation.objectId) : null
+      // A revision's jobId is a plain background job id, not a PixelLab
+      // account object: there is no `/create-object` page to point at.
+      upstreamUrl: generation.provider === "pixellab" && !entry.revision ? pixelLabObjectUrl(generation.generator, generation.objectId) : null
     };
   });
 }
@@ -11113,6 +11360,7 @@ async function buildGallerySnapshot(opts) {
       fps: quality?.frameSet?.fps ?? metadataFps(entry) ?? spec.quality?.fps ?? null,
       cost: entry?.cost ?? 0,
       costUnit: entry?.costUnit ?? spec.costUnit,
+      billed: entry?.billed ?? null,
       estimatedCost: spec.cost,
       candidates: spec.candidates,
       submittedAt: entry?.submittedAt ?? null,
@@ -11139,7 +11387,7 @@ async function buildGallerySnapshot(opts) {
       editChanged,
       editStatus,
       editMeta,
-      upstreamUrl: entry?.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      upstreamUrl: entry?.provider === "pixellab" && !spec.revision ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
       refreshable: Boolean(entry && entry.status === "downloaded" && entry.outputs.length && (entry.sourceUrls?.length || entry.sourceUrl)),
       history: entry ? describeHistory(media, entry, cacheDir) : [],
       tags: spec.tags,
@@ -11176,6 +11424,7 @@ async function buildGallerySnapshot(opts) {
       fps: metadataFps(entry),
       cost: entry.cost,
       costUnit: entry.costUnit,
+      billed: entry.billed,
       estimatedCost: null,
       candidates: null,
       submittedAt: entry.submittedAt,
@@ -11202,7 +11451,7 @@ async function buildGallerySnapshot(opts) {
       editChanged: [],
       editStatus: null,
       editMeta: null,
-      upstreamUrl: entry.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      upstreamUrl: entry.provider === "pixellab" && !entry.revision ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
       refreshable: false,
       history: describeHistory(media, entry, cacheDir),
       tags: [],
@@ -11818,7 +12067,8 @@ async function poll(provider, lock, lockPath, opts = {}) {
                 ...entry.providerMetadata[provider.id],
                 ...state.metadata
               }
-            } : entry.providerMetadata
+            } : entry.providerMetadata,
+            billed: state.billed ?? entry.billed
           });
           result.review++;
           log2(
@@ -11838,7 +12088,8 @@ async function poll(provider, lock, lockPath, opts = {}) {
                 ...state.metadata
               }
             } : entry.providerMetadata,
-            error: null
+            error: null,
+            billed: state.billed ?? entry.billed
           });
           result.completed++;
           log2(`  ready   ${key}`);
@@ -13746,6 +13997,10 @@ async function runLifecycle(args, wave, spent) {
 }
 
 // src/cli/commands/history.ts
+function billedNote(cost, costUnit, billed) {
+  if (!billed || billed.unit === costUnit && billed.amount === cost) return "";
+  return `  (billed ${formatCost(billed.unit, billed.amount)})`;
+}
 async function runHistory(args) {
   const { loaded, specs, lock } = await openProject2(args);
   const limit = historyLimit(loaded.manifest);
@@ -13756,7 +14011,7 @@ async function runHistory(args) {
       limit,
       assets: selected.map(({ spec, entry }) => ({
         key: lockKey(spec.styleId, spec.assetId),
-        current: entry ? { objectId: entry.objectId, outputs: entry.outputs, downloadedAt: entry.downloadedAt, cost: entry.cost, costUnit: entry.costUnit } : null,
+        current: entry ? { objectId: entry.objectId, outputs: entry.outputs, downloadedAt: entry.downloadedAt, cost: entry.cost, costUnit: entry.costUnit, billed: entry.billed } : null,
         history: entry?.history ?? []
       }))
     }, null, 2));
@@ -13770,10 +14025,10 @@ async function runHistory(args) {
     const key = lockKey(spec.styleId, spec.assetId);
     log(`
   ${key}`);
-    log(`    current  ${entry.outputs[0]?.sha256.slice(0, 12) ?? "\u2014"}  ${entry.downloadedAt ?? ""}  ${entry.objectId ?? ""}`);
+    log(`    current  ${entry.outputs[0]?.sha256.slice(0, 12) ?? "\u2014"}  ${entry.downloadedAt ?? ""}  ${entry.objectId ?? ""}${billedNote(entry.cost, entry.costUnit, entry.billed)}`);
     for (const [i, generation] of entry.history.entries()) {
       const changed = generation.prompt !== entry.prompt ? "  (different prompt)" : "";
-      log(`    #${String(i + 1).padEnd(2)}      ${generation.outputs[0]?.sha256.slice(0, 12) ?? "\u2014"}  ${generation.downloadedAt ?? ""}  ${generation.objectId ?? ""}${changed}`);
+      log(`    #${String(i + 1).padEnd(2)}      ${generation.outputs[0]?.sha256.slice(0, 12) ?? "\u2014"}  ${generation.downloadedAt ?? ""}  ${generation.objectId ?? ""}${changed}${billedNote(generation.cost, generation.costUnit, generation.billed)}`);
     }
   }
   if (!shown) log(`  no asset has a previous generation recorded${selected.length ? "" : " (nothing selected)"}`);
@@ -14468,21 +14723,29 @@ async function runPlan(args) {
         actionable: group.actionable.map((item) => item.key)
       })),
       actionable: plan.actionable.map((i) => i.key),
-      items: plan.items.map(({ key, state, reason, quality, spec }) => ({
-        key,
-        state,
-        reason,
-        ...spec.revision ? {
-          revision: {
-            mode: spec.revision.mode,
-            from: spec.revision.sourceAssetId,
-            sourceSha256: spec.revision.sourceSha256,
-            ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {},
-            ...spec.revision.strength == null ? {} : { strength: spec.revision.strength }
-          }
-        } : {},
-        ...quality ? { quality: { state: quality.state, reason: quality.reason } } : {}
-      }))
+      items: plan.items.map(({ key, state, reason, quality, spec }) => {
+        const entry = lock.entries[key];
+        const billedDiffers = entry?.billed && (entry.billed.unit !== entry.costUnit || entry.billed.amount !== entry.cost);
+        return {
+          key,
+          state,
+          reason,
+          ...spec.revision ? {
+            revision: {
+              mode: spec.revision.mode,
+              from: spec.revision.sourceAssetId,
+              sourceSha256: spec.revision.sourceSha256,
+              ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {},
+              ...spec.revision.strength == null ? {} : { strength: spec.revision.strength }
+            }
+          } : {},
+          ...quality ? { quality: { state: quality.state, reason: quality.reason } } : {},
+          // The estimate a wave budget spent against; present alongside the
+          // provider's actual charge only when `poll` has read one and it
+          // differs, since that is the only time the gap is worth a look.
+          ...billedDiffers ? { cost: entry.cost, costUnit: entry.costUnit, billed: entry.billed } : {}
+        };
+      })
     }, null, 2));
   } else {
     printPlan(plan);