image-skill 0.1.61 → 0.1.63

package/CHANGELOG.md

@@ -4,6 +4,24 @@ This changelog tracks the public `image-skill` CLI package and public skill
 mirror. The npm package metadata remains the authority for tarball integrity and
 provenance; this file is the human- and agent-readable release map.
 
+## 0.1.63 - 2026-06-17
+
+- Release (activation/self-fund): make quota/payment error recovery top-up
+  commands copy-runnable from ephemeral `npx image-skill@latest` runs. When
+  hosted create/edit or payment commands return `error.recovery.top_up`, the
+  public CLI now prefixes `suggested_command`, `suggested_commands`,
+  `top_up.first_command`, `top_up.quote_command`, nested `top_up.commands.*`,
+  and workflow step commands with the same zero-install handoff used by
+  `usage quota --json` and `create --guide`.
+
+## 0.1.62 - 2026-06-17
+
+- Release (activation/self-fund): make `usage quota --json` top-up handoffs
+  copy-runnable from ephemeral `npx image-skill@latest` runs. Quota
+  `top_up`, generated `next_actions.self_fund`, and create-guide embedded
+  quota top-up commands now carry the public handoff prefix instead of bare
+  `image-skill ...` commands.
+
 ## 0.1.61 - 2026-06-17
 
 - Release (activation/self-fund): add payment-attempt continuation actions.

package/bin/image-skill.mjs

@@ -15,7 +15,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.61";
+const VERSION = "0.1.63";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -1228,23 +1228,24 @@ async function credits(argv) {
       payment_method: paymentMethod,
       idempotency_key: idempotency.value,
     };
-    const result = await apiRequest({
-      command: "image-skill credits quote",
-      method: "POST",
-      apiBaseUrl: apiBase(args),
-      path: "/v1/credit-quotes",
-      token: token.token,
-      body,
-    });
+    const commandPrefix = createGuideCommandPrefix();
+    const result = withCopyRunnableQuotaRecoveryCommands(
+      await apiRequest({
+        command: "image-skill credits quote",
+        method: "POST",
+        apiBaseUrl: apiBase(args),
+        path: "/v1/credit-quotes",
+        token: token.token,
+        body,
+      }),
+      commandPrefix,
+    );
     if (idempotency.generated) {
       result.envelope.warnings.push(
         `generated idempotency key ${idempotency.value}; pass --idempotency-key for stable retries`,
       );
     }
