image-skill 0.1.60 → 0.1.62

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.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.
+  `credits status --quote-id ...` now repeats the exact
+  `data.next_actions.recommended_buy` command for open x402/Checkout quotes,
+  and Stripe x402 buy/status responses expose
+  `data.next_actions.recommended_settlement` with exact payable-instruction
+  paths, status/quota commands, and wallet-settlement safety flags.
+
 ## 0.1.60 - 2026-06-17
 
 - Release (activation/self-fund): add `credits quote --json`

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.60";
+const VERSION = "0.1.62";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -1296,7 +1296,10 @@ async function credits(argv) {
         idempotency_key: idempotency.value,
       },
     });
-    return withStripeCheckoutCopyFallback(result);
+    return withCopyRunnablePaymentNextActionCommands(
+      withStripeCheckoutCopyFallback(result),
+      createGuideCommandPrefix(),
+    );
   }
   if (subcommand === "status") {
     const args = parseArgs(rest);
@@ -1316,7 +1319,10 @@ async function credits(argv) {
       path: `/v1/credit-purchases/status?${query.toString()}`,
       token: token.token,
     });
-    return withStripeCheckoutCopyFallback(result);
+    return withCopyRunnablePaymentNextActionCommands(
+      withStripeCheckoutCopyFallback(result),
+      createGuideCommandPrefix(),
+    );
   }
   return invalid(
     "image-skill credits",
@@ -1740,16 +1746,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;
@@ -2781,6 +2793,115 @@ function withCopyRunnableCreditQuoteCommands(result, commandPrefix) {
   };
 }
 
+function withCopyRunnablePaymentNextActionCommands(result, commandPrefix) {
+  const data = result.envelope.data;
+  if (
+    !result.envelope.ok ||
+    data === null ||
+    typeof data !== "object" ||
+    Array.isArray(data)
+  ) {
+    return result;
+  }
+  const updated = paymentNextActionsWithCopyRunnableCommands(
+    data,
+    commandPrefix,
+  );
+  if (updated === data) {
+    return result;
+  }
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      data: updated,
+    },
+  };
+}
+
+function paymentNextActionsWithCopyRunnableCommands(data, commandPrefix) {
+  if (
+    data.next_actions === null ||
+    typeof data.next_actions !== "object" ||
+    Array.isArray(data.next_actions)
+  ) {
+    return data;
+  }
+  let changed = false;
+  const nextActions = { ...data.next_actions };
+
+  if (
+    nextActions.recommended_buy !== null &&
+    typeof nextActions.recommended_buy === "object" &&
+    !Array.isArray(nextActions.recommended_buy)
+  ) {
+    const recommendedBuy = { ...nextActions.recommended_buy };
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "buy_command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "status_command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "status_command_after_payment",
+        commandPrefix,
+      ) || changed;
+    nextActions.recommended_buy = recommendedBuy;
+  }
+
+  if (
+    nextActions.recommended_settlement !== null &&
+    typeof nextActions.recommended_settlement === "object" &&
+    !Array.isArray(nextActions.recommended_settlement)
+  ) {
+    const recommendedSettlement = { ...nextActions.recommended_settlement };
+    changed =
+      renderPaymentActionCommandField(
+        recommendedSettlement,
+        "status_command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedSettlement,
+        "quota_command",
+        commandPrefix,
+      ) || changed;
+    nextActions.recommended_settlement = recommendedSettlement;
+  }
+
+  return changed ? { ...data, next_actions: nextActions } : data;
+}
+
+function renderPaymentActionCommandField(record, field, commandPrefix) {
+  if (typeof record[field] !== "string") {
+    return false;
+  }
+  const rendered = renderCopyRunnablePaymentCommand(
+    commandPrefix,
+    record[field],
+  );
+  if (rendered === record[field]) {
+    return false;
+  }
+  record[field] = rendered;
+  return true;
+}
+
 function creditQuoteWithCopyRunnableCommands(quote, commandPrefix) {
   const recommendedBuy =
     quote.next_actions?.recommended_buy !== null &&
@@ -6226,7 +6347,10 @@ function withCommand(result, command) {
   };
 }
 
