@lucid-agents/pi-xgate 0.0.0-stage → 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

@@ -0,0 +1,313 @@
+import { createHash } from "node:crypto";
+import {
+  createAssistantMessageEventStream,
+  type AssistantMessage,
+  type Model,
+  type Provider,
+  type SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+import { XgateError } from "@lucid-agents/xgate-client/types";
+import { catalogEntries, encode, decode, type PiContext } from "./codec.ts";
+import {
+  XgatePurchaseError,
+  type XgatePayment,
+  type XgatePurchaseResult,
+  type XgateTransport,
+} from "./transport.ts";
+const hash = (value: string): string =>
+  createHash("sha256").update(value).digest("hex");
+/** @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,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+});
+/** Stable across automatic retries and payload hooks; a changed paid payload cannot claim a new intent. */
+export function invocationId(
+  model: string,
+  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,
+      model,
+      messages: context.messages.filter(
+        (m) =>
+          m.role !== "assistant" ||
+          !["error", "aborted"].includes(m.stopReason),
+      ),
+      ...legacy,
+    }),
+  );
+}
+export async function createXgateProvider(
+  transport: XgateTransport,
+  {
+    sessionId: identity = () => "standalone",
+    onPaid,
+    onPurchaseFailed,
+  }: XgateProviderOptions = {},
+): Promise<Provider> {
+  let entries = catalogEntries(await transport.models());
+  const stream = (
+    model: Model<any>,
+    context: PiContext,
+    options: SimpleStreamOptions = {},
+  ) => {
+    const events = createAssistantMessageEventStream();
+    const timeout = options.timeoutMs ?? 180000;
+    if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 180000)
+      options = { ...options, timeoutMs: 180000 };
+    const deadline = AbortSignal.timeout(
+      Math.min(options.timeoutMs ?? 180000, 180000),
+    );
+    options = {
+      ...options,
+      signal: options.signal
+        ? AbortSignal.any([options.signal, deadline])
+        : deadline,
+    };
+    const message: AssistantMessage = {
+      role: "assistant",
+      provider: "xgate",
+      api: model.api,
+      model: model.id,
+      content: [],
+      usage: zero(),
+      stopReason: "pending",
+      timestamp: Date.now(),
+    };
+    let attempted: string | undefined, paid: XgatePurchaseResult | undefined;
+    void (async () => {
+      try {
+        options.signal?.throwIfAborted();
+        const current = catalogEntries(await transport.models(options.signal)),
+          entry = current.find(
+            (e) => e.model.id === model.id && e.model.api === model.api,
+          );
+        if (!entry) throw new XgateError("model_not_qualified");
+        const original = encode(entry, context, {
+            ...options,
+            // Respect a lower Pi model override without exceeding live catalog limits.
+            maxTokens:
+              options.maxTokens ??
+              Math.min(4096, model.maxTokens, entry.model.maxTokens),
+          }),
+          replacement = await options.onPayload?.(
+            structuredClone(original),
+            model,
+          ),
+          payload = replacement === undefined ? original : (replacement as any);
+        const limit = entry.route.endsWith("/messages")
+          ? "max_tokens"
+          : "max_output_tokens";
+        if (
+          !payload ||
+          payload.model !== model.id ||
+          payload.stream !== false ||
+          payload[limit] !== original[limit] ||
+          JSON.stringify(payload.tools) !== JSON.stringify(original.tools) ||
+          (!entry.route.endsWith("/messages") && payload.store !== false)
+        )
+          throw new XgateError("payload_hook_changed_scope");
+        const body = JSON.stringify(payload);
+        if (Buffer.byteLength(body) > 8 * 1024 * 1024)
+          throw new XgateError("request_bound");
+        const id = invocationId(
+          model.id,
+          context,
+          options.sessionId ?? identity(),
+        );
+        let observed = false;
+        attempted = id;
+        const result = await transport.purchase(
+          { id, route: entry.route, body },
+          options.signal,
+          async (response) => {
+            observed = true;
+            await options.onResponse?.(response, model);
+          },
+        );
+        paid = result;
+        // In-process injected transports have no HTTP body; retain the observation hook there too.
+        if (!observed)
+          await options.onResponse?.(
+            {
+              status: 200,
+              headers: {
+                "content-type": "application/json",
+                "cache-control": "no-store",
+              },
+            },
+            model,
+          );
+        const value = decode(entry, result.body);
+        message.usage = value.usage;
+        message.responseId = value.responseId;
+        options.signal?.throwIfAborted();
+        events.push({ type: "start", partial: message });
+        for (const block of value.content) {
+          const contentIndex = message.content.length;
+          if (block.type === "text") {
+            message.content.push({ ...block, text: "" });
+            events.push({ type: "text_start", contentIndex, partial: message });
+            (message.content[contentIndex] as typeof block).text = block.text;
+            events.push({
+              type: "text_delta",
+              contentIndex,
+              delta: block.text,
+              partial: message,
+            });
+            events.push({
+              type: "text_end",
+              contentIndex,
+              content: block.text,
+              partial: message,
+            });
+          } else if (block.type === "thinking") {
+            message.content.push({
+              ...block,
+              thinking: block.redacted ? block.thinking : "",
+            });
+            events.push({
+              type: "thinking_start",
+              contentIndex,
+              partial: message,
+            });
+            if (!block.redacted) {
+              (message.content[contentIndex] as typeof block).thinking =
+                block.thinking;
+              events.push({
+                type: "thinking_delta",
+                contentIndex,
+                delta: block.thinking,
+                partial: message,
+              });
+            }
+            events.push({
+              type: "thinking_end",
+              contentIndex,
+              content: block.thinking,
+              partial: message,
+            });
+          } else {
+            message.content.push({ ...block, arguments: {} });
+            events.push({
+              type: "toolcall_start",
+              contentIndex,
+              partial: message,
+            });
+            (message.content[contentIndex] as typeof block).arguments =
+              block.arguments;
+            events.push({
+              type: "toolcall_delta",
+              contentIndex,
+              delta: JSON.stringify(block.arguments),
+              partial: message,
+            });
+            events.push({
+              type: "toolcall_end",
+              contentIndex,
+              toolCall: block,
+              partial: message,
+            });
+          }
+        }
+        message.stopReason = value.stopReason;
+        try {
+          onPaid?.(result);
+        } catch {
+          /* UI diagnostics cannot reverse verified completion. */
+        }
+        events.push({ type: "done", reason: value.stopReason, message });
+      } catch (error) {
+        const aborted = options.signal?.aborted === true;
+        message.stopReason = aborted ? "aborted" : "error";
+        message.errorMessage = aborted
+          ? "Xgate operation stopped. Inspect /xgate status; payment may require reconciliation."
+          : 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,
+          error: message,
+        });
+      } finally {
+        events.end();
+      }
+    })();
+    return events;
+  };
+  return {
+    id: "xgate",
+    name: "xgate",
+    auth: {
+      apiKey: {
+        name: "Policy constrained xgate wallet",
+        resolve: async () => ({ auth: {}, source: "xgate wallet broker" }),
+      },
+    },
+    getModels: () => entries.map((e) => e.model),
+    refreshModels: async (context) => {
+      if (!context.allowNetwork) return;
+      const updated = catalogEntries(await transport.models(context.signal));
+      await context.publish({
+        update: () => {
+          entries = updated;
+        },
+      });
+    },
+    stream: (model, context, options) =>
+      stream(model, context, options as SimpleStreamOptions),
+    streamSimple: stream,
+  };
+}