-    return withCopyRunnableCreditQuoteCommands(
-      result,
-      createGuideCommandPrefix(),
-    );
+    return withCopyRunnableCreditQuoteCommands(result, commandPrefix);
   }
   if (subcommand === "buy") {
     const args = parseArgs(rest);
@@ -1285,20 +1286,24 @@ async function credits(argv) {
       provider === "stripe_x402"
         ? "/v1/credit-purchases/stripe-x402-deposits"
         : "/v1/credit-purchases/stripe-checkout-sessions";
-    const result = await apiRequest({
-      command: "image-skill credits buy",
-      method: "POST",
-      apiBaseUrl: apiBase(args),
-      path: purchasePath,
-      token: token.token,
-      body: {
-        quote_id: quoteId,
-        idempotency_key: idempotency.value,
-      },
-    });
+    const commandPrefix = createGuideCommandPrefix();
+    const result = withCopyRunnableQuotaRecoveryCommands(
+      await apiRequest({
+        command: "image-skill credits buy",
+        method: "POST",
+        apiBaseUrl: apiBase(args),
+        path: purchasePath,
+        token: token.token,
+        body: {
+          quote_id: quoteId,
+          idempotency_key: idempotency.value,
+        },
+      }),
+      commandPrefix,
+    );
     return withCopyRunnablePaymentNextActionCommands(
       withStripeCheckoutCopyFallback(result),
-      createGuideCommandPrefix(),
+      commandPrefix,
     );
   }
   if (subcommand === "status") {
@@ -1312,16 +1317,20 @@ async function credits(argv) {
     addQueryFlag(query, args, "payment-attempt-id", "payment_attempt_id");
     addQueryFlag(query, args, "checkout-session-id", "checkout_session_id");
     addQueryFlag(query, args, "receipt-id", "receipt_id");
-    const result = await apiRequest({
-      command: "image-skill credits status",
-      method: "GET",
-      apiBaseUrl: apiBase(args),
-      path: `/v1/credit-purchases/status?${query.toString()}`,
-      token: token.token,
-    });
+    const commandPrefix = createGuideCommandPrefix();
+    const result = withCopyRunnableQuotaRecoveryCommands(
+      await apiRequest({
+        command: "image-skill credits status",
+        method: "GET",
+        apiBaseUrl: apiBase(args),
+        path: `/v1/credit-purchases/status?${query.toString()}`,
+        token: token.token,
+      }),
+      commandPrefix,
+    );
     return withCopyRunnablePaymentNextActionCommands(
       withStripeCheckoutCopyFallback(result),
-      createGuideCommandPrefix(),
+      commandPrefix,
     );
   }
   return invalid(
@@ -1746,16 +1755,22 @@ async function createGuide(args, options = {}) {
     maxEstimatedUsdPerImage ??
     estimatedDebitUsdPerImage ??
     (estimatedCredits === null ? 0.07 : estimatedCredits / 100);
+  const quotaCommandPrefix = createGuideCommandPrefix({
+    configPath: configuredImageSkillConfigPath(),
+  });
   const quota =
     token.token === null
       ? null
-      : await apiRequest({
-          command: "image-skill create --guide",
-          method: "GET",
-          apiBaseUrl,
-          path: "/v1/quota",
-          token: token.token,
-        });
+      : withQuotaNextActions(
+          await apiRequest({
+            command: "image-skill create --guide",
+            method: "GET",
+            apiBaseUrl,
+            path: "/v1/quota",
+            token: token.token,
+          }),
+          quotaCommandPrefix,
+        );
   const authenticated = quota?.envelope.data?.authenticated === true;
   const publicTokenSource =
     token.source === "anonymous" ? "none" : token.source;
@@ -4042,48 +4057,51 @@ async function create(argv) {
         argv,
       })
     : null;
-  const result = await apiRequest({
-    command: "image-skill create",
-    method: "POST",
-    apiBaseUrl: apiBase(args),
-    path: "/v1/create",
-    ...(token.token === null ? {} : { token: token.token }),
-    body: {
-      prompt: prompt.value,
-      ...(flagString(args, "provider") === null
-        ? {}
-        : { provider: flagString(args, "provider") }),
-      ...(flagString(args, "model") === null
-        ? {}
-        : { model: flagString(args, "model") }),
-      ...(flagString(args, "intent") === null
-        ? {}
-        : { intent: flagString(args, "intent") }),
-      aspect_ratio: flagString(args, "aspect-ratio") ?? "1:1",
-      ...(references.references.length === 0
-        ? {}
-        : { references: references.references }),
-      ...(outputCount.value === null
-        ? {}
-        : { output_count: outputCount.value }),
-      ...(flagNumber(args, "max-estimated-usd-per-image") === null
-        ? {}
-        : {
-            max_estimated_usd_per_image: flagNumber(
-              args,
-              "max-estimated-usd-per-image",
-            ),
-          }),
-      ...(modelParameters.value === null
-        ? {}
-        : { model_parameters: modelParameters.value }),
-      // Retry-safe dedupe (#1228/#1789): a live create always carries a key so a
-      // retry (or an interrupted-then-recovered run) dedupes to one charge.
-      ...(idempotencyKey === null ? {} : { idempotency_key: idempotencyKey }),
-      dry_run: flagBool(args, "dry-run"),
-      accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
-    },
-  });
+  const result = withCopyRunnableQuotaRecoveryCommands(
+    await apiRequest({
+      command: "image-skill create",
+      method: "POST",
+      apiBaseUrl: apiBase(args),
+      path: "/v1/create",
+      ...(token.token === null ? {} : { token: token.token }),
+      body: {
+        prompt: prompt.value,
+        ...(flagString(args, "provider") === null
+          ? {}
+          : { provider: flagString(args, "provider") }),
+        ...(flagString(args, "model") === null
+          ? {}
+          : { model: flagString(args, "model") }),
+        ...(flagString(args, "intent") === null
+          ? {}
+          : { intent: flagString(args, "intent") }),
+        aspect_ratio: flagString(args, "aspect-ratio") ?? "1:1",
+        ...(references.references.length === 0
+          ? {}
+          : { references: references.references }),
+        ...(outputCount.value === null
+          ? {}
+          : { output_count: outputCount.value }),
+        ...(flagNumber(args, "max-estimated-usd-per-image") === null
+          ? {}
+          : {
+              max_estimated_usd_per_image: flagNumber(
+                args,
+                "max-estimated-usd-per-image",
+              ),
+            }),
+        ...(modelParameters.value === null
+          ? {}
+          : { model_parameters: modelParameters.value }),
+        // Retry-safe dedupe (#1228/#1789): a live create always carries a key so a
+        // retry (or an interrupted-then-recovered run) dedupes to one charge.
+        ...(idempotencyKey === null ? {} : { idempotency_key: idempotencyKey }),
+        dry_run: flagBool(args, "dry-run"),
+        accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
+      },
+    }),
+    createGuideCommandPrefix(),
+  );
   await clearInFlightSpendForResult(inFlight, result);
   return result;
 }
@@ -4176,45 +4194,48 @@ async function edit(argv) {
         argv,
       })
     : null;
-  const result = await apiRequest({
-    command: "image-skill edit",
-    method: "POST",
-    apiBaseUrl: apiBase(args),
-    path: "/v1/edit",
-    token: token.token,
-    body: {
-      input_asset_id: assetId.assetId,
-      ...(maskAssetId === null ? {} : { mask_asset_id: maskAssetId.assetId }),
-      ...(references.references.length === 0
-        ? {}
-        : { references: references.references }),
-      ...(prompt.value.length === 0 ? {} : { prompt: prompt.value }),
-      ...(flagString(args, "provider") === null
-        ? {}
-        : { provider: flagString(args, "provider") }),
-      ...(modelId === null ? {} : { model: modelId }),
-      ...(flagString(args, "intent") === null
-        ? {}
-        : { intent: flagString(args, "intent") }),
-      aspect_ratio: flagString(args, "aspect-ratio") ?? "auto",
-      ...(flagNumber(args, "max-estimated-usd-per-image") === null
-        ? {}
-        : {
-            max_estimated_usd_per_image: flagNumber(
-              args,
-              "max-estimated-usd-per-image",
-            ),
-          }),
-      ...(modelParameters.value === null
-        ? {}
-        : { model_parameters: modelParameters.value }),
-      ...(flagBool(args, "dry-run") ? { dry_run: true } : {}),
-      // Retry-safe dedupe (#1228/#1789): a live edit always carries a key so a
-      // retry (or an interrupted-then-recovered run) dedupes to one charge.
-      ...(idempotencyKey === null ? {} : { idempotency_key: idempotencyKey }),
-      accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
-    },
-  });
+  const result = withCopyRunnableQuotaRecoveryCommands(
+    await apiRequest({
+      command: "image-skill edit",
+      method: "POST",
+      apiBaseUrl: apiBase(args),
+      path: "/v1/edit",
+      token: token.token,
+      body: {
+        input_asset_id: assetId.assetId,
+        ...(maskAssetId === null ? {} : { mask_asset_id: maskAssetId.assetId }),
+        ...(references.references.length === 0
+          ? {}
+          : { references: references.references }),
+        ...(prompt.value.length === 0 ? {} : { prompt: prompt.value }),
+        ...(flagString(args, "provider") === null
+          ? {}
+          : { provider: flagString(args, "provider") }),
+        ...(modelId === null ? {} : { model: modelId }),
+        ...(flagString(args, "intent") === null
+          ? {}
+          : { intent: flagString(args, "intent") }),
+        aspect_ratio: flagString(args, "aspect-ratio") ?? "auto",
+        ...(flagNumber(args, "max-estimated-usd-per-image") === null
+          ? {}
+          : {
+              max_estimated_usd_per_image: flagNumber(
+                args,
+                "max-estimated-usd-per-image",
+              ),
+            }),
+        ...(modelParameters.value === null
+          ? {}
+          : { model_parameters: modelParameters.value }),
+        ...(flagBool(args, "dry-run") ? { dry_run: true } : {}),
+        // Retry-safe dedupe (#1228/#1789): a live edit always carries a key so a
+        // retry (or an interrupted-then-recovered run) dedupes to one charge.
+        ...(idempotencyKey === null ? {} : { idempotency_key: idempotencyKey }),
+        accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
+      },
+    }),
+    createGuideCommandPrefix(),
+  );
   await clearInFlightSpendForResult(inFlight, result);
   return result;
 }
