@lucid-agents/pi-xgate 0.1.8 → 0.1.10

package/README.md

@@ -1,7 +1,7 @@
 # xgate provider for Pi
 
-A Pi provider extension for wallet-paid inference, supported on Pi **1.1.0** and
-**0.85.1**. It uses native
+A Pi provider extension for wallet-paid inference, supported on Pi **1.5.2**,
+**1.1.0** and **0.85.1**. It uses native
 Anthropic Messages and structured OpenAI Responses through xgate. Pi executes its
 own tools; xgate never executes local tools. Text, tool calls/results and supported
 reasoning signatures survive the full agent loop.
@@ -10,10 +10,10 @@ reasoning signatures survive the full agent loop.
 
 The release package is `@lucid-agents/pi-xgate`. It includes the client dependency
 and the reviewed model-capability snapshot; the internal router contracts package
-is not required. With Node 24.19 or later and Pi 1.1.0:
+is not required. With Node 24.19 or later and Pi 1.5.2:
 
 ```sh
-pi install npm:@lucid-agents/pi-xgate@0.1.8
+pi install npm:@lucid-agents/pi-xgate@0.1.10
 ```
 
 For repository development before a release is available:
@@ -24,8 +24,9 @@ pi install ./packages/pi-xgate
 ```
 
 Pi supplies `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent` as peers.
-This release supports exactly 1.1.0 and 0.85.1 (the version TaskMarket's agent
-runtime pins); other versions need their own check.
+This release supports exactly 1.5.2, 1.1.0 and 0.85.1 (the version TaskMarket's agent
+runtime pins); other versions need their own check. `pi install` does not enforce
+the peer range, so on another Pi version the extension loads unchecked.
 
 ## Connect a wallet broker
 
@@ -81,9 +82,50 @@ Commands:
 - `/xgate budget`: show the wallet service's fixed authorization caps.
 - `/xgate receipts`: recent content-free payment records.
 - `/xgate reconcile <invocation ID>`: inspect/reconcile the original purchase without
-  resubmitting inference or payment.
+  resubmitting inference or payment. If it reports `authorization_still_live`, the
+  router refused the request before funding but the signed Tempo or Base
+  authorization has not provably expired yet: run the same command again after it
+  expires (Tempo signs about 25 seconds ahead and must then be finalized; Base signs
+  up to 120 seconds ahead and must then reach the policy's confirmation level). Do
+  not start a replacement purchase. Other errors and their actions are in the wallet
+  client's refused before funding sections for
+  [Tempo](../xgate-client/README.md#tempo-purchases-refused-before-funding) and
+  [Base](../xgate-client/README.md#base-purchases-refused-before-funding).
 - `/xgate refresh`: reload private configuration and available models.
 
+### Rate limits
+
+On Tempo the router sponsors the network fee for each purchase's payment channel and
+limits those openings: per wallet **4 a minute** and **13 an hour** (2.00 of
+reserved fee at the current 0.15 cap), with at most 3 unconfirmed at once; across
+all wallets 30 a minute and 66 an hour. Every model call is one purchase and an
+agent turn makes two or more, so an active session reaches these in normal use.
+The full table and what each limit bounds are in the wallet client's
+[Tempo rate limits](../xgate-client/README.md#tempo-rate-limits).
+
+A call over a limit is refused before any funds move. The turn ends with an error
+that says it was a rate limit and how long the router suggests waiting, for example:
+
+```text
+Xgate: rate_limited_requires_reconciliation. The router refused this purchase with
+a rate limit and suggests waiting 32 seconds before a new one. Reconcile this
+purchase first; never resend it. Billing invocation: 3f…c1.
+```
+
+The status line shows the same two steps:
+`xgate rate limited (unresolved): /xgate reconcile <invocation ID>, then wait 32s before a new request`.
+
+1. Run `/xgate reconcile <invocation ID>`. The wallet finishes the purchase at a
+   charge of zero only after it has proven on chain that the signed authorization
+   expired unused; until then the command reports `authorization_still_live` (run
+   it again a little later).
+2. Send the request again as a new turn once the wait has passed. It is a new
+   purchase with a new quote.
+
+Pi does not retry the turn by itself, and the provider never resends a paid
+request. A host can read the wait from `onPurchaseFailed` as `retryAfterSeconds`.
+A host transport reports one by passing it to `XgatePurchaseError`.
+
 Pi cannot raise the service budget. Authorized ceilings remain consumed after
 successful settlement even when most of a deposit is returned. A new budget is an
 explicit wallet-operator action, never automatic rollover or a fresh journal.
@@ -144,7 +186,7 @@ const transport = createTaskMarketTransport({
 const provider = await createXgateProvider(transport, {
   sessionId: () => sessionId,
   onPaid: (r) => show(r.payment), // network, scheme, asset, atomic amounts, channel
-  onPurchaseFailed: (f) => record(f), // original invocation ID, code, pending
+  onPurchaseFailed: (f) => record(f), // original invocation ID, code, pending, retryAfterSeconds
 });
 ```
 
