luxin-cli 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -6,6 +6,94 @@ provenance; this file is the human- and agent-readable release map.
 
 ## Unreleased
 
+## 0.2.3 - 2026-08-04
+
+- Release (self-fund/recovery): the wall now offers a human-funding handoff
+  instead of only a rail no external agent could walk (#2201). Both wall types
+  — credits depleted and daily job cap reached — route through
+  `QUOTA_EXCEEDED`, and the recovery envelope now carries
+  `error.recovery.human_handoff`: a copy-runnable `luxin claim code --json`,
+  typed `no_spend`, with the honest instruction to hand `data.dashboard_url`
+  (and nothing else — never the token, never the raw code) to your human, who
+  funds credits at the dashboard in about a minute. With no wallet evidence —
+  the external default — that handoff leads `error.recovery.suggested_command`
+  and `error.recovery.suggested_commands`; the agent-native x402 quote/buy rail
+  stays listed and `top_up.preferred_payment_method`
+  (`stripe_x402.exact.usdc`) is unchanged. New `error.recovery.delegated_spend`
+  (`state`, `per_tx_cap_usd`, `agent_day_remaining_usd`, `requires_wallet`)
+  lets an agent tell whether it can settle x402 itself before it stops at the
+  wall; it defaults to `state: "unknown"`, and when a caller proves delegated
+  spend is available the x402 quote leads instead. The credits-depleted wall
+  message — the majority wall — now names the price (a ~$5 top-up of 500
+  credits, pack `starter-500`), the concrete next step, and both paths, at the
+  quality the daily-cap message already had. The packaged CLI rewrites the
+  handoff command through your invocation prefix, so what the wall prints is
+  runnable as printed.
+- Release (honest messaging): the `create --guide` / `edit --guide`
+  `quota_required` blocker is now trigger-aware (#2200). It used to always emit
+  the credits-shortfall line ("Selected first image requires N credits; current
+  remaining credits are M") even when the trigger was the daily job cap, so an
+  agent holding spare credits read a message that was simply wrong about why it
+  was blocked. The blocker now mirrors the stage's credit-first ordering:
+  credits only outrank the daily cap when they are genuinely short, and
+  otherwise the message names the real trigger — "You've reached today's job
+  allowance (X/day); a top-up raises your daily allowance so you can keep
+  creating now" — matching the hosted daily-cap copy.
+- Release (no-spend mode): `create --guide` and `edit --guide` accept an opt-in
+  `--no-spend` output mode (#2194). A cold-agent no-spend study got a guide
+  response that repeatedly embedded live create, quote, buy, and payment
+  command templates, which buried the safe dry-run and raised the chance of
+  picking a prohibited action. With `--no-spend`,
+  `data.no_spend_output_mode.enabled` is `true` and the live funding templates
+  are omitted — `data.self_fund_next_command`,
+  `data.self_fund_next_command_label`, `data.self_fund_handoff`,
+  `data.self_fund_preparation`, and `data.checks.payments.suggested_commands`,
+  each named in `data.no_spend_output_mode.suppressed_fields`. The dry-run
+  command (`data.recommended_no_spend_command` / `data.no_spend_next_command`)
+  and the `provider_call` / `credit_debit` / `media_write` false proof in
+  `data.mutation` are retained. The funding path stays discoverable without
+  dominating via `data.no_spend_output_mode.self_fund_discovery`:
+  `rerun_with_funding_command` re-runs the same guide without `--no-spend`, and
+  `inspect_methods_command` is a read-only, no-spend payment-method
+  inspection. `--no-spend` is a guide output mode: outside `--guide` it is
+  rejected with the pointer to `create --dry-run` for a no-spend planned job.
+  `luxin create --help` and the packaged `cli.md` / `commands.json` carry the
+  flag.
+- Release (trust/billing): a completed, charged job always surfaces an asset
+  (#2107). A live create/edit reserves credit before calling the provider and
+  settles on the provider's success envelope — but a provider that answered
+  SUCCESS with an empty or planned-only asset list used to settle the
+  reservation and commit a charged, asset-less job, so the agent was billed for
+  nothing and had no recoverable job or asset. The runner now requires at least
+  one real (non-planned) asset before settling: otherwise it releases the
+  reserved credit and returns a retryable `PROVIDER_COMPLETED_WITHOUT_ASSET`
+  failure instead of committing the charge. Nothing to change on your side —
+  the debit-without-media outcome is gone.
+- Release (guide reliability): the `create --guide` executable-default read is
+  guarded against the shape the hosted registry actually returns (#2109).
+  `GET /v1/models` serves the compact model-summary rows, which carry
+  `model_execution_status` as a flat field rather than nested under
+  `execution`; a nested-only read failed every row's executable check and
+  dead-ended the guide at `no_executable_model` even though an executable
+  default existed and an explicit `create --dry-run --model fal.bagel` still
+  planned for zero credits. The flat-reading fix shipped earlier, but every
+  guide fixture used the nested shape, so a regression would have passed CI.
+  This release adds a faithful regression test serving the compact/flat shape
+  and asserting `ready_to_create` with the executable default selected.
+- Resolved (0.2.2 known limitation): the `dashboard.claim` grant backfill
+  landed (#2184), so `luxin claim code` no longer answers `CAPABILITY_DENIED`
+  for agents whose tokens predate the hosted dashboard plane. That matters more
+  now that the wall itself recommends the command.
+- Release (hosted parity): the Stripe reconciliation sweep is rail-aware and
+  transitions confirmed-unsettled pending attempts older than its abandonment
+  window to a terminal `expired` state with an audit trail (#2160). Settled
+  attempts are never abandoned and live-money retrieval failures still fail
+  loudly. No packaged CLI command changed for this; stale open quotes on your
+  account simply stop lingering as pending forever.
+- No payment caps, wallet settlement, provider spend, dist-tag mutation, or
+  media generation behavior changed in this release bump beyond the
+  debited-no-asset release path above, which only ever refunds.
+
 ## 0.2.2 - 2026-07-30
 
 - Release (retention/self-fund): publish the human handoff from #2181. New verb

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.2";
+const VERSION = "0.2.3";
 const PACKAGE_NAME = "luxin";
 const DEFAULT_API_BASE_URL = "https://api.luxin.sh";
 const DEFAULT_DOCS_BASE_URL = "https://luxin.sh";
@@ -552,6 +552,7 @@ function commandHelpByKey(key) {
       docs_url: "https://luxin.sh/cli.md#luxin-create",
       optional_flags: [
         "--guide",
+        "--no-spend",
         "--dry-run",
         "--model",
         "--aspect-ratio",
@@ -1984,13 +1985,66 @@ async function createGuide(args, options = {}) {
     paymentSummary,
     selfFundPreparation,
   );
+  // #2194: no-spend output mode. Omit the live self-fund and payment command
+  // templates when the agent opts into a no-spend/dry-run study so the safe
+  // dry-run is not buried under quote/buy/payment workflow commands. Retain the
+  // dry-run command and the mutation proof, and keep the self-fund path
+  // discoverable via self_fund_discovery instead of dominating the response.
+  const noSpendOutputMode = flagBool(args, "no-spend");
+  const paymentSummaryOutput = noSpendOutputMode
+    ? { ...paymentSummary, suggested_commands: [] }
+    : paymentSummary;
+  const selfFundHandoffOutput = noSpendOutputMode ? null : selfFundHandoff;
+  const selfFundPreparationOutput = noSpendOutputMode
+    ? null
+    : selfFundPreparation;
+  const selfFundNextCommandOutput = noSpendOutputMode
+    ? null
+    : selfFundNextCommand;
+  const selfFundNextCommandLabelOutput = noSpendOutputMode
+    ? null
+    : selfFundNextCommandLabel;
+  const noSpendOutputModeData = noSpendOutputMode
+    ? {
+        enabled: true,
+        suppressed_fields: [
+          "self_fund_next_command",
+          "self_fund_next_command_label",
+          "self_fund_handoff",
+          "self_fund_preparation",
+          "checks.payments.suggested_commands",
+        ],
+        self_fund_discovery: {
+          rerun_with_funding_command: renderGuideCommand(
+            trimmedPrompt.length > 0 ? trimmedPrompt : "PROMPT",
+            explicitApiBaseUrl(args),
+            guideCommandPrefix,
+            {
+              operation: guideOperation,
+              inputReference: options.inputReference,
+              modelId: requestedModelId,
+              providerId: requestedProviderId,
+              intent: requestedIntentFlag,
+              maxEstimatedUsdPerImage,
+              modelParametersJson: requestedModelParametersJson,
+            },
+          ),
+          inspect_methods_command: escapeHatches.payment_methods,
+          note: "No-spend output mode omits live self-fund and payment command templates. Re-run this guide without --no-spend to surface them; data.escape_hatches.payment_methods stays available for read-only, no-spend payment-method inspection. provider_call, credit_debit, and media_write remain false (see data.mutation).",
+        },
+      }
+    : {
+        enabled: false,
+        suppressed_fields: [],
+        self_fund_discovery: null,
+      };
   const guideRecovery = createGuideRecovery(stage, {
     blocker,
     nextCommand,
     noSpendNextCommand,
     afterNext,
     escapeHatches,
-    selfFundNextCommand,
+    selfFundNextCommand: selfFundNextCommandOutput,
   });
   return createGuideSuccess(command, quota?.envelope.actor ?? null, {
     schema:
@@ -2040,7 +2094,7 @@ async function createGuide(args, options = {}) {
               ? null
               : (quota.envelope.error?.code ?? "quota_unavailable"),
       },
-      payments: paymentSummary,
+      payments: paymentSummaryOutput,
     },
     selection:
       selected === null
@@ -2090,13 +2144,14 @@ async function createGuide(args, options = {}) {
     recommended_no_spend_command: noSpendNextCommand,
     recommended_no_spend_command_label: noSpendNextCommandLabel,
     recommended_no_spend_command_effect: noSpendNextCommandEffect,
-    self_fund_next_command: selfFundNextCommand,
-    self_fund_next_command_label: selfFundNextCommandLabel,
-    self_fund_handoff: selfFundHandoff,
-    self_fund_preparation: selfFundPreparation,
+    self_fund_next_command: selfFundNextCommandOutput,
+    self_fund_next_command_label: selfFundNextCommandLabelOutput,
+    self_fund_handoff: selfFundHandoffOutput,
+    self_fund_preparation: selfFundPreparationOutput,
     after_next: afterNext,
     auth_handoff: authHandoff,
     escape_hatches: escapeHatches,
+    no_spend_output_mode: noSpendOutputModeData,
     mutation: {
       provider_call: false,
       hosted_create: false,
@@ -3389,7 +3444,24 @@ function createGuideBlocker(stage, input) {
     };
   }
   if (stage === "quota_required") {
-    const remaining = quotaRemainingCredits(input.quota?.envelope.data ?? null);
+    const quotaData = input.quota?.envelope.data ?? null;
+    const remaining = quotaRemainingCredits(quotaData);
+    // Mirror createGuideStage's credit-first ordering: credits only outrank the
+    // daily-job cap when they are genuinely short. Agents that hold spare
+    // credits but hit the daily allowance (issues #2103, #2148) must be told the
+    // honest trigger, not a credits-shortfall line that reads as wrong to them
+    // (same confusion class as #1193).
+    const creditsShort =
+      input.estimatedCredits !== null &&
+      remaining !== null &&
+      remaining < input.estimatedCredits;
+    const dailyJobs = quotaData?.daily_jobs;
+    if (!creditsShort && dailyJobs !== undefined && dailyJobs.remaining <= 0) {
+      return {
+        code: "quota_required",
+        message: `You've reached today's job allowance (${dailyJobs.cap}/day); a top-up raises your daily allowance so you can keep creating now.`,
+      };
+    }
     return {
       code: "quota_required",
       message: `Selected first image requires ${input.estimatedCredits ?? "unknown"} credits; current remaining credits are ${remaining ?? "unknown"}.`,
@@ -4439,6 +4511,12 @@ async function create(argv) {
   if (flagBool(args, "guide")) {
     return createGuide(args);
   }
+  if (flagBool(args, "no-spend")) {
+    return invalid(
+      "luxin create",
+      "create --no-spend is a guide output mode; combine it with --guide, or use create --dry-run for a no-spend planned job",
+    );
+  }
   const prompt = await promptValue(args);
   if (!prompt.ok) {
     return prompt.result;
@@ -4586,6 +4664,12 @@ async function edit(argv) {
       inputReference: input,
     });
   }
+  if (flagBool(args, "no-spend")) {
+    return invalid(
+      "luxin edit",
+      "edit --no-spend is a guide output mode; combine it with --guide, or use edit --dry-run for a no-spend planned job",
+    );
+  }
   if (input === undefined) {
     return invalid(
       "luxin edit",
@@ -6967,6 +7051,16 @@ function quotaRecoveryWithCopyRunnableCommands(recovery, commandPrefix) {
           ),
         }
       : {}),
+    ...(recovery.human_handoff &&
+    typeof recovery.human_handoff === "object" &&
+    typeof recovery.human_handoff.command === "string"
+      ? {
+          human_handoff: {
+            ...recovery.human_handoff,
+            command: render(recovery.human_handoff.command),
+          },
+        }
+      : {}),
     top_up: quotaTopUpWithCopyRunnableCommands(recovery.top_up, commandPrefix),
   };
 }

package/cli.md

@@ -355,6 +355,26 @@ step.
   `data.auth_handoff.next_command.with_env` or
   `data.auth_handoff.next_command.with_stdin` so auth follows the create.
 
+For a no-spend or dry-run study, add `--no-spend` to `create --guide` for a
+compact output mode. `data.no_spend_output_mode.enabled` is then `true` and the
+live self-fund and payment command templates are omitted:
+`data.self_fund_next_command`, `data.self_fund_next_command_label`,
+`data.self_fund_handoff`, `data.self_fund_preparation`, and
+`data.checks.payments.suggested_commands` are suppressed (each is listed in
+`data.no_spend_output_mode.suppressed_fields`), so the safe dry-run is not
+buried under quote/buy/payment workflow commands. The response still centers on
+the dry-run command (`data.recommended_no_spend_command`, aliased by
+`data.no_spend_next_command`), and the provider-call, credit-debit, and
+media-write false proof in `data.mutation` is retained. The self-fund path
+stays discoverable without dominating via
+`data.no_spend_output_mode.self_fund_discovery`: its
+`rerun_with_funding_command` re-runs the guide without `--no-spend` to surface
+the funding templates, and `inspect_methods_command` is a read-only, no-spend
+payment-method inspection (the same command as
+`data.escape_hatches.payment_methods`). `--no-spend` is a guide output mode; it
+requires `--guide`, and for a no-spend planned job outside the guide use
+`create --dry-run`.
+
 Manual escape hatches are not prerequisites. Use them only when
 `data.next_command` / `data.escape_hatches` asks, or when the task genuinely
 needs deeper capability, quota, payment, or planning detail:

package/commands.json

@@ -421,6 +421,7 @@
         "docs_url": "https://luxin.sh/cli.md#luxin-create",
         "optional_flags": [
           "--guide",
+          "--no-spend",
           "--dry-run",
           "--model",
           "--aspect-ratio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxin-cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Zero-setup durable creative-media CLI for agents (image + video + audio + 3D): guide-first creation, model and cost inspection, owned URLs, JSON recovery, payments, reusable assets, and feedback. Luxin is a creative-media runtime, unrelated to the luxon datetime library.",
   "type": "module",
   "private": false,

package/skills/luxin/references/cli.md

@@ -355,6 +355,26 @@ step.
   `data.auth_handoff.next_command.with_env` or
   `data.auth_handoff.next_command.with_stdin` so auth follows the create.
 
+For a no-spend or dry-run study, add `--no-spend` to `create --guide` for a
+compact output mode. `data.no_spend_output_mode.enabled` is then `true` and the
+live self-fund and payment command templates are omitted:
+`data.self_fund_next_command`, `data.self_fund_next_command_label`,
+`data.self_fund_handoff`, `data.self_fund_preparation`, and
+`data.checks.payments.suggested_commands` are suppressed (each is listed in
+`data.no_spend_output_mode.suppressed_fields`), so the safe dry-run is not
+buried under quote/buy/payment workflow commands. The response still centers on
+the dry-run command (`data.recommended_no_spend_command`, aliased by
+`data.no_spend_next_command`), and the provider-call, credit-debit, and
+media-write false proof in `data.mutation` is retained. The self-fund path
+stays discoverable without dominating via
+`data.no_spend_output_mode.self_fund_discovery`: its
+`rerun_with_funding_command` re-runs the guide without `--no-spend` to surface
+the funding templates, and `inspect_methods_command` is a read-only, no-spend
+payment-method inspection (the same command as
+`data.escape_hatches.payment_methods`). `--no-spend` is a guide output mode; it
+requires `--guide`, and for a no-spend planned job outside the guide use
+`create --dry-run`.
+
 Manual escape hatches are not prerequisites. Use them only when
 `data.next_command` / `data.escape_hatches` asks, or when the task genuinely
 needs deeper capability, quota, payment, or planning detail:

package/skills/luxin/references/commands.json

@@ -421,6 +421,7 @@
         "docs_url": "https://luxin.sh/cli.md#luxin-create",
         "optional_flags": [
           "--guide",
+          "--no-spend",
           "--dry-run",
           "--model",
           "--aspect-ratio",