@piprail/sdk 1.14.0 → 1.15.0

package/dist/index.js

@@ -22,7 +22,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-H3A4KWLJ.js";
+} from "./chunk-ILPABTI2.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -1271,7 +1271,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-3TRYD4QB.js");
+      mod = await import("./solana-WDKWWF33.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -1283,7 +1283,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-QHGQLJX2.js");
+      mod = await import("./ton-CHJ26BVA.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -1295,7 +1295,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-IK3UML6O.js");
+      mod = await import("./stellar-FIJPQZVW.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -1307,7 +1307,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-2GZMDYW5.js");
+      mod = await import("./xrpl-GTUPP6SK.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -1319,7 +1319,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-2N2GA62O.js");
+      mod = await import("./tron-DD3JDROV.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -1331,7 +1331,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-VSE63WQM.js");
+      mod = await import("./sui-B7AVN7NK.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -1343,7 +1343,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-DT6LRIKB.js");
+      mod = await import("./near-LM7S3WUD.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -1355,7 +1355,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-CDEYDDM5.js");
+      mod = await import("./aptos-SUXOVP7B.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -1367,7 +1367,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-7EUZYL2Z.js");
+      mod = await import("./algorand-F3OYB534.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -1842,7 +1842,18 @@ function encodeBase642(str) {
 
 // src/policy.ts
 var ALLOW = { allowed: true };
-var deny = (reason) => ({ allowed: false, reason });
+var deny = (code, reason) => ({
+  allowed: false,
+  reason,
+  code
+});
+function resolveDeadline(policy, sessionStart) {
+  const fromTtl = policy.ttlSeconds != null && Number.isSafeInteger(sessionStart + policy.ttlSeconds * 1e3) ? sessionStart + policy.ttlSeconds * 1e3 : null;
+  const fromAbs = policy.expiresAt != null ? policy.expiresAt : null;
+  if (fromTtl == null) return fromAbs;
+  if (fromAbs == null) return fromTtl;
+  return Math.min(fromTtl, fromAbs);
+}
 function hostMatches(host, pattern) {
   if (pattern.startsWith("*.")) {
     const suffix = pattern.slice(1);
@@ -1858,18 +1869,26 @@ function chainMatches(intent, allowed) {
   const id = "id" in allowed ? allowed.id : void 0;
   return id !== void 0 && intent.network === `eip155:${id}`;
 }
-function evaluatePolicy(intent, policy, spentForAssetBase) {
+function evaluatePolicy(intent, policy, spentForAssetBase, ctx) {
   if (!policy) return ALLOW;
+  if (ctx) {
+    const deadline = resolveDeadline(policy, ctx.sessionStart);
+    if (deadline != null && ctx.now >= deadline) {
+      return deny("SESSION_EXPIRED", "session expired (TTL elapsed) \u2014 refusing to pay.");
+    }
+  }
   if (policy.chains && !policy.chains.some((c) => chainMatches(intent, c))) {
     return deny(
+      "CHAIN",
       `chain ${intent.network} is not in the allowed set (policy.chains).`
     );
   }
   if (policy.hosts && !policy.hosts.some((h) => hostMatches(intent.host, h))) {
-    return deny(`host ${intent.host} is not in the allowed set (policy.hosts).`);
+    return deny("HOST", `host ${intent.host} is not in the allowed set (policy.hosts).`);
   }
   if (!intent.recognized && !policy.allowUnknownTokens) {
     return deny(
+      "UNKNOWN_TOKEN",
       `asset ${intent.asset} on ${intent.network} isn't a token the SDK can price; refusing to pay it on trust. Set policy.allowUnknownTokens to override.`
     );
   }
@@ -1882,6 +1901,7 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
     });
     if (!matches) {
       return deny(
+        "TOKEN",
         `token ${intent.symbol ?? intent.asset} is not in the allowed set (policy.tokens).`
       );
     }
@@ -1890,6 +1910,7 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
     const cap = floorUnits(policy.maxAmount, intent.decimals);
     if (intent.amountBase > cap) {
       return deny(
+        "MAX_AMOUNT",
         `payment of ${intent.amountBase} base units exceeds policy.maxAmount ` + `(${policy.maxAmount} ${intent.symbol ?? ""}).`.trimEnd()
       );
     }
@@ -1898,10 +1919,20 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
     const cap = floorUnits(policy.maxTotal, intent.decimals);
     if (spentForAssetBase + intent.amountBase > cap) {
       return deny(
+        "MAX_TOTAL",
         `this payment would push spend on ${intent.symbol ?? intent.asset} past policy.maxTotal (${policy.maxTotal}); already spent ${spentForAssetBase} base units.`
       );
     }
   }
+  if (ctx && policy.windowTotal !== void 0 && policy.windowSeconds !== void 0) {
+    const cap = floorUnits(policy.windowTotal, intent.decimals);
+    if (ctx.spentInWindowBase + intent.amountBase > cap) {
+      return deny(
+        "WINDOW_TOTAL",
+        `this payment would exceed policy.windowTotal (${policy.windowTotal}) within the last ${policy.windowSeconds}s on ${intent.symbol ?? intent.asset}.`
+      );
+    }
+  }
   return ALLOW;
 }
 
@@ -1910,6 +1941,12 @@ var keyFor = (network, asset) => `${network}|${asset}`;
 var SpendLedger = class {
   records = [];
   buckets = /* @__PURE__ */ new Map();
+  /**
+   * Session clock origin (epoch-ms) — process/session start = ledger
+   * construction. In-memory; a new process is a new session. The client reads it
+   * to compute the `ttlSeconds` deadline and the rolling-window slice.
+   */
+  sessionStart = Date.now();
   /** Record a settled payment. `decimals` is the TRUE token decimals (for the
    *  per-asset running total used by maxTotal + the formatted summary). */
   record(r, decimals) {
@@ -1935,6 +1972,38 @@ var SpendLedger = class {
   totalFor(network, asset) {
     return this.buckets.get(keyFor(network, asset))?.total ?? 0n;
   }
+  /**
+   * Sum of base-unit amounts for (network, asset) whose record `at` (ISO
+   * timestamp) is at or after `sinceMs` (epoch-ms). Backs the rolling window
+   * (`sinceMs = now - windowSeconds*1000`). A linear scan of `records` —
+   * agent-session cardinality is small (tens), and it only runs when a window
+   * policy is set, so it's negligible against the network round-trip.
+   */
+  totalSince(network, asset, sinceMs) {
+    let sum = 0n;
+    for (const r of this.records) {
+      if (r.network === network && r.asset === asset && Date.parse(r.at) >= sinceMs) {
+        sum += BigInt(r.amountBase);
+      }
+    }
+    return sum;
+  }
+  /**
+   * The per-(network, asset) buckets, as read-only tuples — `network`, `asset`,
+   * `symbol`, the TRUE `decimals` (frozen from the first record), and the running
+   * `totalBase`. Lets the client compose a budget view WITHOUT coupling the ledger
+   * to the policy (the cap math lives in the client). Decimals only exist for a
+   * pair once it's been spent on — a never-spent pair simply isn't a bucket.
+   */
+  assetBuckets() {
+    return [...this.buckets.values()].map((b) => ({
+      network: b.network,
+      asset: b.asset,
+      ...b.symbol ? { symbol: b.symbol } : {},
+      decimals: b.decimals,
+      totalBase: b.total
+    }));
+  }
   /** An immutable snapshot of all spend so far. */
   summary() {
     return {
@@ -1977,6 +2046,37 @@ var PipRailClient = class {
     this.maxRetries = Math.max(1, opts.maxPaymentRetries ?? 3);
     this.retryTimeoutMs = opts.retryTimeoutMs ?? 3e4;
     this.onEvent = opts.onEvent ?? (() => void 0);
+    this.assertPolicyTimeOptions(opts.policy);
+  }
+  /**
+   * Fail LOUDLY at construction on a misconfigured time policy — a security
+   * boundary must never silently half-arm. Two invariants (a misconfiguration is
+   * a programmer error → `TypeError`, no new SDK error code):
+   *   - the rolling window needs BOTH `windowTotal` and `windowSeconds`, or NEITHER
+   *     (one alone is a leash that silently doesn't bite);
+   *   - `ttlSeconds` must be a positive, safe integer whose `*1000` deadline stays
+   *     within `Number.MAX_SAFE_INTEGER` (else the arithmetic would lose precision).
+   */
+  assertPolicyTimeOptions(policy) {
+    if (!policy) return;
+    const hasWindowTotal = policy.windowTotal !== void 0;
+    const hasWindowSeconds = policy.windowSeconds !== void 0;
+    if (hasWindowTotal !== hasWindowSeconds) {
+      throw new TypeError(
+        "policy.windowTotal and policy.windowSeconds must be set together \u2014 a rolling-window cap can't be half-armed (set both, or neither)."
+      );
+    }
+    if (hasWindowSeconds && !(Number.isSafeInteger(policy.windowSeconds) && policy.windowSeconds > 0)) {
+      throw new TypeError("policy.windowSeconds must be a positive integer number of seconds.");
+    }
+    if (policy.ttlSeconds !== void 0) {
+      const ttl = policy.ttlSeconds;
+      if (!Number.isSafeInteger(ttl) || ttl <= 0 || !Number.isSafeInteger(this.ledger.sessionStart + ttl * 1e3)) {
+        throw new TypeError(
+          "policy.ttlSeconds must be a positive integer number of seconds small enough that the resulting deadline stays a safe integer."
+        );
+      }
+    }
   }
   /** Emit an observability event, never letting a throwing handler break the
    * payment flow (mirrors the server gate's `onPaid` isolation). */
@@ -2074,6 +2174,64 @@ var PipRailClient = class {
   spent() {
     return this.ledger.summary();
   }
+  /**
+   * Read-only budget + time leash for a Mode-A (headless) agent — the policy IS
+   * the consent, and this is how the agent SEES what's left of it before paying.
+   * Composes the in-memory ledger with the configured policy; never throws, moves
+   * no funds. PROCESS-SCOPED — every figure resets on restart (see {@link SessionBudget}).
+   */
+  budget() {
+    const view = this.sessionView();
+    const start = new Date(this.ledger.sessionStart).toISOString();
+    return {
+      session: {
+        start,
+        expiresAt: view?.expiresAt != null ? new Date(view.expiresAt).toISOString() : null,
+        secondsRemaining: view?.secondsRemaining ?? null
+      },
+      byAsset: this.remaining()
+    };
+  }
+  /**
+   * Per-(network, asset) remaining budget — ONE row per pair the ledger already
+   * holds (decimals are known only after the first spend), so a fresh client with
+   * a `maxTotal` set returns `[]` until its first payment. `cap`/`remaining` are
+   * `undefined` when no `maxTotal` is configured (unbounded). Pure + in-memory;
+   * never throws, never sums across tokens (no price oracle). PROCESS-SCOPED.
+   */
+  remaining() {
+    const maxTotal = this.opts.policy?.maxTotal;
+    return this.ledger.assetBuckets().map((b) => {
+      const base2 = {
+        network: b.network,
+        asset: b.asset,
+        ...b.symbol ? { symbol: b.symbol } : {},
+        decimals: b.decimals,
+        spentBase: b.totalBase.toString()
+      };
+      if (maxTotal === void 0) return base2;
+      const capBase = floorUnits(maxTotal, b.decimals);
+      const remainingBase = capBase > b.totalBase ? capBase - b.totalBase : 0n;
+      return {
+        ...base2,
+        capBase: capBase.toString(),
+        remainingBase: remainingBase.toString(),
+        remainingFormatted: formatUnits(remainingBase, b.decimals)
+      };
+    });
+  }
+  /** The read-only TIME envelope for the plan/budget surfaces, or `undefined`
+   *  when no session deadline (`ttlSeconds`/`expiresAt`) is set. `secondsRemaining`
+   *  is clamped ≥ 0 — a best-effort host wall-clock estimate. */
+  sessionView(now = Date.now()) {
+    const policy = this.opts.policy;
+    if (!policy || policy.ttlSeconds == null && policy.expiresAt == null) return void 0;
+    const deadline = resolveDeadline(policy, this.ledger.sessionStart);
+    return {
+      expiresAt: deadline,
+      secondsRemaining: deadline == null ? null : Math.max(0, Math.floor((deadline - now) / 1e3))
+    };
+  }
   /**
    * Plan a payment for a gated URL — WITHOUT paying. The read-only completion of
    * the `quote()` → `estimateCost()` → **`planPayment()`** trio: it surveys every
@@ -2369,6 +2527,7 @@ var PipRailClient = class {
    *  net/wallet. Shared by `planPayment` (read-only) and `fetch`'s autoRoute. */
   async planFromChallenge(net, wallet, challenge, url, schemes) {
     const chainLabel = typeof this.opts.chain === "string" ? this.opts.chain : net.network;
+    const session = this.sessionView();
     const candidates = this.gatherCandidates(net, challenge, schemes);
     if (candidates.length === 0) {
       const offered = [...new Set(challenge.accepts.map((a) => a.network))].join(", ") || "none";
@@ -2379,7 +2538,8 @@ var PipRailClient = class {
         payable: false,
         best: null,
         options: [],
-        fundingHint: `This 402 isn't offered on your chain (${chainLabel}); it's payable on: ${offered}.`
+        fundingHint: `This 402 isn't offered on your chain (${chainLabel}); it's payable on: ${offered}.`,
+        ...session ? { session } : {}
       };
     }
     const analysed = await Promise.all(
@@ -2397,7 +2557,8 @@ var PipRailClient = class {
       payable: best !== null,
       best,
       options,
-      fundingHint: best ? null : buildFundingHint(options, chainLabel)
+      fundingHint: best ? null : buildFundingHint(options, chainLabel),
+      ...session ? { session } : {}
     };
   }
   /** Analyse ONE rail against the wallet's holdings — quote (existing) + gas
@@ -2414,7 +2575,11 @@ var PipRailClient = class {
     const blockers = [];
     const warnings = [];
     const shortfall = {};
-    if (!quote.withinPolicy) blockers.push("OUTSIDE_POLICY");
+    if (!quote.withinPolicy) {
+      blockers.push(
+        quote.policyCode === "SESSION_EXPIRED" || quote.policyCode === "WINDOW_TOTAL" ? "OUTSIDE_WINDOW" : "OUTSIDE_POLICY"
+      );
+    }
     if (quote.symbolMismatch) warnings.push("SYMBOL_MISMATCH");
     if (!isExact && cost.basis === "heuristic") warnings.push("GAS_HEURISTIC");
     const tokenKnown = bal.token != null;
@@ -2498,10 +2663,25 @@ var PipRailClient = class {
       symbol,
       recognized: described != null
     };
+    const policy = this.opts.policy;
+    const hasWindow = !!policy && policy.windowTotal != null && policy.windowSeconds != null;
+    const hasTimePolicy = !!policy && (policy.ttlSeconds != null || policy.expiresAt != null || hasWindow);
+    const now = Date.now();
+    const ctx = hasTimePolicy ? {
+      now,
+      sessionStart: this.ledger.sessionStart,
+      // Window slice ONLY when BOTH fields are set — never a `?? 0` width.
+      spentInWindowBase: hasWindow ? this.ledger.totalSince(
+        accept.network,
+        accept.asset,
+        now - policy.windowSeconds * 1e3
+      ) : 0n
+    } : void 0;
     const decision = evaluatePolicy(
       intent,
       this.opts.policy,
-      this.ledger.totalFor(accept.network, accept.asset)
+      this.ledger.totalFor(accept.network, accept.asset),
+      ctx
     );
     const serverSymbol = accept.extra.symbol;
     const symbolMismatch = intent.recognized && !!serverSymbol && !!symbol && serverSymbol.toUpperCase() !== symbol.toUpperCase();
@@ -2520,15 +2700,19 @@ var PipRailClient = class {
       recognized: intent.recognized,
       symbolMismatch,
       withinPolicy: decision.allowed,
-      ...decision.reason ? { policyReason: decision.reason } : {}
+      ...decision.reason ? { policyReason: decision.reason } : {},
+      ...decision.code ? { policyCode: decision.code } : {}
     };
   }
   /** Enforce the spend policy and the onBeforePay hook — both refuse by
-   *  throwing PaymentDeclinedError, before any funds move. */
+   *  throwing PaymentDeclinedError, before any funds move. Every refusal carries
+   *  a typed `reasonCode` so an agent can branch on the cause (and spot a
+   *  TERMINAL expiry/approval decline it must not retry) without parsing prose. */
   async authorize(quote) {
     if (!quote.withinPolicy) {
       throw new PaymentDeclinedError(
-        `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`
+        `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`,
+        { reasonCode: reasonCodeForPolicy(quote.policyCode) }
       );
     }
     const hook = this.opts.onBeforePay;
@@ -2538,12 +2722,14 @@ var PipRailClient = class {
       approved = await hook(quote);
     } catch (err) {
       throw new PaymentDeclinedError("onBeforePay threw \u2014 refusing to pay.", {
-        cause: err
+        cause: err,
+        reasonCode: "APPROVAL"
       });
     }
     if (!approved) {
       throw new PaymentDeclinedError(
-        `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`
+        `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`,
+        { reasonCode: "APPROVAL" }
       );
     }
   }
@@ -2771,6 +2957,9 @@ function buildFundingHint(options, chainLabel) {
   if (target.blockers.includes("RECIPIENT_NOT_READY")) {
     return `Recipient ${shortAddr(target.accept.payTo)} can't receive on ${chainLabel} yet \u2014 ${target.recipient.fix ?? "recipient not ready"}.`;
   }
+  if (target.blockers.includes("OUTSIDE_WINDOW")) {
+    return target.quote.policyCode === "SESSION_EXPIRED" ? `Session is over on ${chainLabel} \u2014 restart the process or extend the TTL; no retry will succeed.` : `Budget window exhausted on ${chainLabel} \u2014 wait for it to free, or raise policy.windowTotal.`;
+  }
   if (target.blockers.includes("OUTSIDE_POLICY")) {
     return `Refused by spend policy: ${target.quote.policyReason ?? "not allowed"}.`;
   }
@@ -2808,6 +2997,20 @@ function railOnNetwork(rail, matches) {
   const n = normalizeNetwork(rail.network);
   return !n.includes(":") || matches(n);
 }
+function reasonCodeForPolicy(code) {
+  switch (code) {
+    case "SESSION_EXPIRED":
+      return "SESSION_EXPIRED";
+    case "WINDOW_TOTAL":
+      return "OUTSIDE_WINDOW";
+    case "MAX_TOTAL":
+      return "BUDGET";
+    case void 0:
+      return void 0;
+    default:
+      return "POLICY";
+  }
+}
 function hostOf2(url) {
   try {
     return new URL(url).hostname;
@@ -2855,7 +3058,111 @@ async function readInvalidReason(response) {
   return null;
 }
 
+// src/render.ts
+function summarizePlan(plan) {
+  if (plan == null) return "No payment required \u2014 the URL is not payment-gated.";
+  if (plan.payable && plan.best) {
+    const q = plan.best.quote;
+    const c = plan.best.cost;
+    const otherRails = plan.options.length - 1;
+    const note = otherRails > 0 ? ` ${otherRails} other rail(s) not settleable.` : "";
+    return `Payable: ${q.amountFormatted} ${q.symbol ?? q.asset} on ${plan.best.accept.network} (gas ~${c.feeFormatted} ${c.feeSymbol}).${note}`;
+  }
+  return `NOT payable: ${plan.fundingHint ?? `no settleable rail on ${plan.network}`}`;
+}
+function explainDecline(err) {
+  if (!(err instanceof PipRailError)) {
+    return `Payment failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  switch (err.code) {
+    case "PAYMENT_DECLINED":
+      return err.message;
+    case "PAYMENT_TIMEOUT":
+    case "MAX_RETRIES_EXCEEDED":
+    case "CONFIRMATION_TIMEOUT":
+      return `${err.message} Recover using the proof on .ref (re-verify or re-submit it); never re-pay \u2014 a fresh payment would double-spend.`;
+    case "INSUFFICIENT_FUNDS":
+      return "The wallet cannot cover the payment + gas \u2014 top up the payer (token and/or native gas) and retry.";
+    case "RECIPIENT_NOT_READY":
+      return `${err.message} The fix is on the RECIPIENT (trustline / registration / opt-in / activation), not your balance.`;
+    case "NO_COMPATIBLE_ACCEPT":
+    case "UNSUPPORTED_SCHEME":
+      return err.message;
+    default:
+      return `Payment failed: ${err.message}`;
+  }
+}
+function formatSpendReport(summary) {
+  if (summary.count === 0) return "No payments yet.";
+  return summary.byAsset.map(
+    (a) => `${a.totalFormatted} ${a.symbol ?? a.asset} on ${a.network} (${a.count} payment${a.count === 1 ? "" : "s"})`
+  ).join("; ");
+}
+
+// src/agentGuide.ts
+var PIPRAIL_AGENT_GUIDE = `# Paying with PipRail \u2014 the agent contract
+
+You can pay for x402 "402 Payment Required" resources autonomously. Money moves
+straight from your wallet to the server; PipRail custodies nothing. Follow this.
+
+## The loop: quote \u2192 plan \u2192 pay
+1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and
+   whether it is within your spend policy. No funds move. Use it to decide if a
+   resource is worth buying.
+2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,
+   and recipient-readiness across every rail, and returns { payable, best,
+   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014
+   fundingHint says exactly what to fix.
+3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)
+   and return the result.
+Always plan before you pay so you never commit to a payment you cannot finish.
+
+## Reading a refusal \u2014 never crash, never double-spend
+A failed pay returns a STRUCTURED object, never a thrown error you must catch:
+  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }
+Branch on \`code\` (always reliable). Key cases:
+- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This
+  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone
+  without a restart / a longer TTL.
+- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this
+  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one
+  answered.
+- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is
+  exhausted. Wait for it to free, then retry; do not raise the amount.
+- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist
+  refused it. Don't retry the same payment; pick a cheaper/allowed one.
+- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.
+- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the
+  payment may ALREADY be on-chain. Recover using the proof on \`.ref\` (re-verify
+  or re-submit it); never re-pay \u2014 a fresh payment would double-spend.
+- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on
+  your chain/scheme; \`explain\` says whether it's the wrong chain or a scheme to enable.
+
+## Knowing your leash \u2014 call piprail_budget
+piprail_budget tells you how much budget and time you have left, per
+(network, asset), plus your spend so far. Read-only; moves no funds. Use it in
+Mode A to self-check before paying.
+
+## Two modes
+- Mode A (headless, default): you run FREE inside a pre-set budget + time
+  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay
+  inside it; piprail_budget shows what's left.
+- Mode B (supervised): the host may ask a human to approve each payment. A
+  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014
+  do NOT retry it as if it were a transient error.
+
+## Hard facts
+- Spend caps are PER (network, asset). There is no single cross-token dollar cap \u2014
+  budgets aren't summed across tokens (no price oracle).
+- Spend totals and the time envelope live IN-MEMORY for THIS process; they reset on restart
+  (a convenience, not a durable ledger).
+`;
+function agentGuide() {
+  return PIPRAIL_AGENT_GUIDE;
+}
+
 // src/agent.ts
+var OPEN_OBJECT = { type: "object", additionalProperties: true };
 async function readBody(res) {
   const text = await res.text();
   if (!text) return null;
@@ -2928,6 +3235,7 @@ function paymentTools(client) {
         required: ["url"],
         additionalProperties: false
       },
+      outputSchema: OPEN_OBJECT,
       invoke: async (args) => {
         const quote = await client.quote(String(args.url));
         return quote ? { gated: true, ...quote } : { gated: false, url: String(args.url) };
@@ -2951,6 +3259,7 @@ function paymentTools(client) {
         required: ["url"],
         additionalProperties: false
       },
+      outputSchema: OPEN_OBJECT,
       invoke: async (args) => {
         const plan = await client.planPayment(String(args.url));
         if (plan == null) return { gated: false, url: String(args.url) };
@@ -2959,6 +3268,8 @@ function paymentTools(client) {
           payable: plan.payable,
           status: plan.status,
           fundingHint: plan.fundingHint,
+          // One model-readable line distilling the whole plan.
+          summary: summarizePlan(plan),
           best: plan.best ? {
             network: plan.best.accept.network,
             symbol: plan.best.quote.symbol,
@@ -2974,7 +3285,9 @@ function paymentTools(client) {
             blockers: o.blockers,
             warnings: o.warnings,
             recipientReady: o.recipient.ready
-          }))
+          })),
+          // The session's time leash, present only when a time policy is configured.
+          ...plan.session ? { session: plan.session } : {}
         };
       }
     },
@@ -3032,8 +3345,20 @@ function paymentTools(client) {
             receipt: parseReceipt(res)
           };
         } catch (err) {
-          if (err instanceof PaymentDeclinedError) {
-            return { declined: true, reason: err.message };
+          if (err instanceof PipRailError) {
+            const out = {
+              ok: false,
+              code: err.code,
+              reason: err.message,
+              explain: explainDecline(err)
+            };
+            if (err instanceof PaymentDeclinedError) {
+              out.declined = true;
+              if (err.reasonCode) out.reasonCode = err.reasonCode;
+            }
+            const ref = err.ref;
+            if (typeof ref === "string") out.ref = ref;
+            return out;
           }
           throw err;
         }
@@ -3071,10 +3396,57 @@ function paymentTools(client) {
         const outcomes = await client.register(String(args.url), opts);
         return { outcomes };
       }
+    },
+    {
+      name: "piprail_budget",
+      description: "Read how much of your spend budget and time leash is left \u2014 per (network, asset) remaining, the session time envelope, and your spend so far. Use it in Mode A (headless) to self-check BEFORE paying, so you never discover the leash by hitting a decline. Read-only; moves no funds. NOTE: totals and the time envelope are in-memory for THIS process and reset on restart.",
+      annotations: {
+        title: "Check remaining budget",
+        readOnlyHint: true,
+        // reads the in-memory ledger + policy; never pays
+        idempotentHint: true
+        // a pure read
+      },
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      outputSchema: OPEN_OBJECT,
+      invoke: async () => {
+        const spent = client.spent();
+        const budget = client.budget();
+        return {
+          spent,
+          remaining: budget.byAsset,
+          session: budget.session,
+          report: formatSpendReport(spent)
+        };
+      }
+    },
+    {
+      name: "piprail_guide",
+      description: "Read the PipRail agent contract \u2014 the quote \u2192 plan \u2192 pay loop, how to read a refusal (and which declines are TERMINAL), the never-re-pay rule for broadcast-but-unconfirmed payments, and Mode A (headless) vs Mode B (supervised). Read-only; call it once if unsure how to use these tools.",
+      annotations: {
+        title: "How to use PipRail",
+        readOnlyHint: true,
+        idempotentHint: true
+      },
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      invoke: async () => ({ guide: PIPRAIL_AGENT_GUIDE })
     }
   ];
 }
 
+// src/classify.ts
+function classifyChallenge(challenge, opts) {
+  const accepts = challenge.accepts ?? [];
+  const offeredSchemes = [...new Set(accepts.map((a) => a.scheme))];
+  const offeredNetworks = [...new Set(accepts.map((a) => a.network))];
+  const onClientChain = accepts.some((a) => a.network === opts.network);
+  const payableScheme = accepts.some(
+    (a) => a.network === opts.network && opts.schemes.includes(a.scheme)
+  );
+  const verdict = accepts.length === 0 ? "NO_RAIL" : payableScheme ? "PAYABLE_RAIL" : onClientChain ? "UNPAYABLE_SCHEME" : "WRONG_CHAIN";
+  return { onClientChain, payableScheme, offeredSchemes, offeredNetworks, verdict };
+}
+
 // src/discovery.ts
 var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
 function buildBazaarExtension(descriptor = {}) {
@@ -3620,6 +3992,7 @@ export {
   MissingDriverError,
   NoCompatibleAcceptError,
   NonReplayableBodyError,
+  PIPRAIL_AGENT_GUIDE,
   PaymentDeclinedError,
   PaymentTimeoutError,
   PipRailClient,
@@ -3631,6 +4004,7 @@ export {
   UnsupportedSchemeError,
   WrongChainError,
   WrongFamilyError,
+  agentGuide,
   buildBazaarExtension,
   buildChallengeHeader,
   buildExactAuthorization,
@@ -3642,11 +4016,14 @@ export {
   buildX402DnsTxt,
   chainIdForExactNetwork,
   claim402IndexDomain,
+  classifyChallenge,
   createPaymentGate,
   decorateOutcome,
   eip3009Abi,
   encodeXPaymentHeader,
   evaluatePolicy,
+  explainDecline,
+  formatSpendReport,
   getDirectoryInfo,
   normalizeNetwork,
   parseChallenge,
@@ -3666,6 +4043,7 @@ export {
   resolveChain,
   searchOpenIndexes,
   settleViaFacilitator,
+  summarizePlan,
   toInsufficientFundsError,
   toInvalidBody,
   verify402IndexDomain