image-skill 0.1.4 → 0.1.6

package/README.md

@@ -16,7 +16,7 @@ Install the executable CLI from npm:
 ```bash
 npm install -g image-skill
 image-skill doctor --json
-image-skill signup --agent --human-email CONTACT_OR_SPONSOR_EMAIL --agent-name creative-agent --runtime openclaw --save --json
+image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name creative-agent --runtime openclaw --save --json
 image-skill credits methods --json
 image-skill credits packs list --json
 image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key first-topup-001 --json
@@ -24,6 +24,8 @@ image-skill credits buy --provider stripe --quote-id quote_... --idempotency-key
 image-skill create --prompt "A tiny studio robot painting a postcard" --model xai.grok-imagine-image --accept-unknown-cost --json
 ```
 
+The public CLI supports Node.js 20 and newer.
+
 Agent-facing contracts:
 
 - [skills/image-skill/SKILL.md](./skills/image-skill/SKILL.md)

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.4";
+const VERSION = "0.1.6";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_CONFIG_PATH = join(
   process.env.XDG_CONFIG_HOME ?? join(os.homedir(), ".config"),
@@ -15,9 +15,9 @@ const DEFAULT_CONFIG_PATH = join(
   "config.json",
 );
 const SIGNUP_SUGGESTED_COMMAND =
-  "image-skill signup --agent --human-email CONTACT_OR_SPONSOR_EMAIL --agent-name NAME --runtime RUNTIME --save --json";
+  "image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name NAME --runtime RUNTIME --save --json";
 const SIGNUP_CONTACT_GUIDANCE =
-  "Use --human-email for the accountable contact or sponsor inbox for this restricted agent identity. If no individual human is in the loop, use a durable operator/team/agent inbox that can receive future claim, billing, or abuse notices; do not invent a person or use a throwaway inbox.";
+  "Use --agent-contact for the accountable contact, sponsor, operator, or agent inbox for this restricted agent identity. If no individual human is in the loop, use a durable operator/team/agent inbox that can receive future claim, billing, or abuse notices; do not invent a person or use a throwaway inbox. --human-email remains a compatibility alias.";
 
 const argv = process.argv.slice(2);
 const result = await main(argv);
@@ -39,7 +39,7 @@ async function main(rawArgv) {
       docs_url: "https://image-skill.com/cli.md",
       commands: [
         "doctor",
-        "signup --agent --save",
+        "signup --agent --agent-contact --save",
         "auth status",
         "auth save",
         "auth logout",
@@ -173,18 +173,35 @@ async function signup(argv) {
   if (!flagBool(args, "agent")) {
     return invalid("image-skill signup", "signup currently requires --agent");
   }
-  const humanEmail = flagString(args, "human-email");
+  const contact = signupContact(args);
   const agentName = flagString(args, "agent-name");
   const runtime = flagString(args, "runtime");
-  if (humanEmail === null || agentName === null || runtime === null) {
+  if (!contact.ok) {
+    return failure(
+      "image-skill signup",
+      2,
+      "INVALID_ARGUMENTS",
+      contact.message,
+      false,
+      {
+        required_flags: ["--agent-contact", "--agent-name", "--runtime"],
+        suggested_command: SIGNUP_SUGGESTED_COMMAND,
+        docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
+      },
+    );
+  }
+  if (contact.value === null || agentName === null || runtime === null) {
     return failure(
       "image-skill signup",
       2,
       "INVALID_ARGUMENTS",
-      `signup requires --human-email, --agent-name, and --runtime. ${SIGNUP_CONTACT_GUIDANCE}`,
+      `signup requires --agent-contact, --agent-name, and --runtime. ${SIGNUP_CONTACT_GUIDANCE}`,
       false,
       {
-        required_flags: ["--human-email", "--agent-name", "--runtime"],
+        required_flags: ["--agent-contact", "--agent-name", "--runtime"],
+        accepted_aliases: {
+          "--human-email": "--agent-contact",
+        },
         suggested_command: SIGNUP_SUGGESTED_COMMAND,
         docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
       },
@@ -198,7 +215,7 @@ async function signup(argv) {
     apiBaseUrl: apiBase(args),
     path: "/v1/agent-signups",
     body: {
-      human_email: humanEmail,
+      human_email: contact.value,
       agent_name: agentName,
       runtime,
       return_token: save || showToken,
@@ -1280,6 +1297,49 @@ function flagBool(args, name) {
   return args.flags.has(name) && args.flags.get(name)?.at(-1) !== "false";
 }
 
+function signupContact(args) {
+  if (
+    args.flags.has("agent-contact") &&
+    flagString(args, "agent-contact") === null
+  ) {
+    return {
+      ok: false,
+      value: null,
+      message: "agent-contact requires a value",
+    };
+  }
+  if (
+    args.flags.has("human-email") &&
+    flagString(args, "human-email") === null
+  ) {
+    return {
+      ok: false,
+      value: null,
+      message: "human-email requires a value",
+    };
+  }
+  const agentContact = flagString(args, "agent-contact");
+  const humanEmail = flagString(args, "human-email");
+  if (agentContact !== null && humanEmail !== null) {
+    const normalizedAgentContact = agentContact.trim().toLowerCase();
+    const normalizedHumanEmail = humanEmail.trim().toLowerCase();
+    if (normalizedAgentContact !== normalizedHumanEmail) {
+      return {
+        ok: false,
+        value: null,
+        message:
+          "signup received both --agent-contact and --human-email with different values; use one durable contact inbox",
+      };
+    }
+    return { ok: true, value: normalizedAgentContact };
+  }
+  const value = agentContact ?? humanEmail;
+  return {
+    ok: true,
+    value: value === null ? null : value.trim().toLowerCase(),
+  };
+}
+
 function flagNumber(args, name) {
   const value = flagString(args, name);
   if (value === null) {

package/cli.md

@@ -54,7 +54,7 @@ Bootstraps restricted agent access.
 
 ```bash
 image-skill signup --agent \
-  --human-email human@example.com \
+  --agent-contact agent-ops@example.com \
   --agent-name creative-agent \
   --runtime codex \
   --save \
@@ -66,13 +66,14 @@ permissions and redacts it from stdout. Use `--show-token` only when the agent
 runtime has a separate secret store and needs the raw token once. Do not paste
 tokens into prompts, logs, issue text, or feedback.
 
-In this preview contract, `--human-email` is the accountable contact or sponsor
-inbox for the restricted agent identity. If no individual human is in the loop,
-use a durable operator/team/agent inbox that can receive future claim, billing,
-or abuse notices. Do not invent a person or use a throwaway inbox.
+In this preview contract, `--agent-contact` is the accountable contact,
+sponsor, operator, or agent inbox for the restricted agent identity. If no
+individual human is in the loop, use a durable operator/team/agent inbox that
+can receive future claim, billing, or abuse notices. Do not invent a person or
+use a throwaway inbox.
 `example.invalid` addresses are only appropriate inside documented harness or
-proof runs. Agent-contact-backed signup is planned, but the currently published
-CLI uses `--human-email`.
+proof runs. `--human-email` remains accepted as a compatibility alias for
+`--agent-contact`.
 
 For shell-based agent runtimes, store the token outside prompts and then expose
 it as:
@@ -235,6 +236,11 @@ image-skill credits quote \
   --json
 ```
 
+Idempotency keys are scoped to the current hosted agent identity and exact
+quote request. Reusing a key with different credits, pack, or payment method
+returns a structured `error.recovery.suggested_command` with a fresh
+idempotency key for the attempted quote terms.
+
 For Stripe Checkout terms, prefer a named pack:
 
 ```bash

package/llms.txt

@@ -44,7 +44,7 @@ Claim states:
 
 First-run flow:
 1. image-skill doctor --json
-2. image-skill signup --agent --human-email EMAIL --agent-name NAME --runtime RUNTIME --save --json. The preview hosted signup path currently requires human_email as the accountable contact or sponsor inbox for the restricted agent identity. If no individual human is in the loop, use a durable operator/team/agent inbox that can receive future claim, billing, or abuse notices; do not invent a person or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. Future payment-backed and agent-contact-backed signup paths are planned. Use --show-token only when the runtime has a separate secret store and needs the raw token once.
+2. image-skill signup --agent --agent-contact EMAIL --agent-name NAME --runtime RUNTIME --save --json. The preview hosted signup path uses --agent-contact as the accountable contact, sponsor, operator, or agent inbox for the restricted agent identity. If no individual human is in the loop, use a durable operator/team/agent inbox that can receive future claim, billing, or abuse notices; do not invent a person or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias. Use --show-token only when the runtime has a separate secret store and needs the raw token once.
 3. Reuse the saved CLI auth for later commands, or store the returned data.token from --show-token in the agent runtime secret store and expose it as IMAGE_SKILL_TOKEN.
 4. image-skill whoami --json
 5. image-skill usage quota --json
@@ -67,7 +67,7 @@ First-run flow:
 
 Core commands:
 - image-skill doctor --json
-- image-skill signup --agent --human-email EMAIL --agent-name NAME --runtime RUNTIME --save --json
+- image-skill signup --agent --agent-contact EMAIL --agent-name NAME --runtime RUNTIME --save --json
 - image-skill whoami --json
 - image-skill usage quota --json
 - image-skill quota --json (compatibility alias)
@@ -98,7 +98,7 @@ Core commands:
 - image-skill feedback create --type TYPE --title TITLE --body BODY --command COMMAND --expected EXPECTED --actual ACTUAL --proof-needed PROOF --surface cli,docs --evidence trace:TRACE_ID --severity medium --confidence high --next-state watch --json
 
 Hosted API endpoints:
-- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. Request human_email is the preview contact/sponsor inbox, not a requirement that an autonomous agent stop until a specific human is present. The response returns the token once as data.token. Store it in the agent runtime secret store; never put it in prompts, logs, issue text, or feedback.
+- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. Raw API request human_email is the compatibility contact field; CLI agents should prefer --agent-contact. The contact is not a requirement that an autonomous agent stop until a specific human is present. The response returns the token once as data.token. Store it in the agent runtime secret store; never put it in prompts, logs, issue text, or feedback.
 - GET https://api.image-skill.com/v1/whoami returns durable hosted identity for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/quota returns durable hosted quota for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/payment-methods returns the no-auth payment rail catalog. It tells agents which rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, limits, endpoint paths, and recovery commands.
@@ -181,7 +181,7 @@ Unclaimed agents may not:
 - send card data, wallet secrets, provider receipts, Stripe secrets, MPP tokens, SPTs, or any payment credential to Image Skill; Stripe payment details must be entered only on Stripe-hosted checkout pages
 
 Credits:
-One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability and whether a browser/human action is required. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --json for exact bounded custom top-ups when the required budget is already known. The default payment_method is fake. Use image-skill credits buy --provider stripe --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_url and does not grant credits. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Use image-skill credits fake-purchase --json only to exercise the quote, receipt, credit-ledger, and activity-audit contract before live settlement rails are enabled. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Credits buy and fake-purchase require explicit --idempotency-key. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
+One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability and whether a browser/human action is required. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --json for exact bounded custom top-ups when the required budget is already known. The default payment_method is fake. Use image-skill credits buy --provider stripe --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_url and does not grant credits. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Use image-skill credits fake-purchase --json only to exercise the quote, receipt, credit-ledger, and activity-audit contract before live settlement rails are enabled. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Credits buy and fake-purchase require explicit --idempotency-key. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; use per-run/per-step quote keys and inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
 
 Telemetry:
 - command or endpoint name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Thin hosted CLI for Image Skill, a creative runtime for agents.",
   "type": "module",
   "private": false,
@@ -20,7 +20,7 @@
     "cli.md"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"

package/skill.md

@@ -51,7 +51,7 @@ Bootstrap restricted agent access:
 
 ```bash
 image-skill signup --agent \
-  --human-email HUMAN_EMAIL \
+  --agent-contact CONTACT_OR_SPONSOR_INBOX \
   --agent-name AGENT_NAME \
   --runtime RUNTIME_NAME \
   --save \
@@ -62,13 +62,14 @@ image-skill signup --agent \
 permissions and redacts it from stdout. Use `--show-token` only when the agent
 runtime has a separate secret store and needs the raw token once.
 
-In the preview contract, `--human-email` means the accountable contact or
-sponsor inbox for the restricted agent identity. If no individual human is in
-the loop, use a durable operator/team/agent inbox that can receive future claim,
-billing, or abuse notices. Do not invent a person or use a throwaway inbox.
+In the preview contract, `--agent-contact` means the accountable contact,
+sponsor, operator, or agent inbox for the restricted agent identity. If no
+individual human is in the loop, use a durable operator/team/agent inbox that
+can receive future claim, billing, or abuse notices. Do not invent a person or
+use a throwaway inbox.
 `example.invalid` addresses are only appropriate inside documented harness or
-proof runs. Agent-contact-backed signup is planned, but the currently published
-CLI uses `--human-email`.
+proof runs. `--human-email` remains accepted as a compatibility alias for
+`--agent-contact`.
 
 If the runtime supports stdin secret handoff, prefer `--token-stdin` for
 `whoami`, `usage quota`, `quota`, `create`, and `feedback create` instead of
@@ -81,10 +82,10 @@ image-skill whoami --json
 image-skill usage quota --json
 ```
 
-The preview hosted signup path currently uses the contact/sponsor email field
-above. Future payment-backed and agent-contact-backed signup paths are planned
-so capable agents can become bounded paying users without making human claim the
-only path to meaningful usage.
+The preview hosted signup path currently uses the agent-contact inbox above.
+Future payment-backed signup paths are planned so capable agents can become
+bounded paying users without making human claim the only path to meaningful
+usage.
 
 Credit quote and buy flow: