image-skill 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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.17 - 2026-06-01
+
+- Money integrity: `create` and `edit` now send `--idempotency-key` to the
+  server so a retry of a transiently-failed generation REPLAYS the original
+  job instead of charging again. `create --guide` bakes a generated key into
+  its suggested command, and a proxy-killed 502 (`HOSTED_API_NON_JSON_RESPONSE`)
+  now returns a recovery block with the request's idempotency key so the
+  advertised retry is charge-safe. (0.1.16 parsed the flag but did not send it
+  on create, so same-key retries still double-charged against the live server's
+  dedup; this build closes that end-to-end.)
+
 ## 0.1.16 - 2026-06-01
 
 - `credits buy` now accepts `--provider stripe_x402` to execute the agent-native

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.16";
+const VERSION = "0.1.17";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -1197,6 +1197,10 @@ function createGuideNextCommand(stage, input) {
     intent: input.requestedIntent,
     budgetGuard: input.budgetGuard,
     dryRun: false,
+    // Retry-safe by default (#1228): bake a stable idempotency key into the
+    // advertised create command so an agent that copies it and retries after a
+    // transient 502 does not double-charge.
+    idempotencyKey: `create-guide-${Date.now()}-${randomBytes(4).toString("hex")}`,
     apiBaseUrl: input.apiBaseUrl,
     commandPrefix: input.commandPrefix,
   });
@@ -1228,6 +1232,9 @@ function renderCreateCommand(input) {
     shellQuote(input.intent),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.idempotencyKey === undefined || input.idempotencyKey === null
+      ? []
+      : ["--idempotency-key", shellQuote(input.idempotencyKey)]),
     ...(input.apiBaseUrl === null
       ? []
       : ["--api-base-url", shellQuote(input.apiBaseUrl)]),
@@ -1353,6 +1360,11 @@ async function create(argv) {
       ...(modelParameters.value === null
         ? {}
         : { model_parameters: modelParameters.value }),
+      // Retry-safe dedupe (#1228): when provided, a retry with the same key does
+      // not double-charge after a transient 502 that already debited a credit.
+      ...(flagString(args, "idempotency-key") === null
+        ? {}
+        : { idempotency_key: flagString(args, "idempotency-key") }),
       dry_run: flagBool(args, "dry-run"),
       accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
     },
@@ -1459,6 +1471,11 @@ async function edit(argv) {
       ...(modelParameters.value === null
         ? {}
         : { model_parameters: modelParameters.value }),
+      // Retry-safe dedupe (#1228): see create — same key dedupes a retry that
+      // follows a transient 502 which already debited a credit.
+      ...(flagString(args, "idempotency-key") === null
+        ? {}
+        : { idempotency_key: flagString(args, "idempotency-key") }),
       accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
     },
   });
@@ -2556,7 +2573,9 @@ async function apiRequest(input) {
       body: input.body === undefined ? undefined : JSON.stringify(input.body),
     });
     const text = await response.text();
-    const envelope = parseEnvelope(text, input.command, response.status);
+    const envelope = parseEnvelope(text, input.command, response.status, {
+      requestBody: input.body,
+    });
     const exitCodeHeader = response.headers.get("x-image-skill-exit-code");
     return {
       exitCode:
@@ -2583,7 +2602,7 @@ async function apiRequest(input) {
   }
 }
 
