@itpay/cli 0.1.8 → 0.1.10

package/README.md

@@ -155,7 +155,7 @@ from the current state.
 Before starting a new purchase, agents should inspect recoverable local state:
 
 ```bash
-itp status --json
+itp status --refresh --json
 ```
 
 If an unfinished run exists, continue it:
@@ -241,6 +241,15 @@ itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json
 Agents must not ask humans to paste claim links, claim tokens, raw API results,
 provider keys, or grant ids into chat.
 
+Order/account/refund commands require a server-verified buyer session, not a
+vault grant. If they fail with a buyer session error, run:
+
+```bash
+itp status --refresh --json
+```
+
+Then follow the returned `next.command`.
+
 ## Agent Skill And Docs
 
 Installed agents can read the buyer skill and docs graph at any time:

package/bin/itp

@@ -222,6 +222,7 @@ async function main() {
           "buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
           "account login-link --json",
           "status --json",
+          "status --refresh --json",
           "docs list --role buyer --json",
           "docs show quickstart --role buyer --json",
           "docs search <question> --role buyer --json",
@@ -1954,26 +1955,37 @@ async function agentStatus(flags) {
   if (!run) {
     const config = readConfig();
     const credentials = readCredentials();
-    let auth = { authenticated: Boolean(readSessionToken(credentials)), account_id: config.account_id || null, device_id: config.device_id || null };
-    if (auth.authenticated && flags.refresh) {
-      try {
-        auth = await api("/api/itp/auth/status", { method: "GET" }, flags);
-      } catch (error) {
-        auth = { authenticated: false, account_id: config.account_id || null, error: error.message };
-      }
-    }
-      output({
-        schema_version: "itp.agent.v1",
-        status: auth.authenticated ? "idle" : "unauthenticated",
+    const hasLocalSession = Boolean(readSessionToken(credentials));
+    const auth = flags.refresh
+      ? await refreshBuyerSessionForStatus(flags)
+      : {
+          authenticated: hasLocalSession,
+          session_verified: false,
+          account_id: config.account_id || null,
+          device_id: config.device_id || null,
+          auth_source: hasLocalSession ? "local_files_unverified" : "local_files"
+        };
+    output({
+      schema_version: "itp.agent.v1",
+      status: auth.authenticated
+        ? (auth.session_verified === false ? "local_session_unverified" : "idle")
+        : "unauthenticated",
       phase: auth.authenticated ? "idle" : "unauthenticated",
       authenticated: Boolean(auth.authenticated),
-        account_id: auth.account_id || null,
-        device_id: auth.device_id || null,
-        next: auth.authenticated
-          ? { type: "choose_credits_or_plan", command: cliCommand("plans", "--json"), safe_for_agent: true }
-          : { type: "start_auth", command: cliCommand("setup", "--plan", "credit-300", "--method", "alipay", "--json"), safe_for_agent: true },
-        secrets: { raw_key_included: false, session_token_included: false }
-      });
+      session_verified: auth.session_verified !== false,
+      auth_source: auth.auth_source,
+      account_id: auth.account_id || null,
+      device_id: auth.device_id || null,
+      next: nextActionForAuthStatus(auth, flags),
+      agent_next_actions: auth.authenticated && auth.session_verified !== false
+        ? ["search_catalog", "view_orders", "create_refund_if_needed", "list_agent_read_grants"]
+        : ["run_status_refresh", "start_human_auth_if_unauthenticated"],
+      note: auth.authenticated && auth.session_verified === false
+        ? "Local buyer session exists but the server has not verified it. Run the next.command before order/refund/account operations."
+        : undefined,
+      error: auth.error || undefined,
+      secrets: { raw_key_included: false, session_token_included: false }
+    });
     return;
   }
   const refreshed = flags.refresh ? await refreshRun(run, flags) : run;
@@ -1981,6 +1993,50 @@ async function agentStatus(flags) {
   output(agentRunResponse(refreshed));
 }
 
+async function refreshBuyerSessionForStatus(flags = {}) {
+  const config = readConfig();
+  const credentials = readCredentials();
+  if (!readSessionToken(credentials)) {
+    return {
+      authenticated: false,
+      session_verified: true,
+      account_id: config.account_id || null,
+      device_id: config.device_id || null,
+      auth_source: "core_no_session"
+    };
+  }
+  try {
+    const status = await coreApi("/v1/me/auth/status", { method: "GET" }, flags);
+    return {
+      authenticated: true,
+      session_verified: true,
+      account_id: status.buyer_account_id || config.account_id || null,
+      device_id: config.device_id || null,
+      account_status: status.account_status || null,
+      auth_source: "core"
+    };
+  } catch (error) {
+    return {
+      authenticated: false,
+      session_verified: true,
+      account_id: config.account_id || null,
+      device_id: config.device_id || null,
+      auth_source: "core",
+      error: safeErrorMessage(error)
+    };
+  }
+}
+
+function nextActionForAuthStatus(auth = {}, flags = {}) {
+  if (auth.authenticated && auth.session_verified === false) {
+    return { type: "verify_buyer_session", command: cliCommand("status", "--refresh", "--json"), safe_for_agent: true };
+  }
+  if (auth.authenticated) {
+    return { type: "buyer_ready", command: cliCommand("buyer", "auth", "status", "--json"), safe_for_agent: true };
+  }
+  return { type: "start_auth", command: cliCommand("setup", "--plan", "credit-300", "--method", "alipay", "--json"), safe_for_agent: true };
+}
+
 async function resume(flags) {
   const runId = flags.run_id || readState().current_run_id;
   const run = readRun(runId);
@@ -3422,6 +3478,15 @@ async function renderHumanAction(action, flags = {}) {
         return { rendered: false, mode: "json-local-qr", outputs: [localPath] };
       }
     }
+    if (!qrImageURL && shouldGenerateLocalQRFromActionURL(action, mode, flags)) {
+      const localPath = await prepareLocalQRFromActionURL(action, flags, mode !== "file" && !flags.qr_file && !process.env.ITP_QR_FILE);
+      if (localPath) {
+        attachAgentLocalQR(action, localPath);
+        annotateHumanActionPresentation(action, "");
+        persistHumanAction(action, flags);
+        return { rendered: false, mode: "json-local-url-qr", outputs: [localPath] };
+      }
+    }
     return { rendered: false, mode: flags.json ? "json" : mode };
   }
   const host = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
@@ -3435,9 +3500,18 @@ async function renderHumanAction(action, flags = {}) {
       persistHumanAction(action, flags);
       return { rendered: false, mode: localPath ? "agent-local-image-qr" : "agent-image-qr", host, outputs: [localPath || "preferred_qr_url"] };
     }
-    process.stderr.write(`No QR image available. Open payment URL: ${action.url}\n`);
+    if (shouldGenerateLocalQRFromActionURL(action, mode, flags)) {
+      const localPath = await prepareLocalQRFromActionURL(action, flags, true);
+      if (localPath) {
+        attachAgentLocalQR(action, localPath);
+        annotateHumanActionPresentation(action, "");
+        persistHumanAction(action, flags);
+        return { rendered: false, mode: "agent-local-url-qr", host, outputs: [localPath] };
+      }
+    }
+    process.stderr.write(`No QR image available. Open action URL: ${action.url}\n`);
     persistHumanAction(action, flags);
-    return { rendered: false, mode: "agent-url-fallback", host, outputs: ["payment_url"] };
+    return { rendered: false, mode: "agent-url-fallback", host, outputs: ["action_url"] };
   }
 
   const renderResult = { rendered: false, mode, outputs: [] };
