@lucid-agents/pi-xgate 0.1.5 → 0.1.7

package/src/extension.ts

@@ -8,6 +8,15 @@ 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 type { XgatePayment, XgateTransport } from "./transport.ts";
+export interface XgateExtensionOptions {
+  /**
+   * Host-managed transport, or a factory called on load and `/xgate refresh`. When set, the
+   * extension reads no broker configuration and `/xgate setup` is unavailable. Without it, the
+   * standalone `BrokerClient` from `XGATE_CONFIG` or `~/.pi/agent/xgate.json` is used.
+   */
+  transport?: XgateTransport | (() => XgateTransport | Promise<XgateTransport>);
+}
 function privateText(path: string, max = 8192): string {
   if (!isAbsolute(path)) throw new XgateError("absolute_config_path_required");
   const s = lstatSync(path);
@@ -20,25 +29,57 @@ function privateText(path: string, max = 8192): string {
     throw new XgateError("private_config_required");
   return readFileSync(path, "utf8").trim();
 }
-export default async function extension(pi: ExtensionAPI): Promise<void> {
+function standalone(configPath: string): BrokerClient {
+  const cfg = JSON.parse(privateText(configPath));
+  if (typeof cfg.url !== "string" || typeof cfg.tokenFile !== "string")
+    throw new XgateError("invalid_config");
+  return new BrokerClient(cfg.url, privateText(cfg.tokenFile, 128));
+}
+/** Rail-neutral: atomic units of the named asset; decimals are not assumed. */
+export function paymentStatus(p: XgatePayment): string {
+  const left = p.channel
+    ? `; channel ${p.channel.refundableAtomic} refundable`
+    : "";
+  return `xgate paid ${p.chargedAtomic ?? "?"}/${p.authorizedAtomic} ${p.asset} on ${p.network} (${p.scheme})${left}`;
+}
+/** Pi extension factory. The default export is the standalone wallet-broker extension. */
+export function createXgateExtension(
+  options: XgateExtensionOptions = {},
+): (pi: ExtensionAPI) => Promise<void> {
+  return (pi) => register(pi, options);
+}
+export default createXgateExtension();
+async function register(
+  pi: ExtensionAPI,
+  options: XgateExtensionOptions,
+): Promise<void> {
+  const injected = options.transport;
   const configPath =
     process.env.XGATE_CONFIG ?? join(homedir(), ".pi", "agent", "xgate.json");
-  let broker: BrokerClient | undefined;
+  let broker: XgateTransport | undefined;
   let context: ExtensionContext | undefined;
   const load = async () => {
-    const cfg = JSON.parse(privateText(configPath));
-    if (typeof cfg.url !== "string" || typeof cfg.tokenFile !== "string")
-      throw new XgateError("invalid_config");
-    const next = new BrokerClient(cfg.url, privateText(cfg.tokenFile, 128));
-    const provider = await createXgateProvider(
-      next,
-      () => context?.sessionManager.getSessionId() ?? "standalone",
-      (r) =>
+    const next =
+      injected === undefined
+        ? standalone(configPath)
+        : typeof injected === "function"
+          ? await injected()
+          : injected;
+    const provider = await createXgateProvider(next, {
+      sessionId: () => context?.sessionManager.getSessionId() ?? "standalone",
+      onPaid: (r) =>
         context?.ui.setStatus(
           "xgate",
-          `xgate paid ${(Number(r.settlement.chargedAtomic) / 1e6).toFixed(6)}`,
+          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}`,
+        ),
+    });
     pi.registerProvider(provider);
     broker = next;
   };
@@ -63,6 +104,8 @@ export default async function extension(pi: ExtensionAPI): Promise<void> {
       const [command, id] = args.trim().split(/\s+/);
       try {
         if (command === "setup") {
+          if (injected !== undefined)
+            throw new XgateError("transport_managed_by_host");
           if (!ctx.hasUI)
             throw new XgateError("configure_XGATE_CONFIG_for_headless_mode");
           const url = await ctx.ui.input(
@@ -97,11 +140,15 @@ export default async function extension(pi: ExtensionAPI): Promise<void> {
         if (!broker) throw new XgateError("wallet_not_configured");
         if (command === "reconcile") {
           if (!id) throw new XgateError("purchase_id_required");
+          if (!broker.reconcile)
+            throw new XgateError("unsupported_by_transport");
           const result = await broker.reconcile(id);
           ctx.ui.notify(JSON.stringify(result), "info");
           return;
         }
         if (command === "receipts") {
+          if (!broker.receipts)
+            throw new XgateError("unsupported_by_transport");
           ctx.ui.notify(
             JSON.stringify(await broker.receipts(), null, 2),
             "info",
@@ -109,6 +156,7 @@ export default async function extension(pi: ExtensionAPI): Promise<void> {
           return;
         }
         if (command === "status" || command === "budget" || !command) {
+          if (!broker.status) throw new XgateError("unsupported_by_transport");
           const status = await broker.status();
           ctx.ui.notify(JSON.stringify(status, null, 2), "info");
           return;

package/src/index.ts

@@ -0,0 +1,45 @@
+// Supported entry point. Hosts build the provider around their own transport; the default
+// Pi extension (`./extension`) keeps the standalone wallet broker.
+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 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/src/provider.ts

@@ -5,26 +5,34 @@ import {
   type Model,
   type Provider,
   type SimpleStreamOptions,
-  type TranscriptContext,
 } from "@earendil-works/pi-ai";
+import { XgateError } from "@lucid-agents/xgate-client/types";
+import { catalogEntries, encode, decode, type PiContext } from "./codec.ts";
 import {
-  XgateError,
-  type PurchaseResult,
-  type Invocation,
-} from "@lucid-agents/xgate-client/types";
-import { catalogEntries, encode, decode } from "./codec.ts";
+  XgatePurchaseError,
+  type XgatePayment,
+  type XgatePurchaseResult,
+  type XgateTransport,
+} from "./transport.ts";
 const hash = (value: string): string =>
   createHash("sha256").update(value).digest("hex");
-export interface Broker {
-  models(signal?: AbortSignal): Promise<any[]>;
-  purchase(
-    input: Invocation,
-    signal?: AbortSignal,
-    onResponse?: (response: {
-      status: number;
-      headers: Record<string, string>;
-    }) => Promise<void>,
-  ): Promise<PurchaseResult>;
+/** @deprecated Use `XgateTransport`. */
+export type Broker = XgateTransport;
+export interface XgateProviderOptions {
+  /** Invocation identity scope when Pi supplies no `sessionId`. Defaults to `"standalone"`. */
+  sessionId?: () => string;
+  /** Display-only notification of a verified paid result; it cannot change the outcome. */
+  onPaid?: (result: XgatePurchaseResult) => void;
+  /** Terminal notification of a purchase that ended without a verified result. */
+  onPurchaseFailed?: (failure: XgatePurchaseFailure) => void;
+}
+export interface XgatePurchaseFailure {
+  /** The original invocation ID; reconcile it, never retry under a new one. */
+  invocationId: string;
+  code: string;
+  /** False only when the transport proved no unresolved payment. */
+  pending: boolean;
+  payment?: XgatePayment;
 }
 const zero = () => ({
   input: 0,
@@ -37,9 +45,14 @@ const zero = () => ({
 /** Stable across automatic retries and payload hooks; a changed paid payload cannot claim a new intent. */
 export function invocationId(
   model: string,
-  context: TranscriptContext,
+  context: PiContext,
   session: string,
 ): string {
+  // Pi 0.85 carries the prompt and tools beside the messages; Pi 1.1 carries them inside.
+  const legacy =
+    "systemPrompt" in context || "tools" in context
+      ? { systemPrompt: context.systemPrompt, tools: context.tools }
+      : {};
   return hash(
     JSON.stringify({
       session,
@@ -49,18 +62,22 @@ export function invocationId(
           m.role !== "assistant" ||
           !["error", "aborted"].includes(m.stopReason),
       ),
+      ...legacy,
     }),
   );
 }
 export async function createXgateProvider(
-  broker: Broker,
-  identity: () => string = () => "standalone",
-  onPaid?: (result: PurchaseResult) => void,
+  transport: XgateTransport,
+  {
+    sessionId: identity = () => "standalone",
+    onPaid,
+    onPurchaseFailed,
+  }: XgateProviderOptions = {},
 ): Promise<Provider> {
-  let entries = catalogEntries(await broker.models());
+  let entries = catalogEntries(await transport.models());
   const stream = (
     model: Model<any>,
-    context: TranscriptContext,
+    context: PiContext,
     options: SimpleStreamOptions = {},
   ) => {
     const events = createAssistantMessageEventStream();
@@ -86,10 +103,11 @@ export async function createXgateProvider(
       stopReason: "pending",
       timestamp: Date.now(),
     };
+    let attempted: string | undefined, paid: XgatePurchaseResult | undefined;
     void (async () => {
       try {
         options.signal?.throwIfAborted();
-        const current = catalogEntries(await broker.models(options.signal)),
+        const current = catalogEntries(await transport.models(options.signal)),
           entry = current.find(
             (e) => e.model.id === model.id && e.model.api === model.api,
           );
@@ -127,7 +145,8 @@ export async function createXgateProvider(
           options.sessionId ?? identity(),
         );
         let observed = false;
-        const result = await broker.purchase(
+        attempted = id;
+        const result = await transport.purchase(
           { id, route: entry.route, body },
           options.signal,
           async (response) => {
@@ -135,7 +154,8 @@ export async function createXgateProvider(
             await options.onResponse?.(response, model);
           },
         );
-        // In-process injected brokers have no HTTP body; retain the observation hook there too.
+        paid = result;
+        // In-process injected transports have no HTTP body; retain the observation hook there too.
         if (!observed)
           await options.onResponse?.(
             {
@@ -234,6 +254,28 @@ export async function createXgateProvider(
           : error instanceof XgateError
             ? error.message
             : "Xgate operation stopped. Inspect /xgate status before requesting another purchase.";
+        if (attempted !== undefined) {
+          // 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 failure: XgatePurchaseFailure = {
+            invocationId: attempted,
+            code: error instanceof XgateError ? error.code : "purchase_failed",
+            pending:
+              paid === undefined &&
+              !(error instanceof XgatePurchaseError && !error.pending),
+            ...(payment ? { payment } : {}),
+          };
+          // 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".
+          message.errorMessage += ` Billing invocation: ${attempted}.`;
+          try {
+            onPurchaseFailed?.(failure);
+          } catch {
+            /* Diagnostics cannot change the terminal outcome. */
+          }
+        }
         events.push({
           type: "error",
           reason: message.stopReason,
@@ -257,7 +299,7 @@ export async function createXgateProvider(
     getModels: () => entries.map((e) => e.model),
     refreshModels: async (context) => {
       if (!context.allowNetwork) return;
-      const updated = catalogEntries(await broker.models(context.signal));
+      const updated = catalogEntries(await transport.models(context.signal));
       await context.publish({
         update: () => {
           entries = updated;