@@ -210,13 +252,14 @@ from the current tool set is rejected rather than silently losing that history.
 
 Run `pnpm pi:check` at the repository root. Tests instantiate Pi's real agent core,
 execute a fixture tool, and verify the next request contains its exact result and
-reasoning history. `pnpm packages:check` installs the packed tarballs with Pi 1.1.0
-and 0.85.1 and runs each real Pi CLI through the mock broker and an injected
+reasoning history. `pnpm packages:check` installs the packed tarballs with Pi 1.5.2,
+1.1.0 and 0.85.1 and runs each real Pi CLI through the mock broker and an injected
 transport, type-checks a consumer of the supported exports, and runs the TaskMarket
 payer loop suite (`test/installed-loop.test.ts`: continuation, qualification,
 cancellation, duplicate and lost response) against each installed Pi. Separate wallet tests cover durable financial boundaries.
 These are fixture tests. The [9 October staging campaign](../../docs/validation/pi-client-staging-20261009.md)
-separately exercised the installed Pi CLI with live providers and test tokens.
+separately exercised the installed Pi 1.1.0 CLI with live providers and test tokens;
+Pi 1.5.2 and 0.85.1 have fixture coverage only.
 That evidence is staging-only; it does not qualify production payment execution.
 Installing the extension does not publish router qualifications or deploy any service.
 

package/dist/extension.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type XgatePurchaseFailure } from "./provider.ts";
 import type { XgatePayment, XgateTransport } from "./transport.ts";
 export interface XgateExtensionOptions {
     /**
@@ -10,6 +11,8 @@ export interface XgateExtensionOptions {
 }
 /** Rail-neutral: atomic units of the named asset; decimals are not assumed. */
 export declare function paymentStatus(p: XgatePayment): string;
+/** What to do about a purchase that ended without a verified result. */
+export declare function failureStatus(f: XgatePurchaseFailure): string;
 /** Pi extension factory. The default export is the standalone wallet-broker extension. */
 export declare function createXgateExtension(options?: XgateExtensionOptions): (pi: ExtensionAPI) => Promise<void>;
 declare const _default: (pi: ExtensionAPI) => Promise<void>;

package/dist/extension.js

@@ -28,6 +28,13 @@ export function paymentStatus(p) {
         : "";
     return `xgate paid ${p.chargedAtomic ?? "?"}/${p.authorizedAtomic} ${p.asset} on ${p.network} (${p.scheme})${left}`;
 }
+/** What to do about a purchase that ended without a verified result. */
+export function failureStatus(f) {
+    const state = f.pending ? "unresolved" : "failed";
+    return f.retryAfterSeconds === undefined
+        ? `xgate ${state}: ${f.invocationId}`
+        : `xgate rate limited (${state}): ${f.pending ? `/xgate reconcile ${f.invocationId}, then ` : ""}wait ${f.retryAfterSeconds}s before a new request`;
+}
 /** Pi extension factory. The default export is the standalone wallet-broker extension. */
 export function createXgateExtension(options = {}) {
     return (pi) => register(pi, options);
@@ -49,7 +56,7 @@ async function register(pi, options) {
             onPaid: (r) => context?.ui.setStatus("xgate", r.payment
                 ? paymentStatus(r.payment)
                 : `xgate paid ${(Number(r.settlement.chargedAtomic) / 1e6).toFixed(6)}`),
-            onPurchaseFailed: (f) => context?.ui.setStatus("xgate", `xgate ${f.pending ? "unresolved" : "failed"}: ${f.invocationId}`),
+            onPurchaseFailed: (f) => context?.ui.setStatus("xgate", failureStatus(f)),
         });
         pi.registerProvider(provider);
         broker = next;

package/dist/generated/openai-model-capabilities.json

@@ -843,5 +843,28 @@
             "gpt-6.1-sol"
         ],
         "chat_tools": "unsupported"
