@lucid-agents/pi-xgate 0.1.5 → 0.1.6

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;

package/src/taskmarket.ts

@@ -0,0 +1,484 @@
+// Adapts TaskMarket's x402 payer to the xgate Pi transport. The payer package is private, so
+// this file declares the structural subset of its v1 contract (`@taskmarket/x402-payer`
+// `src/api.ts`, X402_PAYER_API_VERSION 1) that the adapter uses; TaskMarket injects its
+// instance. The payer owns the wallet, signer, rails, policy and journals: this adapter keeps
+// no payment state of its own.
+//
+// The payer's string unions may gain values without a version bump. Every type here accepts
+// unknown strings, and the adapter treats an unknown state as unverified.
+import {
+  atomic,
+  origin as checkOrigin,
+  record,
+  route as checkRoute,
+  XgateError,
+  type Invocation,
+} from "@lucid-agents/xgate-client/types";
+import {
+  XgatePurchaseError,
+  type XgateChannelBalance,
+  type XgatePayment,
+  type XgatePurchaseResult,
+  type XgateResponseHead,
+  type XgateTransport,
+} from "./transport.ts";
+type Open<T extends string> = T | (string & {});
+export type TaskMarketChargeStatus = Open<
+  | "none"
+  | "reserved"
+  | "pending"
+  | "settled"
+  | "amount_unknown"
+  | "released"
+  | "manually_resolved"
+>;
+export type TaskMarketInvocationState = Open<
+  "in_progress" | "interrupted" | "completed" | "failed"
+>;
+export type TaskMarketPayErrorCode = Open<
+  | "invalid_request"
+  | "request_body_too_large"
+  | "response_body_too_large"
+  | "challenge_invalid"
+  | "invocation_conflict"
+  | "invocation_duplicate"
+  | "invocation_not_found"
+  | "destination_rejected"
+  | "policy_denied"
+  | "payment_declined"
+  | "no_supported_rail"
+  | "signer_unavailable"
+  | "journal_unavailable"
+  | "aborted"
+  | "outcome_uncertain"
+  | "paid_retry_prohibited"
+  | "request_failed"
+  | "allocation_not_found"
+  | "allocation_conflict"
+  | "allocation_closed"
+  | "allocation_exhausted"
+  | "allocation_mismatch"
+  | "funding_exhausted"
+  | "allocation_required"
+  | "reservation_not_found"
+>;
+export interface TaskMarketPayerLimits {
+  maxRequestBodyBytes: number;
+  maxResponseBodyBytes: number;
+  maxChallengeBodyBytes: number;
+}
+export interface TaskMarketPayRequest {
+  apiVersion: 1;
+  invocationId: string;
+  url: string;
+  method: "GET" | "POST";
+  headers?: Record<string, string>;
+  body?: Uint8Array;
+  policyRuleId?: string;
+  nonInteractive?: boolean;
+  limits?: Partial<TaskMarketPayerLimits>;
+  allocationId?: string;
+}
+export interface TaskMarketPaymentTerms {
+  origin: string;
+  pathname: string;
+  method: "GET" | "POST";
+  rail: { id: string; kind: string };
+  scheme: string;
+  network: string;
+  asset: string;
+  payTo: string;
+  authorizedAmount: string;
+  policyRuleId?: string;
+  windowMaximum?: string;
+  unattended: boolean;
+}
+export interface TaskMarketPayCallOptions {
+  signal?: AbortSignal;
+  confirmPayment?: (terms: TaskMarketPaymentTerms) => Promise<boolean>;
+}
+export interface TaskMarketPaymentSummary {
+  paymentId: string;
+  rail: { id: string; kind: string };
+  network: string;
+  scheme: string;
+  asset: string;
+  payTo: string;
+  payer: string;
+  authorizedAmount: string;
+  settledAmount?: string;
+  transaction?: string;
+  commitment?: string;
+  charge: TaskMarketChargeStatus;
+}
+export interface TaskMarketPayResponse {
+  status: number;
+  headers: Record<string, string>;
+  contentType: string;
+  bytes: number;
+  sha256: string;
+  body: Uint8Array;
+}
+export interface TaskMarketPayResult {
+  apiVersion: number;
+  invocationId: string;
+  requestFingerprint: string;
+  payment?: TaskMarketPaymentSummary;
+  response: TaskMarketPayResponse;
+}
+export interface TaskMarketInvocationStatus {
+  apiVersion: number;
+  invocationId: string;
+  requestFingerprint: string;
+  state: TaskMarketInvocationState;
+  charge: TaskMarketChargeStatus;
+  uncertain: boolean;
+  errorCode?: TaskMarketPayErrorCode;
+  createdAt: string;
+  updatedAt: string;
+  payment?: TaskMarketPaymentSummary;
+}
+/** Structural `X402Payer` v1. */
+export interface TaskMarketPayer {
+  readonly apiVersion: 1;
+  request(
+    input: TaskMarketPayRequest,
+    options?: TaskMarketPayCallOptions,
+  ): Promise<TaskMarketPayResult>;
+  status(invocationId: string): Promise<TaskMarketInvocationStatus>;
+  reconcile(invocationId: string): Promise<TaskMarketInvocationStatus>;
+}
+/** Structural `X402FundingBalance`: one session-rail deposit. */
+export interface TaskMarketFundingBalance {
+  railId: string;
+  sessionKey: string;
+  network: string;
+  asset: string;
+  depositing: string;
+  locked: string;
+  refunded: string;
+  charged: string;
+  pending: string;
+  refundable: string;
+}
+export interface TaskMarketTransportOptions {
+  payer: TaskMarketPayer;
+  /** Router origin, e.g. `https://api.xgate.run`. */
+  origin: string;
+  /** Allocation that bounds this agent's inference; forwarded on every request. */
+  allocationId?: string;
+  policyRuleId?: string;
+  /** Authorize only through unattended policy rules. */
+  nonInteractive?: boolean;
+  /** Attended confirmation, forwarded to the payer. */
+  confirmPayment?: (terms: TaskMarketPaymentTerms) => Promise<boolean>;
+  /** Restrict the offered models; the router catalog still qualifies them. */
+  models?: readonly string[];
+  /** Session-rail balances for display, e.g. TaskMarket's `X402Allocations.balances`. */
+  balances?: () => Promise<readonly TaskMarketFundingBalance[]>;
+  /** Unpaid catalog reads. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+}
+const RESOLVED_CHARGES = ["none", "released", "settled", "manually_resolved"],
+  RESOLVED_STATES = ["completed", "failed"];
+const CATALOG_BYTES = 2 * 1024 * 1024,
+  REQUEST_BYTES = 8 * 1024 * 1024,
+  CATALOG_DEADLINE_MS = 15000;
+/** Never sends the request again for an ID the payer has seen: `purchase` maps every non-verified outcome to a terminal error. */
+export function createTaskMarketTransport(
+  options: TaskMarketTransportOptions,
+): XgateTransport & {
+  status(): Promise<unknown>;
+  reconcile(invocationId: string): Promise<unknown>;
+} {
+  const { payer } = options,
+    base = checkOrigin(options.origin),
+    fetcher = options.fetch ?? fetch;
+  if (payer.apiVersion !== 1) throw new XgateError("unsupported_payer_api");
+  const channel = async (
+    payment: TaskMarketPaymentSummary,
+  ): Promise<XgateChannelBalance | undefined> => {
+    if (!options.balances || payment.rail.kind !== "session") return;
+    try {
+      const matches = (await options.balances()).filter(
+        (b) =>
+          b.railId === payment.rail.id &&
+          b.network === payment.network &&
+          b.asset === payment.asset,
+      );
+      // Several sessions on one rail are not one channel; unlike balances are never summed.
+      if (matches.length !== 1) return;
+      const b = matches[0]!;
+      return {
+        depositingAtomic: b.depositing,
+        lockedAtomic: b.locked,
+        chargedAtomic: b.charged,
+        pendingAtomic: b.pending,
+        refundableAtomic: b.refundable,
+      };
+    } catch {
+      return; // Display only.
+    }
+  };
+  return {
+    async models(signal) {
+      const deadline = AbortSignal.timeout(CATALOG_DEADLINE_MS);
+      let response: Response;
+      try {
+        response = await fetcher(base + "/v1/models", {
+          signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+          redirect: "error",
+          cache: "no-store",
+          credentials: "omit",
+          referrerPolicy: "no-referrer",
+          headers: { accept: "application/json" },
+        });
+      } catch {
+        throw new XgateError("catalog_unavailable");
+      }
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        throw new XgateError("catalog_unavailable");
+      }
+      const v = parse(await bounded(response, CATALOG_BYTES));
+      if (!record(v) || !Array.isArray(v.data) || v.data.length > 128)
+        throw new XgateError("invalid_catalog");
+      return v.data
+        .filter(
+          (m: unknown) =>
+            record(m) &&
+            (options.models === undefined || options.models.includes(m.id)),
+        )
+        .map((m: Record<string, unknown>) => ({ ...m, xgate_origin: base }));
+    },
+    async purchase(invocation: Invocation, signal, onResponse) {
+      checkRoute(invocation.route);
+      const body = new TextEncoder().encode(invocation.body);
+      if (body.byteLength === 0 || body.byteLength > REQUEST_BYTES)
+        throw new XgateError("invalid_invocation");
+      const id = invocation.id;
+      let result: TaskMarketPayResult;
+      try {
+        result = await payer.request(
+          {
+            apiVersion: 1,
+            invocationId: id,
+            url: base + invocation.route,
+            method: "POST",
+            // Application headers only: the payer owns every payment header.
+            headers: {
+              "content-type": "application/json",
+              accept: "application/json",
+            },
+            body,
+            limits: { maxRequestBodyBytes: REQUEST_BYTES },
+            ...(options.allocationId !== undefined
+              ? { allocationId: options.allocationId }
+              : {}),
+            ...(options.policyRuleId !== undefined
+              ? { policyRuleId: options.policyRuleId }
+              : {}),
+            ...(options.nonInteractive !== undefined
+              ? { nonInteractive: options.nonInteractive }
+              : {}),
+          },
+          {
+            ...(signal ? { signal } : {}),
+            ...(options.confirmPayment
+              ? { confirmPayment: options.confirmPayment }
+              : {}),
+          },
+        );
+      } catch (error) {
+        throw failure(error, id);
+      }
+      const payment = result.payment;
+      if (result.invocationId !== id || result.apiVersion !== 1)
+        throw new XgatePurchaseError(
+          "payer_result_mismatch",
+          id,
+          true,
+          payment && display(payment),
+        );
+      // A paid xgate route never answers without a payment challenge.
+      if (!payment)
+        throw new XgatePurchaseError(
+          result.response.status === 200
+            ? "payment_missing"
+            : "request_rejected",
+          id,
+          false,
+        );
+      const shown = display(payment);
+      if (
+        payment.charge !== "settled" ||
+        typeof payment.settledAmount !== "string"
+      )
+        throw new XgatePurchaseError("payment_unverified", id, true, shown);
+      shown.chargedAtomic = payment.settledAmount;
+      try {
+        if (atomic(payment.settledAmount) > atomic(payment.authorizedAmount))
+          throw new XgateError("charge_over_authorization");
+      } catch {
+        throw new XgatePurchaseError("invalid_settlement", id, true, shown);
+      }
+      const r = result.response,
+        h = r.headers;
+      // Charged, so not pending, but the content is unusable.
+      if (
+        r.status !== 200 ||
+        !/^application\/json\b/i.test(r.contentType) ||
+        h["x-inference-privacy"] !== "anonymous" ||
+        h["x-result-retention"] !== "none" ||
+        !h["cache-control"]?.includes("no-store")
+      )
+        throw new XgatePurchaseError("response_rejected", id, false, shown);
+      let value: unknown;
+      try {
+        value = parse(r.body);
+      } catch {
+        throw new XgatePurchaseError("invalid_response", id, false, shown);
+      }
+      if (
+        !record(value) ||
+        typeof value.id !== "string" ||
+        value.result_replay_available !== undefined
+      )
+        throw new XgatePurchaseError("invalid_response", id, false, shown);
+      const head: XgateResponseHead = {
+        status: r.status,
+        headers: { "content-type": r.contentType, "cache-control": "no-store" },
+      };
+      try {
+        await onResponse?.(head);
+      } catch {
+        throw new XgatePurchaseError("response_hook_failed", id, false, shown);
+      }
+      const balance = await channel(payment);
+      if (balance) shown.channel = balance;
+      return {
+        body: value,
+        settlement: {
+          chargedAtomic: payment.settledAmount,
+          reference:
+            payment.transaction ?? payment.commitment ?? payment.paymentId,
+        },
+        purchase: payment.commitment ?? payment.paymentId,
+        payment: shown,
+      } satisfies XgatePurchaseResult;
+    },
+    async status() {
+      return {
+        transport: "taskmarket",
+        origin: base,
+        ...(options.balances
+          ? {
+              balances: (await options.balances()).map((b) => ({
+                rail: b.railId,
+                network: b.network,
+                asset: b.asset,
+                depositingAtomic: b.depositing,
+                lockedAtomic: b.locked,
+                chargedAtomic: b.charged,
+                pendingAtomic: b.pending,
+                refundableAtomic: b.refundable,
+              })),
+            }
+          : {}),
+      };
+    },
+    async reconcile(invocationId) {
+      const s = await payer.reconcile(invocationId);
+      return {
+        invocationId: s.invocationId,
+        state: s.state,
+        charge: s.charge,
+        uncertain: s.uncertain,
+        ...(s.errorCode ? { errorCode: s.errorCode } : {}),
+        ...(s.payment ? { payment: display(s.payment) } : {}),
+      };
+    },
+  };
+}
+function display(p: TaskMarketPaymentSummary): XgatePayment {
+  return {
+    network: p.network,
+    scheme: p.scheme,
+    asset: p.asset,
+    payTo: p.payTo,
+    rail: p.rail.kind,
+    authorizedAtomic: p.authorizedAmount,
+    ...(p.charge === "settled" && p.settledAmount !== undefined
+      ? { chargedAtomic: p.settledAmount }
+      : {}),
+    status: p.charge,
+    ...((p.transaction ?? p.commitment)
+      ? { reference: p.transaction ?? p.commitment }
+      : {}),
+  };
+}
+/**
+ * Maps a payer rejection. Only the stable code crosses into Pi; the payer's message may carry
+ * URLs or server text. A rejection that does not state `pending: false` counts as pending.
+ */
+function failure(error: unknown, id: string): XgatePurchaseError {
+  const e = error as {
+    code?: unknown;
+    pending?: unknown;
+    invocation?: { uncertain?: unknown; payment?: TaskMarketPaymentSummary };
+  };
+  const code =
+    typeof e?.code === "string" && /^[a-z0-9_]{1,64}$/.test(e.code)
+      ? e.code
+      : "payer_failed";
+  // A duplicate never sends again, but its recorded invocation may still be unresolved: only a
+  // positively resolved record counts as not pending.
+  const recorded = e?.invocation as
+    | { uncertain?: unknown; charge?: unknown; state?: unknown }
+    | undefined;
+  const pending =
+    e?.pending !== false ||
+    (recorded !== undefined &&
+      !(
+        recorded.uncertain === false &&
+        RESOLVED_CHARGES.includes(recorded.charge as string) &&
+        RESOLVED_STATES.includes(recorded.state as string)
+      ));
+  const summary = e?.invocation?.payment;
+  return new XgatePurchaseError(
+    code,
+    id,
+    pending,
+    record(summary) ? display(summary) : undefined,
+  );
+}
+async function bounded(response: Response, limit: number): Promise<Uint8Array> {
+  if (!response.body) throw new XgateError("invalid_catalog");
+  const reader = response.body.getReader(),
+    chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    for (;;) {
+      const part = await reader.read();
+      if (part.done) break;
+      length += part.value.byteLength;
+      if (length > limit) throw new XgateError("catalog_bound");
+      chunks.push(part.value);
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => {});
+    throw error instanceof XgateError
+      ? error
+      : new XgateError("catalog_unavailable");
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, length);
+}
+function parse(bytes: Uint8Array): unknown {
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new XgateError("invalid_response");
+  }
+}