@lucid-agents/pi-xgate 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xgate contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# xgate provider for Pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Pi **v1.1.0** provider extension for wallet-paid inference. 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.
+
+## Install
+
+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+ (below 25) and Pi 1.1.0:
+
+```sh
+pi install npm:@lucid-agents/pi-xgate@0.1.5
+```
+
+For repository development before a release is available:
+
+```sh
+pnpm --filter @lucid-agents/xgate-client build
+pi install ./packages/pi-xgate
+```
+
+Pi supplies `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent` as peers.
+This release pins compatibility to 1.1.0; other versions need their own check.
+
+## Connect a wallet broker
+
+Choose Tempo MPP, Base x402 batch settlement, or Solana x402 exact in the
+[wallet service policy](../xgate-client/README.md#x402-configuration). Pi's provider
+and tool loop are the same for each; payment selection and keys stay in the broker.
+The new x402 client adapters have fixture coverage and still require separately
+budgeted signed live qualification before production use.
+
+Run the [wallet service](../xgate-client/README.md) outside the filesystem/process
+access available to Pi tools. The extension reads a **broker token**, not a wallet
+key. A broker running under the same user as unrestricted Pi shell tools does not
+provide key isolation.
+
+Use `/xgate setup` in Pi to set the broker URL and an absolute path to its token
+file. Setup writes `~/.pi/agent/xgate.json` only if it does not already exist. To
+change an existing setup, edit that owner-only file and use `/xgate refresh`.
+For headless runs, set `XGATE_CONFIG` to an absolute owner-only JSON file:
+
+```json
+{
+  "url": "http://127.0.0.1:4021",
+  "tokenFile": "/absolute/private/broker-token"
+}
+```
+
+Both files must be regular, nonsymlink files with no group/other permissions.
+Select a model through `/model`. Only the broker policy's models with compatible
+live qualifications are offered. OpenAI requires the new
+`openai-anonymous-tools-v2` router profile; an older server will expose no OpenAI
+coding models. Anthropic requires `anthropic-anonymous-usage-v3` and uses only
+`anthropic_no_cache` native Messages scopes.
+An expired/revoked catalog scope cannot authorize payment just because Pi remembers
+an earlier model list: the provider refreshes before each invocation and the wallet
+client validates the actual quote again.
+
+Commands:
+
+- `/xgate status`: pending purchases and budget totals.
+- `/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.
+- `/xgate refresh`: reload private configuration and available models.
+
+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.
+
+## Behavior and limits
+
+Responses are **buffered**, not token-streamed over the network. After a complete
+response and independently verified payment, the adapter emits Pi's normal text,
+thinking and tool-call events. It never exposes partial tool calls before payment
+verification. It emits one terminal event and honors cancellation; cancellation
+can still leave a charged or unresolved purchase requiring status inspection.
+
+There is no automatic paid POST retry. Stable invocation IDs bind retries to the
+same ledger record even when a payload hook changes its output. Unresolved
+purchases block new purchases. A lost result is not recoverable from xgate and
+cannot be regenerated by replaying the same invocation. Keep Pi agent/provider
+retry disabled for an initial deployment; the durable wallet guard is independent
+of that setting. Cache warming is disabled for this provider.
+
+The initial scope is text-only, with a maximum advertised output of 8,192 tokens
+and a default request cap of 4,096. A lower Pi `models.json` `modelOverrides`
+`maxTokens` value lowers that default; it cannot raise the live catalog limit. Pi thinking controls expose the reviewed levels (GPT-5 Mini currently permits only
+`minimal`) and clamp the selected level through Pi's native model handling.
+It rejects images, unsupported sampling/forced
+tool settings, excessive schemas and incompatible thinking levels before paying.
+OpenAI allows eight custom tools / 8 KiB of declarations; Anthropic allows 32 /
+64 KiB. The router additionally validates tool/result identities and message bounds.
+Opaque OpenAI reasoning reserves the reviewed full input ceiling because ciphertext
+length cannot prove its decoded token count. Consequently its authorization hold
+can be much larger than its eventual charge; the wallet cap still applies.
+
+Pi's token-cost figures are supplier-rate estimates, excluding router markup and
+success floors. `/xgate` status and receipts report actual atomic payment amounts.
+The extension sends no Pi session ID, caller metadata, cache affinity key or wallet
+credential to the inference provider. Payload hooks run before quoting and cannot
+change the model, output cap or tool declarations. Response hooks receive sanitized
+headers without payment/status capabilities.
+
+Pi retains its own transcripts by default. That is separate from xgate's
+application content-retention policy. Use Pi's `--no-session` option if local
+transcript persistence is unwanted; financial reconciliation records are separate.
+Changing models can discard incompatible opaque reasoning signatures, but preserves
+text/tool history and consistent tool IDs. Removing a historical Anthropic tool
+from the current tool set is rejected rather than silently losing that history.
+
+## Tests and rollout
+
+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. 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.
+That evidence is staging-only; it does not qualify production payment execution.
+Installing the extension does not publish router qualifications or deploy any service.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@lucid-agents/pi-xgate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.5",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "xgate",
+    "x402",
+    "mpp",
+    "lucid-agents"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@lucid-agents/xgate-client": "0.1.5"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0"
+  },
+  "engines": {
+    "node": ">=24.19 <25"
+  },
+  "description": "Wallet-paid OpenAI and Anthropic inference through xgate for the Pi coding agent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daydreamsai/402-router.git",
+    "directory": "packages/pi-xgate"
+  },
+  "homepage": "https://github.com/daydreamsai/402-router/tree/main/packages/pi-xgate",
+  "bugs": {
+    "url": "https://github.com/daydreamsai/402-router/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "gitHead": "2c12308686701f39f95093c5984d014c0ec83d26",
+  "xgateRelease": {
+    "version": "v0.1.5",
+    "sourceSha": "2c12308686701f39f95093c5984d014c0ec83d26",
+    "candidateId": "rc-2c1230868670-37853927676-1"
+  }
+}