@@ -3461,7 +3535,19 @@ async function renderHumanAction(action, flags = {}) {
       renderResult.outputs.push(file);
       if (mode === "file") return renderResult;
     } else {
-      process.stderr.write(`No QR image available. Open payment URL: ${action.url}\n`);
+      const localPath = shouldGenerateLocalQRFromActionURL(action, mode, flags)
+        ? await prepareLocalQRFromActionURL(action, flags, false)
+        : "";
+      if (localPath) {
+        attachAgentLocalQR(action, localPath);
+        annotateHumanActionPresentation(action, "");
+        process.stderr.write(`Alipay action QR image: ${localPath}\n`);
+        renderResult.rendered = true;
+        renderResult.outputs.push(localPath);
+        if (mode === "file") return renderResult;
+      } else {
+        process.stderr.write(`No QR image available. Open action URL: ${action.url}\n`);
+      }
     }
   }
 
@@ -3535,6 +3621,12 @@ function shouldPrepareLocalQRForJSON(mode, flags = {}, action = {}) {
   return false;
 }
 
+function shouldGenerateLocalQRFromActionURL(action = {}, mode = "", flags = {}) {
+  if (!action?.url) return false;
+  if (action.kind === "auth_qr") return true;
+  return mode === "file" || Boolean(flags.qr_file || process.env.ITP_QR_FILE);
+}
+
 async function prepareLocalQRFile(action, qrImageURL, flags = {}, optional = false) {
   if (!qrImageURL) return "";
   const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, qrImageURL);
