@lucid-agents/pi-xgate 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,7 @@
 # xgate provider for Pi
 
-A Pi **v1.1.0** provider extension for wallet-paid inference. It uses native
+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.
@@ -9,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+ (below 25) and Pi 1.1.0:
+is not required. With Node 24.19 or later and Pi 1.1.0:
 
 ```sh
-pi install npm:@lucid-agents/pi-xgate@0.1.5
+pi install npm:@lucid-agents/pi-xgate@0.1.7
 ```
 
 For repository development before a release is available:
@@ -23,7 +24,8 @@ 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.
+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
 
@@ -54,8 +56,21 @@ 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.
+coding models. Anthropic requires `anthropic-anonymous-usage-v3` native Messages
+scopes qualified as `anthropic_no_cache`, `anthropic_ephemeral_5m` or
+`anthropic_ephemeral_1h`.
+
+Anthropic caches a prompt only at explicit `cache_control` breakpoints. On a
+cache-qualified scope the provider marks, like Pi's direct Anthropic provider, the
+last tool, the system prompt and the newest user turn (three of Anthropic's four
+breakpoints), so each call in a conversation can read the prefix the previous call
+wrote. Breakpoints are five-minute `ephemeral` writes; Pi's `cacheRetention: "long"`
+selects one-hour writes only on an `anthropic_ephemeral_1h` scope, and
+`cacheRetention: "none"` sends none. An `anthropic_no_cache` scope gets no
+breakpoints, and cache usage it reports is rejected as an invalid result. The
+breakpoints carry no session ID or other key: the provider cache is keyed by the
+content prefix alone. Cache warming stays off, so no unpaid or extra paid call
+is made to keep a cache alive.
 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.
@@ -73,6 +88,83 @@ 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
@@ -118,7 +210,11 @@ 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. Separate wallet tests cover durable financial boundaries.
+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.

package/dist/codec.d.ts

@@ -0,0 +1,40 @@
+import type { AssistantMessage, Message, Model, SimpleStreamOptions, Tool, Usage } from "@earendil-works/pi-ai";
+import { type Route } from "@lucid-agents/xgate-client/types";
+/** The widest Anthropic prompt-cache write lifetime a scope's qualification permits. */
+export type CacheTtl = "none" | "5m" | "1h";
+export type Entry = {
+    model: Model<any>;
+    catalog: any;
+    route: Route;
+    efforts: string[];
+    /** Anthropic only: requests may carry `cache_control` breakpoints up to this lifetime. */
+    cache: CacheTtl;
+    /** Anthropic only: the per-million-token price of a one-hour cache write. */
+    cacheWrite1h: number;
+};
+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 {};