luxin-cli 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -6,6 +6,46 @@ provenance; this file is the human- and agent-readable release map.
 
 ## Unreleased
 
+## 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
+  `media.input.images.required`, which the hosted `/v1/models` summary does not
+  publish, so on 0.2.4 every edit brief returned `no_executable_model` and the
+  blocker named `create`. The predicate now reads `supports`, which the summary
+  does publish; measured on the live 220-model catalog the two express the same
+  79-model set, so this drops a redundant conjunct rather than a guarantee. The
+  blocker also names the operation it actually failed on.
+- Release (correctness): a plain video brief reports its aspect ratio again.
+  `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.
+- 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
 
 - Release (correctness): the guide honors an aspect ratio stated in the brief

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.4";
+const VERSION = "0.2.6";
 const PACKAGE_NAME = "luxin";
 const DEFAULT_API_BASE_URL = "https://api.luxin.sh";
 const DEFAULT_DOCS_BASE_URL = "https://luxin.sh";
@@ -1933,7 +1933,16 @@ async function createGuide(args, options = {}) {
           requestedAspectRatio: briefAspectRatio,
         });
   let selection = selectModel(listedModels);
-  if (briefAspectRatio !== null && listedModels !== null) {
+  // The compact hosted list omits `media.input.aspect_ratios` entirely, so the
+  // ratio capability can only come from the detail endpoint. Probe when the
+  // brief named a ratio (selection itself has to be capability-aware) and also
+  // when the pick is a video model: `selection.suggested_aspect_ratio` is
+  // video-only, and without the probe it reported null on every real video
+  // brief that did not state a ratio -- the same
+  // published-payload-omits-the-field defect as #2265, one field over.
+  const needsAspectRatioCapabilities =
+    briefAspectRatio !== null || selection?.model?.modality === "video";
+  if (needsAspectRatioCapabilities && listedModels !== null) {
     // Two-pass: the first pass names the models worth asking about, then one
     // bounded round of detail lookups makes the second pass actually
     // capability-aware instead of guessing.
@@ -1943,6 +1952,7 @@ async function createGuide(args, options = {}) {
         models: listedModels,
         selected: selection?.model ?? null,
         intent: requestedIntent,
+        routing: briefAspectRatio !== null,
       }),
       apiBaseUrl,
     });
@@ -1983,22 +1993,30 @@ async function createGuide(args, options = {}) {
           modelParameters: modelParameters.value ?? {},
           maxEstimatedUsdPerImage,
         });
-  const shouldPriceModelParameters =
+  // Price the request the guide is about to emit, at the ratio it will emit it
+  // with -- not the registry's default-shape quote, which describes a request
+  // `create` never makes (#2259). Models priced from input-image dimensions stay
+  // on the quote: the guide uploads nothing, so there are no dimensions to price
+  // from. `tests/hosted-create-estimate-parity.test.ts` pins this against the
+  // source dry-run so the two implementations cannot drift apart again.
+  const pricing =
+    selected === null || createGuideSelectedModelRequiresInputImage(selected)
+      ? createGuideModelCreditPricing(selected)
+      : createGuidePricingForModel(
+          selected,
+          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) &&
-    (defaultedModelParameters.defaultsApplied.length > 0 ||
-      Object.keys(modelParameters.value ?? {}).length > 0);
-  const pricing =
-    selected === null
-      ? null
-      : shouldPriceModelParameters
-        ? createGuidePricingForModel(
-            selected,
-            defaultedModelParameters.modelParameters,
-            pricingContext,
-          )
-        : createGuideModelCreditPricing(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.
@@ -2057,6 +2075,7 @@ async function createGuide(args, options = {}) {
     guideCommandPrefix,
   );
   const blocker = createGuideBlocker(stage, {
+    operation: guideOperation,
     requestedModelId,
     quota,
     estimatedCredits,
@@ -2397,6 +2416,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,
@@ -2434,11 +2456,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;
 }
@@ -2467,8 +2498,6 @@ function selectCreateGuideModel(
   const isExecutableInputImageEdit = (model) =>
     model?.status === "available" &&
     guideModelExecutionStatus(model) === "executable" &&
-    Array.isArray(model?.supports) &&
-    (model.supports.includes("edit") || model.supports.includes("variation")) &&
     createGuideSelectedModelRequiresInputImage(model);
   const isExecutableGuideModel = (model) =>
     operation === "edit"
@@ -2585,16 +2614,21 @@ function selectCreateGuideModel(
 // capability UNKNOWN, which never disqualifies a model and never triggers the
 // unsupported-ratio warning.
 
-function guideAspectRatioProbeModelIds({ models, selected, intent }) {
+function guideAspectRatioProbeModelIds({ models, selected, intent, routing }) {
   const ids = [];
   if (typeof selected?.id === "string") {
     ids.push(selected.id);
   }
-  for (const modelId of preferredCreateGuideModelIds(
-    createGuideIntentClass(intent),
-  )) {
-    if (models.some((model) => model?.id === modelId)) {
-      ids.push(modelId);
+  // Only a stated ratio can make the guide hop between models. Without one the
+  // sole open question is what the current pick can express, so asking about
+  // the alternatives would be a round trip spent on an answer nothing reads.
+  if (routing) {
+    for (const modelId of preferredCreateGuideModelIds(
+      createGuideIntentClass(intent),
+    )) {
+      if (models.some((model) => model?.id === modelId)) {
+        ids.push(modelId);
+      }
     }
   }
   return [...new Set(ids)].slice(0, GUIDE_ASPECT_RATIO_PROBE_LIMIT);
@@ -2939,7 +2973,69 @@ function createGuidePricingForModel(model, modelParameters, context = {}) {
   if (createGuideCanPriceModelParameters(model)) {
     return createGuideXaiImagePricing(model, modelParameters, context);
   }
-  return createGuideModelCreditPricing(model);
+  return (
+    createGuideAspectRatioCreditPricing(model, context) ??
+    createGuideModelCreditPricing(model)
+  );
+}
+
+// The debit `create` will actually make at the ratio the guide is about to
+// emit, read from the model registry (#2259).
+//
+// `economics.credit_pricing` is the quote at the model's own default shape --
+// no aspect ratio, no policy model-parameter defaults. `create` never sends
+// that request: it always sends a concrete ratio (`1:1` unless the brief asked
+// otherwise) plus the hosted defaults. For any model priced from its output
+// shape or from a defaulted parameter the quote is therefore not the debit, and
+// 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
+  // the full catalog) nests it. Reading only the nested one is how a fix passes
+  // its own test against a payload production never sends.
+  const byAspectRatio = isRecord(
+    model?.economics?.create_credit_debit_by_aspect_ratio,
+  )
+    ? model.economics.create_credit_debit_by_aspect_ratio
+    : model?.create_credit_debit_by_aspect_ratio;
+  const aspectRatio = context?.aspectRatio;
+  if (!isRecord(byAspectRatio) || typeof aspectRatio !== "string") {
+    return null;
+  }
+  const credits = byAspectRatio[aspectRatio];
+  if (!Number.isFinite(credits)) {
+    return null;
+  }
+  const quoted = createGuideModelCreditPricing(model);
+  return {
+    ...(quoted ?? {}),
+    credits_required: credits,
+    credit_unit_usd: CREDIT_UNIT_USD,
+    estimated_charge_usd: roundUsd(credits * CREDIT_UNIT_USD),
+    pricing_confidence: quoted?.pricing_confidence ?? "known",
+  };
 }
 
 function createGuideCanPriceModelParameters(model) {
@@ -3017,6 +3113,43 @@ function roundUsdMicro(value) {
   return Math.round(value * 1_000_000) / 1_000_000;
 }
 
+// ---------------------------------------------------------------------------
+// How the guide reads a model field. Read this before adding an accessor.
+//
+// There is NO normalizer. `createGuide` hands the rows from `GET /v1/models`
+// to these accessors verbatim -- `withModelSummary` is the `models list`
+// command's compactor and never runs on this path. So an accessor here has to
+// cope with BOTH published shapes itself:
+//
+//   GET /v1/models      (compact list)   flat: model_execution_status,
+//                                        credits_required, estimated_usd_per_image,
+//                                        max_outputs_per_request, artifact_storage.
+//                                        NO `media`, `execution`, or `economics`.
+//   GET /v1/models/:id  (detail)         nested under execution/economics/media.
+//
+// The convention is therefore NESTED-OR-FLAT: try the detail shape, fall back
+// to the flat field the list actually publishes. That convention is the whole
+// safety property, and #2265 was one accessor quietly breaking it.
+// `createGuideSelectedModelRequiresInputImage` read
+// `media.input.images.required` with a "fallback" of `accepts_input_images` --
+// a field the API has never published -- so against a real list row it had no
+// fallback at all, and it failed closed.
+//
+//   guideModelExecutionStatus       execution.model_execution_status  -> flat
+//   createGuideModelCreditPricing   economics.credit_pricing          -> flat
+//   guideBudgetUsdForModel          economics.estimated_usd_per_image -> flat
+//   guideModelAspectRatioValues     media.input.aspect_ratios.values  -> none;
+//                                   fails open and is hydrated from the detail
+//                                   endpoint on demand (see the note there)
+//   ...SelectedModelRequiresInputImage  reads `supports`, published on the list
+//
+// `max_outputs_per_request` and `artifact_storage` are published flat as well,
+// but nothing on the guide path reads them. Their only nested reads live in
+// `modelSummaryRow`/`modelSummaryTaskTags`, which `withModelSummary` skips
+// outright for a payload already marked `compact_model_summary` -- which the
+// hosted list is. Those eight `media.*` reads therefore never see a list row.
+// ---------------------------------------------------------------------------
+
 function guideModelExecutionStatus(model) {
   if (
     isRecord(model?.execution) &&
@@ -3133,6 +3266,26 @@ function requestedAspectRatioFromBrief(input) {
 // say. The hosted `/v1/models` list is a compact summary and omits the `media`
 // block entirely, so "not published" is the common case here and must be kept
 // distinct from "published and does not include this ratio".
+//
+// #2265, worth stating because the next reader will assume otherwise: this is
+// ONE OF EXACTLY TWO `media.*` reads that run over the LIST payload, and the
+// two behave OPPOSITELY. `GET /v1/models/:id` does publish `media`; the compact
+// list does not. So a `media.*` read is only safe here if it either fails open
+// or arranges to be hydrated from the detail endpoint first.
+//
+//   - This one FAILS OPEN. Unknown never disqualifies a model, so an unhydrated
+//     read costs a hint, not a decision. That is why capability routing kept
+//     working in production while `edit --guide` was dead.
+//   - `createGuideSelectedModelRequiresInputImage` used to FAIL CLOSED: no
+//     `media` meant no model could prove it accepts an input image, so `edit
+//     --guide` selected nothing on every real call. It no longer reads `media`
+//     at all -- see the note there.
+//
+// Failing open is not the same as being correct. `guideModelSuggestedAspectRatio`
+// consumes this to REPORT a value rather than to gate one, so before the probe
+// was extended to video picks it published `suggested_aspect_ratio: null` on
+// every video brief that did not state a ratio -- silently, since no blocker
+// fires. Fail-open degrades quietly; that is its failure mode, not its absence.
 function guideModelAspectRatioValues(model) {
   const values = Array.isArray(model?.media?.input?.aspect_ratios?.values)
     ? model.media.input.aspect_ratios.values
@@ -3197,10 +3350,31 @@ function createGuideSuggestedAspectRatio(input) {
   return values.includes("16:9") ? "16:9" : (values[0] ?? null);
 }
 
+// #2265: this must decide from what the hosted payload actually publishes.
+// `GET /v1/models` returns the compact summary, which omits the `media` block
+// entirely (and has never published `accepts_input_images`), so gating on
+// `media.input.images.required` disqualified every model on every real call and
+// `edit --guide` could not select one, ever.
+//
+// This read FAILED CLOSED, which is why it was catastrophic rather than merely
+// lossy: an absent field could not prove any model accepts an input image, so
+// the guide selected nothing and reported `no_executable_model`. The other
+// list-payload `media.*` read (`guideModelAspectRatioValues`) fails open and
+// only loses a hint. Do not assume the two are interchangeable -- see the note
+// there before adding a third.
+//
+// `supports` is published and carries the same fact: it is derived from the
+// capability's operations (`image.edit` -> "edit", `image.variation` ->
+// "variation"), and both are input-image operations by construction. On the
+// live 220-model catalog the old conjunction and this predicate select the
+// identical 79 models, so the dropped conjunct was doing no work -- while
+// costing the mirror the ability to decide at all.
+//
+// Keep this reading only summary fields. `src/` holds strictly more model data
+// than the mirror can ever see; every extra field the guide reads there is a
+// fresh chance for the two surfaces to decide differently.
 function createGuideSelectedModelRequiresInputImage(model) {
   return (
-    (model?.media?.input?.images?.required === true ||
-      model?.accepts_input_images === true) &&
     Array.isArray(model?.supports) &&
     (model.supports.includes("edit") || model.supports.includes("variation"))
   );
@@ -3891,12 +4065,16 @@ function createGuideBlocker(stage, input) {
     };
   }
   if (stage === "no_executable_model") {
+    // #2265: name the operation that actually failed. Saying "create" when the
+    // caller ran `edit --guide` made the one diagnostic an agent gets point at
+    // the wrong half of the product.
+    const operation = input.operation === "edit" ? "edit" : "create";
     return {
       code: "no_executable_model",
       message:
         input.requestedModelId === null
-          ? "No available executable create model was found in the public registry."
-          : `Requested model is not currently an available executable create model: ${input.requestedModelId}`,
+          ? `No available executable ${operation} model was found in the public registry.`
+          : `Requested model is not currently an available executable ${operation} model: ${input.requestedModelId}`,
     };
   }
   if (stage === "auth_required") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxin-cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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,