@@ -3550,11 +3642,37 @@ async function prepareLocalQRFile(action, qrImageURL, flags = {}, optional = fal
   return file;
 }
 
+async function prepareLocalQRFromActionURL(action, flags = {}, optional = false) {
+  if (!action?.url) return "";
+  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultGeneratedQRFilePath(action);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    await QRCode.toFile(file, action.url, {
+      type: "png",
+      errorCorrectionLevel: "M",
+      margin: 2,
+      width: 512
+    });
+  } catch (error) {
+    if (!optional) throw error;
+    action.local_qr_error = safeErrorMessage(error);
+    return "";
+  }
+  action.local_qr_path = file;
+  action.local_qr_mime = "image/png";
+  return file;
+}
+
 function defaultQRFilePath(action, qrImageURL) {
   const id = sanitizeFilename(action?.payment_intent_id || action?.id || "qr");
   return path.join(os.tmpdir(), `itp-${id}.${qrFileExtension(qrImageURL, action)}`);
 }
 
+function defaultGeneratedQRFilePath(action) {
+  const id = sanitizeFilename(action?.payment_intent_id || action?.id || "qr");
+  return path.join(os.tmpdir(), `itp-${id}.png`);
+}
+
 function qrFileExtension(qrImageURL, action = {}) {
   const mime = qrMimeType(qrImageURL, action);
   if (mime === "image/png") return "png";
@@ -3620,6 +3738,22 @@ function attachAgentQRImage(action, qrImageURL, localPath = "") {
   return action;
 }
 
+function attachAgentLocalQR(action, localPath = "") {
+  if (!action || !localPath) return action;
+  if (!Array.isArray(action.display)) {
+    action.display = [];
+  }
+  if (!action.display.some((item) => item?.type === "image" && item?.local_path === localPath)) {
+    action.display.push({
+      type: "image",
+      format: "png",
+      local_path: localPath,
+      instructions: "Render this local QR image for the human to scan. It encodes the ItPay human action URL, not a provider raw QR payload."
+    });
+  }
+  return action;
+}
+
 async function downloadQRImage(qrImageURL, file, flags = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), apiTimeoutMs(flags));
@@ -3772,9 +3906,9 @@ async function coreApi(pathname, options = {}, flags = {}) {
     });
   } catch (error) {
     if (error?.name === "AbortError") {
-      throw new Error(`request timed out after ${Math.ceil(timeoutMs / 1000)}s: ${targetURL}`);
+      throw new Error(`request timed out after ${Math.ceil(timeoutMs / 1000)}s: ${safeRequestTarget(targetURL)}`);
     }
-    throw error;
+    throw new Error(`network request failed: ${safeRequestTarget(targetURL)}: ${safeErrorMessage(error)}`);
   } finally {
     clearTimeout(timer);
   }
@@ -3790,11 +3924,27 @@ async function coreApi(pathname, options = {}, flags = {}) {
   if (!response.ok || payload.success === false) {
     const error = new Error(payload.error || payload.message || `request failed: ${response.status}`);
     error.status = response.status;
+    if (response.status === 401 && String(pathname).startsWith("/v1/me/")) {
+      error.message = "buyer session required or expired; run status --refresh --json, then run setup --method alipay --json if unauthenticated";
+      error.next = [
+        { type: "verify_buyer_session", command: cliCommand("status", "--refresh", "--json"), safe_for_agent: true },
+        { type: "start_auth_if_needed", command: cliCommand("setup", "--method", "alipay", "--json"), safe_for_agent: true }
+      ];
+    }
     throw error;
   }
   return payload.data ?? payload;
 }
 