+    },
+    "gpt-6.1-terra": {
+        "canonical": "gpt-6.1-terra",
+        "price_label": "gpt-6.1-terra",
+        "operations": [
+            "chat",
+            "responses"
+        ],
+        "reasoning_efforts": [
+            "none",
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "max"
+        ],
+        "cache": "write_priced",
+        "tools": true,
+        "chat_legacy_max_tokens": false,
+        "response_models": [
+            "gpt-6.1-terra"
+        ],
+        "chat_tools": "unsupported"
     }
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { createXgateProvider, invocationId, type Broker, type XgateProviderOptions, type XgatePurchaseFailure, } from "./provider.ts";
 export { XgatePurchaseError, type XgateChannelBalance, type XgatePayment, type XgatePurchaseResult, type XgateResponseHead, type XgateTransport, } from "./transport.ts";
 export { createXgateExtension, type XgateExtensionOptions, } from "./extension.ts";
-export { XgateError } from "@lucid-agents/xgate-client/types";
+export { XgateError, XgateRateLimitedError, } from "@lucid-agents/xgate-client/types";
 export type { Invocation, PurchaseResult, Route, Settlement, } from "@lucid-agents/xgate-client/types";
 export { createTaskMarketTransport, type TaskMarketChargeStatus, type TaskMarketFundingBalance, type TaskMarketInvocationState, type TaskMarketInvocationStatus, type TaskMarketPayCallOptions, type TaskMarketPayErrorCode, type TaskMarketPayer, type TaskMarketPayerLimits, type TaskMarketPayRequest, type TaskMarketPayResponse, type TaskMarketPayResult, type TaskMarketPaymentSummary, type TaskMarketPaymentTerms, type TaskMarketTransportOptions, } from "./taskmarket.ts";

package/dist/index.js

@@ -3,5 +3,5 @@
 export { createXgateProvider, invocationId, } from "./provider.js";
 export { XgatePurchaseError, } from "./transport.js";
 export { createXgateExtension, } from "./extension.js";
-export { XgateError } from "@lucid-agents/xgate-client/types";
+export { XgateError, XgateRateLimitedError, } from "@lucid-agents/xgate-client/types";
 export { createTaskMarketTransport, } from "./taskmarket.js";

package/dist/provider.d.ts

@@ -18,6 +18,11 @@ export interface XgatePurchaseFailure {
     /** False only when the transport proved no unresolved payment. */
     pending: boolean;
     payment?: XgatePayment;
+    /**
+     * Set when the payee refused the purchase with a rate limit: its suggested wait, in
+     * seconds, before a new purchase. Reconciling this invocation still comes first.
+     */
+    retryAfterSeconds?: number;
 }
 /** Stable across automatic retries and payload hooks; a changed paid payload cannot claim a new intent. */
 export declare function invocationId(model: string, context: PiContext, session: string): string;

package/dist/provider.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
-import { XgateError } from "@lucid-agents/xgate-client/types";
+import { XgateError, XgateRateLimitedError, } from "@lucid-agents/xgate-client/types";
 import { catalogEntries, encode, decode } from "./codec.js";
 import { XgatePurchaseError, } from "./transport.js";
 const hash = (value) => createHash("sha256").update(value).digest("hex");
