@itpay/cli 0.1.1 → 0.1.2

package/bin/itp

@@ -838,6 +838,7 @@ async function buyer(command, rest, flags) {
     if (subcommand === "grants") {
       const action = rest[1] && !String(rest[1]).startsWith("--") ? rest[1] : "list";
       if (action === "list") {
+        await ensureBuyerSessionForVaultAccess(flags);
         const grants = await listBuyerAgentReadGrants(flags);
         output(buyerRunOutput({
           status: "agent_read_grants",
@@ -849,6 +850,7 @@ async function buyer(command, rest, flags) {
       if (action === "read" || action === "show") {
         const grantID = flags.grant || flags.grant_id || flags.agent_read_grant_id || positional(rest, 2);
         if (!grantID) throw new Error("agent_read_grant_id is required");
+        await ensureBuyerSessionForVaultAccess(flags);
         const view = await readBuyerAgentReadGrant(grantID, flags);
         output(buyerRunOutput({
           status: "agent_read_grant_view",
@@ -859,6 +861,7 @@ async function buyer(command, rest, flags) {
       }
     }
     if (subcommand === "read") {
+      await ensureBuyerSessionForVaultAccess(flags);
       const view = await readBuyerVaultArtifactGrant(flags);
       output(buyerRunOutput({
         status: "agent_read_grant_view",
@@ -1325,6 +1328,35 @@ async function maybeClaimBuyerSessionForCheckout(checkout, flags = {}) {
   return await maybeClaimBuyerSessionFromAuthAction(action, flags);
 }
 
+async function ensureBuyerSessionForVaultAccess(flags = {}) {
+  if (readSessionToken()) return null;
+  const checkoutID =
+    flags.checkout ||
+    flags.checkout_id ||
+    readState().last_core_checkout_id ||
+    readState().last_core_auth_checkout_id;
+  if (checkoutID) {
+    try {
+      const checkout = await getBuyerCheckout(checkoutID, flags);
+      rememberCoreAuthAction(checkout.checkout_id || checkoutID, checkout.human_action);
+      const claimed = await maybeClaimBuyerSessionForCheckout(checkout, { ...flags, quiet: true });
+      if (claimed || readSessionToken()) return claimed;
+    } catch {
+      // Continue with the locally remembered auth action below.
+    }
+    const action = readCoreAuthAction(checkoutID);
+    const claimed = await maybeClaimBuyerSessionFromAuthAction(action, { ...flags, quiet: true });
+    if (claimed || readSessionToken()) return claimed;
+  }
+  const state = readState();
+  const entries = Object.entries(state.core_auth_actions || {});
+  for (const [, action] of entries.reverse()) {
+    const claimed = await maybeClaimBuyerSessionFromAuthAction(action, { ...flags, quiet: true });
+    if (claimed || readSessionToken()) return claimed;
+  }
+  return null;
+}
+
 function parseBuyerAuthActionURL(action) {
   const rawURL = action?.url || action?.auth_url || "";
   if (!rawURL) return {};

package/docs/agent/buyer/human-claim-ui.json

@@ -30,12 +30,13 @@
     "The claim link is short-lived and single-use.",
     "The agent may explain that ItPay intentionally separates agent operations from raw secret access.",
     "If the human wants the agent to analyze or use the delivered result, ask them to click 'Give to Agent / 一键给 Agent' in the ItPay page and confirm with Passkey.",
-    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list ...`; do not ask the human to paste the grant id.",
+    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list --checkout <checkout_id> --json`; do not ask the human to paste the grant id. The CLI restores the buyer agent session from the checkout auth handoff when possible.",
     "If the human later wants the agent to install or use something, wait for an explicit human-granted install/capability flow."
   ],
   "forbidden": [
     "Do not ask the human to paste the claim link or key into chat.",
     "Do not fetch the claim page with CLI, curl, browser automation, or an agent tool.",
+    "Do not ask the human for auth session IDs, display tokens, buyer session tokens, or portal tokens.",
     "Do not store raw content in local run files."
   ],
   "next_docs": [

package/docs/agent/buyer/vault-agent-read.json

@@ -10,7 +10,7 @@
     "A checkout/order has delivered a vault artifact and the human granted agent-readable access."
   ],
   "required_state": {
-    "needs": ["authenticated buyer account session", "current agent device binding", "order_id or checkout_id or vault_artifact_id"],
+    "needs": ["checkout_id or authenticated buyer account session", "current agent device binding", "order_id or checkout_id or vault_artifact_id"],
     "must_not_need": ["human portal token", "claim token", "passkey credential", "raw protected payload", "grant id copied by the human"]
   },
   "commands": [
@@ -37,14 +37,16 @@
   ],
   "agent_rules": [
     "Only read through `buyer vault` commands after the human has explicitly approved the agent grant in the ItPay portal.",
+    "Prefer `itp buyer vault grants list --checkout <checkout_id> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
     "Do not ask the human to copy or paste `agent_read_grant_id`; discover it with `buyer vault grants list`.",
     "If no grant is returned, tell the human to open their ItPay account portal, reveal with Passkey, choose fields, and confirm one-key agent authorization.",
     "Use only fields returned in the grant view. Do not infer that unreturned fields are accessible.",
-    "If the command returns 401 or buyer_session_invalid, run `itp buyer auth status --json` and ask the human to reauthorize through a normal checkout/account flow."
+    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
   ],
   "forbidden": [
+    "Do not open, click through, scrape, or automate the human web UI yourself.",
     "Do not open, scrape, or screenshot the human portal to obtain protected content.",
-    "Do not request passkey credentials, portal tokens, claim links, claim tokens, storage refs, provider AppCode, provider keys, or raw payloads.",
+    "Do not request passkey credentials, portal tokens, claim links, claim tokens, auth session IDs, display tokens, session tokens, storage refs, provider AppCode, provider keys, or raw payloads.",
     "Do not use another agent's grant id. Grants are scoped to the exact buyer account session and agent device.",
     "Do not cache selected fields beyond the task context unless the user explicitly asks you to create a local artifact."
   ],

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -126,9 +126,11 @@ registered name or run fuzzy search first.
    `delivery_claimable`, `check_email`, and `claim_link_sent`, but must not
    fetch or reveal protected content.
 11. If the human uses Passkey to authorize agent-readable vault access, do not
-    ask them to paste content, portal text, claim links, or grant IDs. Run
+    ask them to paste content, portal text, claim links, session tokens, auth
+    session IDs, display tokens, or grant IDs. Run
     `itp buyer vault grants list ...` and then `itp buyer vault read ...`.
-    Use only the fields returned by that command.
+    The CLI automatically restores the buyer agent session from the checkout
+    auth handoff when possible. Use only the fields returned by that command.
 12. If the user asks you to analyze, compare, summarize, install, or otherwise
     use a delivered result, you may ask them to open the ItPay claim/account
     page, click "Give to Agent / 一键给 Agent", choose fields, and confirm with
@@ -140,6 +142,10 @@ registered name or run fuzzy search first.
     broad keyword. For enterprise precise lookup, `company_name_or_credit_no`
     must be exact; otherwise warn the user that the query may waste the paid
     lookup.
+15. Do not operate ItPay by opening the human web UI yourself. Use the CLI for
+    catalog, cart, checkout, payment wait, delivery status, grant discovery,
+    and vault reads. Browser/UI pages are for the human to scan, pay, claim,
+    reveal, and approve.
 
 ## Docs Directory