+function safeRequestTarget(target) {
+  try {
+    const url = new URL(String(target));
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return String(target).split("?")[0];
+  }
+}
+
 function coreAgentFingerprint(flags = {}) {
   const explicit = flags.agent_fingerprint || flags.agent_device_fingerprint || process.env.ITPAY_AGENT_FINGERPRINT || process.env.ITPAY_AGENT_DEVICE_FINGERPRINT;
   if (explicit) return String(explicit);
@@ -4131,7 +4281,12 @@ async function withStateLock(fn) {
     fd = fs.openSync(LOCK_PATH, "wx", 0o600);
     fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }));
   } catch {
-    throw new Error("another itp setup/status operation is running; retry shortly or remove stale ~/.itp/state.lock");
+    const error = new Error(`another itp setup/status operation is running; if no other ItPay CLI is active, remove the stale lock and retry: rm -f ${LOCK_PATH}`);
+    error.next = [
+      { type: "check_status", command: cliCommand("status", "--refresh", "--json"), safe_for_agent: true },
+      { type: "clear_stale_lock", command: `rm -f ${shellQuote(LOCK_PATH)}`, safe_for_agent: true }
+    ];
+    throw error;
   } finally {
     if (fd !== undefined) fs.closeSync(fd);
   }
@@ -4481,7 +4636,9 @@ function output(value) {
 }
 
 function outputError(error) {
-  console.error(JSON.stringify({ success: false, message: safeErrorMessage(error) }, null, 2));
+  const payload = { success: false, message: safeErrorMessage(error) };
+  if (error?.next) payload.next = error.next;
+  console.error(JSON.stringify(payload, null, 2));
 }
 
 function maskSecret(secret) {

package/docs/agent/buyer/quickstart.json

@@ -14,6 +14,11 @@
     "must_not_need": ["ops token", "claim token", "raw key", "provider raw payload"]
   },
   "commands": [
+    {
+      "intent": "verify whether this agent/device already has a server-valid buyer session",
+      "command": "itp status --refresh --json",
+      "success_signal": "response.status is idle when authenticated, or response.next.command tells the agent how to start human auth"
+    },
     {
       "intent": "list the available agent docs topics",
       "command": "itp docs list --role buyer --json",
@@ -37,6 +42,7 @@
   ],
   "agent_rules": [
     "Use --json for every ItPay command.",
+    "Use `itp status --refresh --json` before account, order, refund, or repeat-purchase decisions. Plain local memory is not identity.",
     "Search and explain options before buying unless the user already named a variant.",
     "Add the selected UCP Variant.id to cart; do not bypass cart for CORE-028 flows.",
     "When explaining prices, remember ItPay JSON money fields use minor units. For CNY, amount=10 means CNY 0.10. Prefer display_amount when present.",
@@ -45,6 +51,7 @@
     "For first purchase, show auth_qr as the ItPay first-purchase entry: the human first approves provider login/registration/profile sharing, then ItPay should continue the same checkout to payment.",
     "After showing auth_qr, keep running/resuming the same checkout unless the human explicitly asks you to pause. Do not stop merely because a QR was displayed.",
     "When a buyer command returns buyer_session.status=buyer_session_saved, the CLI has stored the buyer account session for this agent device. You may continue with checkout/payment or `buyer vault` commands without asking the human for a token.",
+    "Vault grants are only for reading approved delivered artifacts. They are not buyer session credentials and do not authorize refunds or account/order management.",
     "Use high-level itp buy when possible; it is designed to show the first-purchase entry, wait/resume, continue to payment, wait for verification, and poll delivery.",
     "Show the returned payment QR exactly as provided.",
     "Payment truth comes only from payment_intent.verified.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -23,6 +23,7 @@ protocol from this file. Use the CLI docs graph whenever you need details.
 Run these commands before buying:
 
 ```bash
+itp status --refresh --json
 itp docs show quickstart --role buyer --json
 itp docs list --role buyer --json
 ```
@@ -37,6 +38,7 @@ itp docs search "<what you need to know>" --role buyer --json
 
 ```text
 read this skill
+-> run status --refresh and follow next.command if unauthenticated
 -> read quickstart doc
 -> search catalog
 -> explain/recommend a variant
@@ -108,6 +110,9 @@ Refund commands use ItPay shared order state. If `itp buyer refund create`
 returns `policy_risk_confirmation_required`, explain the returned
 `refund_eligibility.policy` and `agent_guidance` to the human first. Only retry
 with `--confirm-policy-risk true` after explicit human confirmation.
+Refund commands require a server-verified buyer session, not a vault grant. If
+the CLI says the buyer session is required or expired, run
+`itp status --refresh --json` and follow the returned `next.command`.
 Current buyer refunds are whole-order only; do not use line-item refund scope.
 If the human cancels a refund before provider or money movement starts, use
 `buyer refund cancel <refund_id> --json`; after cancel, the delivery claim can