-function withQuotaNextActions(result) {
+function withQuotaNextActions(
+  result,
+  commandPrefix = createGuideCommandPrefix(),
+) {
   const data = result.envelope?.data;
   if (
     result.envelope?.ok !== true ||
@@ -6235,22 +6359,84 @@ 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 quotaTopUpNextActions(topUp) {
   const commands = topUp?.commands;
   if (

package/cli.md

@@ -665,6 +665,12 @@ Use `data.next_actions.recommended_buy.status_command` to inspect the quote or
 payment state by `quote_id`; after buy returns a `payment_attempt_id`, prefer
 `status_command_after_payment`.
 
+When `credits status --quote-id quote_... --json` sees an open
+`stripe_x402.exact.usdc` or `stripe_checkout` quote, it repeats the exact
+`data.next_actions.recommended_buy` command with the real `quote_id` and
+`purchase:quote_...` idempotency key so agents do not need to reconstruct the
+buy step from placeholders.
+
 Hosted API equivalent:
 
 ```bash
@@ -743,6 +749,22 @@ Minimum x402 action-required data:
       "client_secret": "[redacted-stripe-client-secret]"
     }
   },
+  "next_actions": {
+    "recommended_settlement": {
+      "purpose": "settle_stripe_x402_credit_top_up",
+      "quote_id": "quote_...",
+      "payment_attempt_id": "payatt_...",
+      "method_id": "stripe_x402.exact.usdc",
+      "payable_instructions_path": "data.stripe_x402.payable_instructions",
+      "status_command": "image-skill credits status --payment-attempt-id payatt_... --json",
+      "quota_command": "image-skill usage quota --json",
+      "command_effect": {
+        "wallet_settlement": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
   "next": {
     "agent_action": "pay_stripe_crypto_deposit",
     "suggested_commands": [
@@ -842,6 +864,12 @@ At most one reference flag is allowed: `--quote-id`,
 `--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`. Passing no
 reference returns the balance/quota state.
 
+For Stripe x402 attempts that are still `action_required`, status responses
+include `data.next_actions.recommended_settlement` with the same exact Base/USDC
+payable instructions, a copy-runnable status command for the real
+`payment_attempt_id`, and explicit effect flags showing this is wallet
+settlement, not credit debit, media write, or provider generation work.
+
 Minimum action-required data:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "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,

package/skills/image-skill/references/cli.md

@@ -665,6 +665,12 @@ Use `data.next_actions.recommended_buy.status_command` to inspect the quote or
 payment state by `quote_id`; after buy returns a `payment_attempt_id`, prefer
 `status_command_after_payment`.
 
+When `credits status --quote-id quote_... --json` sees an open
+`stripe_x402.exact.usdc` or `stripe_checkout` quote, it repeats the exact
+`data.next_actions.recommended_buy` command with the real `quote_id` and
+`purchase:quote_...` idempotency key so agents do not need to reconstruct the
+buy step from placeholders.
+
 Hosted API equivalent:
 
 ```bash
@@ -743,6 +749,22 @@ Minimum x402 action-required data:
       "client_secret": "[redacted-stripe-client-secret]"
     }
   },
+  "next_actions": {
+    "recommended_settlement": {
+      "purpose": "settle_stripe_x402_credit_top_up",
+      "quote_id": "quote_...",
+      "payment_attempt_id": "payatt_...",
+      "method_id": "stripe_x402.exact.usdc",
+      "payable_instructions_path": "data.stripe_x402.payable_instructions",
+      "status_command": "image-skill credits status --payment-attempt-id payatt_... --json",
+      "quota_command": "image-skill usage quota --json",
+      "command_effect": {
+        "wallet_settlement": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
   "next": {
     "agent_action": "pay_stripe_crypto_deposit",
     "suggested_commands": [
@@ -842,6 +864,12 @@ At most one reference flag is allowed: `--quote-id`,
 `--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`. Passing no
 reference returns the balance/quota state.
 
+For Stripe x402 attempts that are still `action_required`, status responses
+include `data.next_actions.recommended_settlement` with the same exact Base/USDC
+payable instructions, a copy-runnable status command for the real
+`payment_attempt_id`, and explicit effect flags showing this is wallet
+settlement, not credit debit, media write, or provider generation work.
+
 Minimum action-required data:
 
 ```json