@@ -188,12 +188,18 @@ export async function createXgateProvider(transport, { sessionId: identity = ()
                     // After a verified result the charge is known even if Pi discards the content.
                     const payment = paid?.payment ??
                         (error instanceof XgatePurchaseError ? error.payment : undefined);
+                    const wait = paid === undefined &&
+                        (error instanceof XgateRateLimitedError ||
+                            error instanceof XgatePurchaseError)
+                        ? error.retryAfterSeconds
+                        : undefined;
                     const failure = {
                         invocationId: attempted,
                         code: error instanceof XgateError ? error.code : "purchase_failed",
                         pending: paid === undefined &&
                             !(error instanceof XgatePurchaseError && !error.pending),
                         ...(payment ? { payment } : {}),
+                        ...(wait !== undefined ? { retryAfterSeconds: wait } : {}),
                     };
                     // The original ID is the only reconciliation key. "Billing" also keeps Pi's transient
                     // error classifier from retrying a message whose hex ID happens to contain "500".

package/dist/transport.d.ts

@@ -47,7 +47,9 @@ export declare class XgatePurchaseError extends XgateError {
     readonly invocationId: string;
     readonly pending: boolean;
     readonly payment?: XgatePayment;
-    constructor(code: string, invocationId: string, pending: boolean, payment?: XgatePayment);
+    /** The payee's rate-limit hint, in seconds, when that is why the purchase ended. */
+    readonly retryAfterSeconds?: number;
+    constructor(code: string, invocationId: string, pending: boolean, payment?: XgatePayment, retryAfterSeconds?: number);
 }
 /**
  * Moves one frozen Pi request to xgate and returns the verified result. The provider owns

package/dist/transport.js

@@ -7,15 +7,24 @@ export class XgatePurchaseError extends XgateError {
     invocationId;
     pending;
     payment;
-    constructor(code, invocationId, pending, payment) {
+    /** The payee's rate-limit hint, in seconds, when that is why the purchase ended. */
+    retryAfterSeconds;
+    constructor(code, invocationId, pending, payment, retryAfterSeconds) {
         super(code);
         this.name = "XgatePurchaseError";
-        this.message = pending
-            ? `Xgate: ${code}. The payment outcome is unknown; do not retry. Reconcile it before another purchase.`
-            : `Xgate: ${code}. Inspect the payment status before another purchase.`;
+        const limited = retryAfterSeconds === undefined
+            ? ""
+            : ` The payee rate limited it and suggests waiting ${retryAfterSeconds} seconds before a new purchase.`;
+        this.message =
+            (pending
+                ? `Xgate: ${code}. The payment outcome is unknown; do not retry. Reconcile it before another purchase.`
+                : `Xgate: ${code}. Inspect the payment status before another purchase.`) +
+                limited;
         this.invocationId = invocationId;
         this.pending = pending;
         if (payment)
             this.payment = payment;
+        if (retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = retryAfterSeconds;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucid-agents/pi-xgate",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "exports": {
     ".": {
@@ -32,11 +32,11 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@lucid-agents/xgate-client": "0.1.8"
+    "@lucid-agents/xgate-client": "0.1.10"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.85.1 || 1.1.0",
-    "@earendil-works/pi-coding-agent": "0.85.1 || 1.1.0"
+    "@earendil-works/pi-ai": "0.85.1 || 1.1.0 || 1.5.2",
+    "@earendil-works/pi-coding-agent": "0.85.1 || 1.1.0 || 1.5.2"
   },
   "engines": {
     "node": ">=24.19"
@@ -56,10 +56,10 @@
     "registry": "https://registry.npmjs.org"
   },
   "license": "MIT",
-  "gitHead": "d410140f8e57fd3fc4309a1c54772b8a9f99ccd9",
+  "gitHead": "4b2e77819216a41c265171bdaae9291f9b129037",
   "xgateRelease": {
-    "version": "v0.1.8",
-    "sourceSha": "d410140f8e57fd3fc4309a1c54772b8a9f99ccd9",
-    "candidateId": "rc-d410140f8e57-42908627975-1"
+    "version": "v0.1.10",
+    "sourceSha": "4b2e77819216a41c265171bdaae9291f9b129037",
+    "candidateId": "rc-4b2e77819216-43169339829-1"
   }
 }

package/src/extension.ts

@@ -7,7 +7,7 @@ import { XgateError } from "@lucid-agents/xgate-client/types";
 import { readFileSync, lstatSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { homedir } from "node:os";
-import { createXgateProvider } from "./provider.ts";
+import { createXgateProvider, type XgatePurchaseFailure } from "./provider.ts";
 import type { XgatePayment, XgateTransport } from "./transport.ts";
 export interface XgateExtensionOptions {
   /**
@@ -42,6 +42,13 @@ export function paymentStatus(p: XgatePayment): string {
     : "";
   return `xgate paid ${p.chargedAtomic ?? "?"}/${p.authorizedAtomic} ${p.asset} on ${p.network} (${p.scheme})${left}`;
 }
+/** What to do about a purchase that ended without a verified result. */
+export function failureStatus(f: XgatePurchaseFailure): string {
+  const state = f.pending ? "unresolved" : "failed";
+  return f.retryAfterSeconds === undefined
+    ? `xgate ${state}: ${f.invocationId}`
+    : `xgate rate limited (${state}): ${f.pending ? `/xgate reconcile ${f.invocationId}, then ` : ""}wait ${f.retryAfterSeconds}s before a new request`;
+}
 /** Pi extension factory. The default export is the standalone wallet-broker extension. */
 export function createXgateExtension(
   options: XgateExtensionOptions = {},
@@ -74,11 +81,7 @@ async function register(
             ? paymentStatus(r.payment)
             : `xgate paid ${(Number(r.settlement.chargedAtomic) / 1e6).toFixed(6)}`,
         ),
-      onPurchaseFailed: (f) =>
-        context?.ui.setStatus(
-          "xgate",
-          `xgate ${f.pending ? "unresolved" : "failed"}: ${f.invocationId}`,
-        ),
+      onPurchaseFailed: (f) => context?.ui.setStatus("xgate", failureStatus(f)),
     });
     pi.registerProvider(provider);
     broker = next;

package/src/generated/openai-model-capabilities.json

@@ -843,5 +843,28 @@
       "gpt-6.1-sol"
     ],
     "chat_tools": "unsupported"
+  },
+  "gpt-6.1-terra": {
+    "canonical": "gpt-6.1-terra",
+    "price_label": "gpt-6.1-terra",
+    "operations": [
+      "chat",
+      "responses"
+    ],
+    "reasoning_efforts": [
+      "none",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max"
+    ],
+    "cache": "write_priced",
+    "tools": true,
+    "chat_legacy_max_tokens": false,
+    "response_models": [
+      "gpt-6.1-terra"
+    ],
+    "chat_tools": "unsupported"
   }
 }

package/src/index.ts

@@ -19,7 +19,10 @@ export {
   createXgateExtension,
   type XgateExtensionOptions,
 } from "./extension.ts";
-export { XgateError } from "@lucid-agents/xgate-client/types";
+export {
+  XgateError,
+  XgateRateLimitedError,
+} from "@lucid-agents/xgate-client/types";
 export type {
   Invocation,
   PurchaseResult,

package/src/provider.ts

@@ -6,7 +6,10 @@ import {
   type Provider,
   type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
-import { XgateError } from "@lucid-agents/xgate-client/types";
+import {
+  XgateError,
+  XgateRateLimitedError,
+} from "@lucid-agents/xgate-client/types";
 import { catalogEntries, encode, decode, type PiContext } from "./codec.ts";
 import {
   XgatePurchaseError,
@@ -33,6 +36,11 @@ export interface XgatePurchaseFailure {
   /** False only when the transport proved no unresolved payment. */
   pending: boolean;
   payment?: XgatePayment;
+  /**
+   * Set when the payee refused the purchase with a rate limit: its suggested wait, in
+   * seconds, before a new purchase. Reconciling this invocation still comes first.
+   */
+  retryAfterSeconds?: number;
 }
 const zero = () => ({
   input: 0,
@@ -259,6 +267,12 @@ export async function createXgateProvider(
           const payment =
             paid?.payment ??
             (error instanceof XgatePurchaseError ? error.payment : undefined);
+          const wait =
+            paid === undefined &&
+            (error instanceof XgateRateLimitedError ||
+              error instanceof XgatePurchaseError)
+              ? error.retryAfterSeconds
+              : undefined;
           const failure: XgatePurchaseFailure = {
             invocationId: attempted,
             code: error instanceof XgateError ? error.code : "purchase_failed",
@@ -266,6 +280,7 @@ export async function createXgateProvider(
               paid === undefined &&
               !(error instanceof XgatePurchaseError && !error.pending),
             ...(payment ? { payment } : {}),
+            ...(wait !== undefined ? { retryAfterSeconds: wait } : {}),
           };
           // The original ID is the only reconciliation key. "Billing" also keeps Pi's transient
           // error classifier from retrying a message whose hex ID happens to contain "500".

package/src/transport.ts

@@ -51,20 +51,31 @@ export class XgatePurchaseError extends XgateError {
   readonly invocationId: string;
   readonly pending: boolean;
   readonly payment?: XgatePayment;
+  /** The payee's rate-limit hint, in seconds, when that is why the purchase ended. */
+  readonly retryAfterSeconds?: number;
   constructor(
     code: string,
     invocationId: string,
     pending: boolean,
     payment?: XgatePayment,
+    retryAfterSeconds?: number,
   ) {
     super(code);
     this.name = "XgatePurchaseError";
-    this.message = pending
-      ? `Xgate: ${code}. The payment outcome is unknown; do not retry. Reconcile it before another purchase.`
-      : `Xgate: ${code}. Inspect the payment status before another purchase.`;
+    const limited =
+      retryAfterSeconds === undefined
+        ? ""
+        : ` The payee rate limited it and suggests waiting ${retryAfterSeconds} seconds before a new purchase.`;
+    this.message =
+      (pending
+        ? `Xgate: ${code}. The payment outcome is unknown; do not retry. Reconcile it before another purchase.`
+        : `Xgate: ${code}. Inspect the payment status before another purchase.`) +
+      limited;
     this.invocationId = invocationId;
     this.pending = pending;
     if (payment) this.payment = payment;
+    if (retryAfterSeconds !== undefined)
+      this.retryAfterSeconds = retryAfterSeconds;
   }
 }
 /**