luxin-cli 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -6,6 +6,43 @@ provenance; this file is the human- and agent-readable release map.
 
 ## Unreleased
 
+## 0.2.7 - 2026-08-12
+
+- Release (pricing): the guide's local credit quoting for xAI models moved from
+  a `startsWith("xai.grok-imagine-image")` prefix test to an explicit model-id
+  list. The prefix test would have priced any Grok Imagine model it had never
+  heard of off the 1.x table — for the new `xai.grok-imagine-image-2.0` that
+  meant quoting 4 credits for a 10-credit create. Models outside the list now
+  defer to the hosted registry's published debit instead of guessing.
+- Adds the `xai.grok-imagine-image-2.0` quality×resolution credit matrix to
+  local guide pricing (low/1k through medium/2k), matching the registry the
+  hosted API serves since 2026-08-12. Every tier was verified against live
+  provider billing before release ($0.04/$0.06/$0.07/$0.08 receipts).
+- The registry behind `models show` grew from 290 to 316 models server-side
+  (grok-imagine-image-2.0 create+edit executable and listed; 24 summer-wave
+  fal models cataloged with honest tier pricing before they are wired —
+  reachable via `models show MODEL_ID`, not yet in the `models list` output,
+  which serves executable models only). No CLI change was needed for that —
+  noted here because agents read this file to decide whether to upgrade:
+  upgrade for the pricing fix, not for model availability.
+
+## 0.2.6 - 2026-08-09
+
+- Release (trust): `create --guide` now says when it cannot price the request it
+  is planning, instead of presenting the model's default-shape quote as the
+  planned debit. `selection.planned_debit_source` reports which of the two you
+  got, and the unpriceable case carries a warning pointing at the dry-run.
+- This closes a gap that was invisible rather than wrong: the hosted API
+  published per-aspect-ratio create debits only when they differed from the
+  quote, so an absent field could mean either "the quote already is the debit"
+  or "this server is older than your CLI". The npm package and the hosted API
+  deploy independently, so that second case is permanent, not a one-off, and it
+  under-quoted silently during any deploy gap or rollback. The API now publishes
+  the debit for every create-capable model (107 of 107 live rows), so absence
+  means exactly one thing, and the CLI now treats it that way.
+- Carries the correction to the 0.2.5 note below: the "known issue" that shipped
+  in the 0.2.5 tarball describes behaviour that does not exist.
+
 ## 0.2.5 - 2026-08-09
 
 - Release (correctness): `edit --guide` selects a model again. It gated on
@@ -19,12 +56,15 @@ provenance; this file is the human- and agent-readable release map.
   `selection.suggested_aspect_ratio` read the same unpublished block and
   returned null on every real video call unless the brief happened to name a
   ratio.