-function parseEnvelope(text, command, statusCode) {
+function parseEnvelope(text, command, statusCode, options = {}) {
   try {
     const parsed = JSON.parse(text);
     if (parsed && typeof parsed === "object" && "ok" in parsed) {
@@ -2592,21 +2611,62 @@ function parseEnvelope(text, command, statusCode) {
   } catch {
     // Fall through to normalized public error.
   }
+  const retryable = statusCode >= 500;
+  // Money integrity (#1228): a proxy-killed 502 returns a non-JSON body, so the
+  // server's own recovery guidance never reaches the agent. For a retryable
+  // create/edit (which may already have debited a credit) synthesize an
+  // idempotency-keyed retry command so the advertised retry dedupes to one
+  // charge instead of double-charging. Echo the request's key when present;
+  // otherwise mint a stable key so the NEXT retry is safe.
+  const recovery =
+    retryable && isCreateOrEditCommand(command)
+      ? nonJsonRetryRecovery(command, options.requestBody)
+      : undefined;
   return {
     ok: false,
     command,
     trace_id: traceId(),
     actor: null,
     data: null,
-    warnings: [],
+    warnings: retryable
+      ? [
+          "the hosted API may have already reserved a credit; retry with the returned idempotency_key so the retry is not double-charged",
+        ]
+      : [],
     error: {
       code: "HOSTED_API_NON_JSON_RESPONSE",
       message: `hosted API returned HTTP ${statusCode} without a JSON envelope`,
-      retryable: statusCode >= 500,
+      retryable,
+      ...(recovery === undefined ? {} : { recovery }),
     },
   };
 }
 
+function isCreateOrEditCommand(command) {
+  return command === "image-skill create" || command === "image-skill edit";
+}
+
+function nonJsonRetryRecovery(command, requestBody) {
+  const operation = command === "image-skill edit" ? "edit" : "create";
+  const existingKey =
+    requestBody &&
+    typeof requestBody === "object" &&
+    typeof requestBody.idempotency_key === "string"
+      ? requestBody.idempotency_key
+      : null;
+  const idempotencyKey =
+    existingKey ??
+    `${operation}-retry-${Date.now()}-${randomBytes(4).toString("hex")}`;
+  const anchor =
+    operation === "edit" ? "image-skill-edit" : "image-skill-create";
+  return {
+    suggested_command: `${command} --idempotency-key ${idempotencyKey} --json`,
+    idempotency_key: idempotencyKey,
+    docs_url: `https://image-skill.com/cli.md#${anchor}`,
+    retry_after_seconds: 5,
+  };
+}
+
 function withStripeCheckoutCopyFallback(result) {
   const data = result.envelope.data;
   if (!isRecord(data)) {

package/cli.md

@@ -876,6 +876,21 @@ If provider generation succeeds but artifact storage fails, the command returns
 should not retry the whole create blindly, because that may duplicate paid
 provider spend.
 
+For retry-safe create automation, pass an explicit non-secret
+`--idempotency-key`. A retry that reuses the same key does not create a second
+credit reservation, so a transient `502`/`PROVIDER_FAILURE` that already
+reserved a credit cannot double-charge on retry. `create --guide` bakes a
+generated `--idempotency-key` into its advertised create `next_command`, and a
+retryable create error returns an `error.recovery.idempotency_key` plus an
+`error.recovery.suggested_command` that re-runs the same create with that key.
+
+```bash
+image-skill create \
+  --prompt "A compact field camera on a stainless workbench" \
+  --idempotency-key create-run-001 \
+  --json
+```
+
 Hosted free-preview API equivalent:
 
 ```bash
@@ -1074,6 +1089,12 @@ public UX. The public selection surface should be Image Skill capabilities and
 model-parameter schemas; provider/model details belong in explicit
 provenance/debug output.
 
+Edit accepts the same retry-safe `--idempotency-key` as create. A retry that
+reuses the same key does not create a second credit reservation, so a transient
+`502`/`PROVIDER_FAILURE` after a reservation cannot double-charge; a retryable
+edit error returns an `error.recovery.idempotency_key` and an
+`error.recovery.suggested_command` that re-runs the same edit with that key.
+
 ### `image-skill assets show`
 
 Inspects an Image Skill-owned asset URL or hosted asset id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Zero-setup durable creative-media CLI for agents (image + video): 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

@@ -876,6 +876,21 @@ If provider generation succeeds but artifact storage fails, the command returns
 should not retry the whole create blindly, because that may duplicate paid
 provider spend.
 
+For retry-safe create automation, pass an explicit non-secret
+`--idempotency-key`. A retry that reuses the same key does not create a second
+credit reservation, so a transient `502`/`PROVIDER_FAILURE` that already
+reserved a credit cannot double-charge on retry. `create --guide` bakes a
+generated `--idempotency-key` into its advertised create `next_command`, and a
+retryable create error returns an `error.recovery.idempotency_key` plus an
+`error.recovery.suggested_command` that re-runs the same create with that key.
+
+```bash
+image-skill create \
+  --prompt "A compact field camera on a stainless workbench" \
+  --idempotency-key create-run-001 \
+  --json
+```
+
 Hosted free-preview API equivalent:
 
 ```bash
@@ -1074,6 +1089,12 @@ public UX. The public selection surface should be Image Skill capabilities and
 model-parameter schemas; provider/model details belong in explicit
 provenance/debug output.
 
+Edit accepts the same retry-safe `--idempotency-key` as create. A retry that
+reuses the same key does not create a second credit reservation, so a transient
+`502`/`PROVIDER_FAILURE` after a reservation cannot double-charge; a retryable
+edit error returns an `error.recovery.idempotency_key` and an
+`error.recovery.suggested_command` that re-runs the same edit with that key.
+
 ### `image-skill assets show`
 
 Inspects an Image Skill-owned asset URL or hosted asset id.