@@ -6341,7 +6362,10 @@ function withCommand(result, command) {
   };
 }
 
-function withQuotaNextActions(result) {
+function withQuotaNextActions(
+  result,
+  commandPrefix = createGuideCommandPrefix(),
+) {
   const data = result.envelope?.data;
   if (
     result.envelope?.ok !== true ||
@@ -6350,22 +6374,132 @@ function withQuotaNextActions(result) {
   ) {
     return result;
   }
-  const nextActions = quotaTopUpNextActions(data.top_up);
+  const quotaData = quotaDataWithCopyRunnableTopUpCommands(data, commandPrefix);
+  const nextActions = quotaTopUpNextActions(quotaData.top_up);
   if (nextActions === null) {
-    return result;
+    return quotaData === data
+      ? result
+      : {
+          ...result,
+          envelope: {
+            ...result.envelope,
+            data: quotaData,
+          },
+        };
   }
   return {
     ...result,
     envelope: {
       ...result.envelope,
       data: {
-        ...data,
+        ...quotaData,
         next_actions: nextActions,
       },
     },
   };
 }
 
+function quotaDataWithCopyRunnableTopUpCommands(data, commandPrefix) {
+  if (data.top_up === undefined || data.top_up === null) {
+    return data;
+  }
+  const topUp = quotaTopUpWithCopyRunnableCommands(data.top_up, commandPrefix);
+  return topUp === data.top_up ? data : { ...data, top_up: topUp };
+}
+
+function quotaTopUpWithCopyRunnableCommands(topUp, commandPrefix) {
+  const commands = topUp.commands;
+  const workflow = topUp.workflow;
+  if (topUp === null || typeof topUp !== "object") {
+    return topUp;
+  }
+  const render = (command) =>
+    renderCopyRunnablePaymentCommand(commandPrefix, command);
+  const renderIfString = (value) =>
+    typeof value === "string" ? render(value) : value;
+  return {
+    ...topUp,
+    first_command: renderIfString(topUp.first_command),
+    quote_command: renderIfString(topUp.quote_command),
+    commands:
+      commands !== null && typeof commands === "object"
+        ? {
+            ...commands,
+            inspect_methods: renderIfString(commands.inspect_methods),
+            inspect_packs: renderIfString(commands.inspect_packs),
+            quote: renderIfString(commands.quote),
+            buy: renderIfString(commands.buy),
+            status: renderIfString(commands.status),
+            fallback_quote: renderIfString(commands.fallback_quote),
+            fallback_buy: renderIfString(commands.fallback_buy),
+          }
+        : commands,
+    workflow:
+      workflow !== null &&
+      typeof workflow === "object" &&
+      Array.isArray(workflow.steps)
+        ? {
+            ...workflow,
+            steps: workflow.steps.map((step) =>
+              step !== null &&
+              typeof step === "object" &&
+              typeof step.command === "string"
+                ? { ...step, command: render(step.command) }
+                : step,
+            ),
+          }
+        : workflow,
+  };
+}
+
+function withCopyRunnableQuotaRecoveryCommands(
+  result,
+  commandPrefix = createGuideCommandPrefix(),
+) {
+  const recovery = result.envelope?.error?.recovery;
+  if (
+    result.envelope?.ok === true ||
+    recovery === null ||
+    typeof recovery !== "object" ||
+    recovery.top_up === undefined ||
+    recovery.top_up === null
+  ) {
+    return result;
+  }
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      error: {
+        ...result.envelope.error,
+        recovery: quotaRecoveryWithCopyRunnableCommands(
+          recovery,
+          commandPrefix,
+        ),
+      },
+    },
+  };
+}
+
+function quotaRecoveryWithCopyRunnableCommands(recovery, commandPrefix) {
+  const render = (command) =>
+    renderCopyRunnablePaymentCommand(commandPrefix, command);
+  return {
+    ...recovery,
+    ...(typeof recovery.suggested_command === "string"
+      ? { suggested_command: render(recovery.suggested_command) }
+      : {}),
+    ...(Array.isArray(recovery.suggested_commands)
+      ? {
+          suggested_commands: recovery.suggested_commands.map((command) =>
+            typeof command === "string" ? render(command) : command,
+          ),
+        }
+      : {}),
+    top_up: quotaTopUpWithCopyRunnableCommands(recovery.top_up, commandPrefix),
+  };
+}
+
 function quotaTopUpNextActions(topUp) {
   const commands = topUp?.commands;
   if (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "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.",
   "type": "module",
   "private": false,