-- Known issue (#2259): `create --guide` can quote a different credit figure than
-  the `--dry-run` it hands you, because it prices the model's catalog default
-  shape rather than the ratio the command actually sends. Measured against the
-  live API: 4 vs 5 with no ratio stated, 4 vs 3 at 16:9. The dry-run figure is
-  the authoritative one; budget from it, not from the guide. Unchanged from
-  0.2.4; the fix landed server-side but not in this package.
+- Correction (added after 0.2.5 shipped): the 0.2.5 tarball carries a "known
+  issue" note claiming `create --guide` can quote a different credit figure than
+  the `--dry-run` it hands you. **That note is wrong and the behaviour it
+  describes does not exist.** It was written from a measurement taken during a
+  deploy-skew window, minutes after the fix merged and before the hosted API had
+  deployed its half. Measured after both halves landed, the guide and the dry-run
+  agree: 5 and 5 with no ratio stated, 3 and 3 at 16:9. #2259 is fixed and
+  closed. Budgeting from the dry-run figure remains sound advice, but it is not a
+  workaround for anything.
 
 ## 0.2.4 - 2026-08-09
 

package/bin/luxin.mjs

@@ -15,7 +15,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.2.5";
+const VERSION = "0.2.7";
 const PACKAGE_NAME = "luxin";
 const DEFAULT_API_BASE_URL = "https://api.luxin.sh";
 const DEFAULT_DOCS_BASE_URL = "https://luxin.sh";
@@ -101,12 +101,28 @@ const ACCEPTED_PUBLIC_MEDIA_HOSTS = [
 // price. These are prices, not costs: the CLI never computes or publishes
 // provider cost or margin.
 const XAI_IMAGE_CREDIT_PRICES = {
-  source_image: { standard: 1 / 3, quality: 5 / 3 },
+  source_image: { standard: 1 / 3, quality: 5 / 3, image_2: 5 / 3 },
   output_image: {
     standard: 10 / 3,
     quality: { "1k": 25 / 3, "2k": 35 / 3 },
+    image_2: {
+      low: { "1k": 20 / 3, "2k": 10 },
+      medium: { "1k": 10, "2k": 40 / 3 },
+    },
   },
 };
+// Mirrors src/credit-pricing.ts XAI_IMAGE_MODEL_IDS. This is an explicit list,
+// not a prefix test: a Grok Imagine image model this CLI has never heard of is
+// priced by the hosted registry's published debit, not by guessing it onto the
+// 1.x price table.
+const XAI_LOCALLY_PRICED_IMAGE_MODEL_IDS = new Set([
+  "xai.grok-imagine-image",
+  "xai.grok-imagine-image-edit",
+  "xai.grok-imagine-image-quality",
+  "xai.grok-imagine-image-quality-edit",
+  "xai.grok-imagine-image-2.0",
+  "xai.grok-imagine-image-2.0-edit",
+]);
 const MODALITY_COMMAND_ALIASES = new Map([
   ["image", { command: "create", intent: null }],
   ["video", { command: "create", intent: "video" }],
@@ -2007,6 +2023,16 @@ async function createGuide(args, options = {}) {
           defaultedModelParameters.modelParameters,
           pricingContext,
         );
+  // The quote is not the debit, and against a server that does not publish
+  // debits this CLI cannot compute one -- it has no pricing engine, by design.
+  // Say that plainly instead of letting the caller budget against a number the
+  // product does not charge (#2259, #2272).
+  const plannedDebitUnavailable =
+    selected !== null &&
+    createGuideModelSupportsCreate(selected) &&
+    !createGuideSelectedModelRequiresInputImage(selected) &&
+    !createGuideCanPriceModelParameters(selected) &&
+    !createGuideRegistryPublishesCreditDebit(selected);
   const estimatedCredits = pricing?.credits_required ?? null;
   // The guide publishes what the caller will be charged, never our provider
   // cost. `economics.estimated_usd_per_image` is the hosted charge per image.
@@ -2406,6 +2432,9 @@ async function createGuide(args, options = {}) {
       pricing_source: pricing?.pricing_source ?? null,
       model_parameter_defaults_applied:
         defaultedModelParameters.defaultsApplied,
+      planned_debit_source: plannedDebitUnavailable
+        ? "create_credit_debit_unavailable"
+        : "registry_create_credit_debit",
     },
     blocker,
     guide_warning: guideWarning,
@@ -2443,11 +2472,20 @@ async function createGuide(args, options = {}) {
   for (const field of compactOmittedFields) {
     delete guideData[field];
   }
-  return createGuideSuccess(command, quota?.envelope.actor ?? null, guideData);
+  return createGuideSuccess(
+    command,
+    quota?.envelope.actor ?? null,
+    guideData,
+    plannedDebitUnavailable
+      ? [
+          "create_credit_debit_unavailable: this hosted API does not publish per-aspect-ratio create debits, so the credits above are the model's default-shape quote and may not be what create debits. Run the dry_run command in escape_hatches for the exact figure before budgeting.",
+        ]
+      : [],
+  );
 }
 
-function createGuideSuccess(command, actor, data) {
-  const result = success(command, data);
+function createGuideSuccess(command, actor, data, warnings = []) {
+  const result = success(command, data, warnings);
   result.envelope.actor = actor;
   return result;
 }
@@ -2968,6 +3006,26 @@ function createGuidePricingForModel(model, modelParameters, context = {}) {
 // this CLI has no pricing engine to recompute it -- so the registry publishes
 // the answer and this reads it. Absent field means the quote already is the
 // debit.
+// Does this registry response publish create debits at all?
+//
+// The hosted API and this CLI ship independently, so a client can always be
+// talking to a server older than itself. `create_credit_debit_by_aspect_ratio`
+// is published for EVERY create-capable model precisely so that absence has one
+// meaning -- "this server cannot tell me the debit" -- rather than being
+// confusable with "the debit happens to equal the quote". When it is absent the
+// honest answer is to say so and point at the dry-run, not to present the
+// model's default-shape quote as the planned debit (#2259, #2272).
+function createGuideRegistryPublishesCreditDebit(model) {
+  return (
+    isRecord(model?.economics?.create_credit_debit_by_aspect_ratio) ||
+    isRecord(model?.create_credit_debit_by_aspect_ratio)
+  );
+}
+
+function createGuideModelSupportsCreate(model) {
+  return Array.isArray(model?.supports) && model.supports.includes("create");
+}
+
 function createGuideAspectRatioCreditPricing(model, context) {
   // Both shapes: `GET /v1/models` serves the COMPACT summary, which flattens
   // economics onto the row, and only `?details=true` (or a fixture built from
@@ -2997,14 +3055,16 @@ function createGuideAspectRatioCreditPricing(model, context) {
 }
 
 function createGuideCanPriceModelParameters(model) {
-  return String(model?.id ?? "").startsWith("xai.grok-imagine-image");
+  return XAI_LOCALLY_PRICED_IMAGE_MODEL_IDS.has(String(model?.id ?? ""));
 }
 
 function createGuideXaiImagePricing(model, modelParameters, context) {
   const modelId = String(model?.id ?? "");
   const quality = modelId.includes("-quality");
+  const image2 = modelId.startsWith("xai.grok-imagine-image-2.0");
   const edit = modelId.endsWith("-edit");
   const resolution = modelParameters?.resolution === "2k" ? "2k" : "1k";
+  const image2Quality = modelParameters?.quality === "low" ? "low" : "medium";
   const outputImageCount =
     Number.isInteger(context?.outputCount) && context.outputCount > 0
       ? context.outputCount
@@ -3015,12 +3075,16 @@ function createGuideXaiImagePricing(model, modelParameters, context) {
       ? context.referenceAssetCount
       : 0;
   const sourceImageCount = edit ? 1 + referenceAssetCount : 0;
-  const sourceCredits = quality
-    ? XAI_IMAGE_CREDIT_PRICES.source_image.quality
-    : XAI_IMAGE_CREDIT_PRICES.source_image.standard;
-  const outputCredits = quality
-    ? XAI_IMAGE_CREDIT_PRICES.output_image.quality[resolution]
-    : XAI_IMAGE_CREDIT_PRICES.output_image.standard;
+  const sourceCredits = image2
+    ? XAI_IMAGE_CREDIT_PRICES.source_image.image_2
+    : quality
+      ? XAI_IMAGE_CREDIT_PRICES.source_image.quality
+      : XAI_IMAGE_CREDIT_PRICES.source_image.standard;
+  const outputCredits = image2
+    ? XAI_IMAGE_CREDIT_PRICES.output_image.image_2[image2Quality][resolution]
+    : quality
+      ? XAI_IMAGE_CREDIT_PRICES.output_image.quality[resolution]
+      : XAI_IMAGE_CREDIT_PRICES.output_image.standard;
   const creditsRequired = Math.max(
     1,
     Math.ceil(
@@ -3033,8 +3097,14 @@ function createGuideXaiImagePricing(model, modelParameters, context) {
     modelParameters?.resolution === undefined ||
     modelParameters?.resolution === null ||
     modelParameters?.resolution === "1k";
+  const defaultQuality =
+    !image2 ||
+    modelParameters?.quality === undefined ||
+    modelParameters?.quality === null ||
+    modelParameters?.quality === "medium";
   const defaultShape =
     defaultResolution &&
+    defaultQuality &&
     outputImageCount === 1 &&
     sourceImageCount === (edit ? 1 : 0);
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxin-cli",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Image generation, image editing, video, audio, and image-to-3D for agents, with no API key to obtain first. The agent signs itself up, starts on free preview credits, and gets hosted media URLs, recoverable jobs, and cost receipts.",
   "type": "module",
   "private": false,