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

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,212 @@
-# 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 provider extension for wallet-paid inference, supported on Pi **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.
+
+## 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.6
+```
+
+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 supports exactly 1.1.0 and 0.85.1 (the version TaskMarket's agent
+runtime pins); 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.
+
+## Host-injected transport
+
+A host that owns payment, such as TaskMarket, builds the provider around its own
+transport instead of the wallet broker. The supported entry point ships built
+JavaScript and type declarations:
+
+```ts
+import {
+  createXgateExtension,
+  createXgateProvider,
+  type XgateTransport,
+} from "@lucid-agents/pi-xgate";
+
+const transport: XgateTransport = {
+  models: (signal) => hostCatalog(signal), // router catalog rows
+  purchase: (invocation, signal) => hostPurchase(invocation, signal),
+};
+// As a Pi extension: the broker configuration and `/xgate setup` are not used.
+export default createXgateExtension({ transport });
+// Or directly, e.g. for an agent's stream function.
+const provider = await createXgateProvider(transport, {
+  sessionId: () => sessionId,
+});
+```
+
+`createXgateExtension({ transport })` also accepts a factory, called on load and on
+`/xgate refresh`. `/xgate status`, `budget`, `receipts` and `reconcile` use the
+transport's optional methods of the same names. The default extension
+(`@lucid-agents/pi-xgate/extension`, and Pi's `pi.extensions` entry) keeps the
+standalone `BrokerClient`.
+
+The provider keeps catalog qualification, native codecs and invocation identity;
+the transport only moves the frozen request and payment. A transport must send at
+most one paid submission per `Invocation.id`, never retry a paid request, reject a
+repeated ID rather than pay again, and resolve only with a verified result.
+`BrokerClient` satisfies this contract.
+
+### TaskMarket payer
+
+`createTaskMarketTransport` adapts TaskMarket's x402 payer (`@taskmarket/x402-payer`
+API v1). That package is private, so this one declares a structural
+`TaskMarketPayer` (`request`, `status`, `reconcile`) and TaskMarket injects its
+instance. The payer remains the only wallet, signer and payment journal; the
+adapter keeps no payment state.
+
+```ts
+const transport = createTaskMarketTransport({
+  payer, // TaskMarket's X402Payer
+  origin: "https://api.xgate.run",
+  allocationId, // the agent session's inference allocation
+  nonInteractive: true,
+  balances: () => allocations.balances(), // optional, for display
+});
+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
+});
+```
+
+- The Pi invocation ID is the payer `invocationId`. A retried turn reuses it, so
+  the payer refuses to send it again (`invocation_duplicate`).
+- The provider refreshes the router catalog (an unpaid `GET /v1/models`) before
+  every paid request. The payer's rail echoes the router quote binding and verifies
+  settlement.
+- A result is accepted only with a `settled` charge, the Anonymous privacy
+  headers and a native JSON body. Every other outcome rejects with
+  `XgatePurchaseError`. It is `pending` unless the payer proved no unresolved
+  payment; unknown future charge states count as unverified.
+- Pi gets a terminal `error`/`aborted` message naming the original invocation ID,
+  worded so Pi's transient-error retry does not fire. Only payer error codes reach
+  Pi, never payer messages. Hooks see only `content-type` and `cache-control`.
+- Payment details are rail-neutral (`XgatePayment`): CAIP-2 network, scheme, asset,
+  payee, rail kind, authorized and charged atomic amounts, status, reference and,
+  for a single matching session deposit, its channel balance. Pi displays them
+  and never selects or configures a rail.
+
+## 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. `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
+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.
+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/dist/codec.d.ts

@@ -0,0 +1,34 @@
+import type { AssistantMessage, Message, Model, SimpleStreamOptions, Tool, Usage } from "@earendil-works/pi-ai";
+import { type Route } from "@lucid-agents/xgate-client/types";
+export type Entry = {
+    model: Model<any>;
+    catalog: any;
+    route: Route;
+    efforts: string[];
+};
+export declare function catalogEntries(rows: any[]): Entry[];
+/**
+ * Pi 1.1 passes a normalized transcript; Pi 0.85 passes `systemPrompt` and `tools` beside the
+ * messages. Structural, so published types do not name a type only one Pi version has.
+ */
+export type PiContext = {
+    messages: Message[];
+    systemPrompt?: string;
+    tools?: Tool[];
+};
+type Turn = Exclude<Message, {
+    role: "system";
+}>;
+export declare function transcript(context: PiContext): {
+    system: string;
+    tools: Tool[];
+    messages: Turn[];
+};
+export declare function encode(entry: Entry, context: PiContext, options?: SimpleStreamOptions): any;
+export declare function decode(entry: Entry, body: any): {
+    content: AssistantMessage["content"];
+    usage: Usage;
+    stopReason: "stop" | "toolUse";
+    responseId: string;
+};
+export {};