@itpay/cli 0.1.9 → 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);
@@ -3850,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);
   }
@@ -3868,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);
@@ -4209,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);
   }
@@ -4559,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.9",
+  "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