@lucid-agents/pi-xgate 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/index.js

@@ -0,0 +1,7 @@
+// Supported entry point. Hosts build the provider around their own transport; the default
+// Pi extension (`./extension`) keeps the standalone wallet broker.
+export { createXgateProvider, invocationId, } from "./provider.js";
+export { XgatePurchaseError, } from "./transport.js";
+export { createXgateExtension, } from "./extension.js";
+export { XgateError } from "@lucid-agents/xgate-client/types";
+export { createTaskMarketTransport, } from "./taskmarket.js";

package/dist/provider.d.ts

@@ -0,0 +1,24 @@
+import { type Provider } from "@earendil-works/pi-ai";
+import { type PiContext } from "./codec.ts";
+import { type XgatePayment, type XgatePurchaseResult, type XgateTransport } from "./transport.ts";
+/** @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;
+}
+/** Stable across automatic retries and payload hooks; a changed paid payload cannot claim a new intent. */
+export declare function invocationId(model: string, context: PiContext, session: string): string;
+export declare function createXgateProvider(transport: XgateTransport, { sessionId: identity, onPaid, onPurchaseFailed, }?: XgateProviderOptions): Promise<Provider>;

package/dist/provider.js

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
+import { XgateError } from "@lucid-agents/xgate-client/types";
+import { catalogEntries, encode, decode } from "./codec.js";
+import { XgatePurchaseError, } from "./transport.js";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+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, context, session) {
+    // 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, { sessionId: identity = () => "standalone", onPaid, onPurchaseFailed, } = {}) {
+    let entries = catalogEntries(await transport.models());
+    const stream = (model, context, options = {}) => {
+        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 = {
+            role: "assistant",
+            provider: "xgate",
+            api: model.api,
+            model: model.id,
+            content: [],
+            usage: zero(),
+            stopReason: "pending",
+            timestamp: Date.now(),
+        };
+        let attempted, paid;
+        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;
+                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].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].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].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 = {
+                        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),
+        streamSimple: stream,
+    };
+}

package/dist/taskmarket.d.ts

@@ -0,0 +1,131 @@
+import { 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;
+}
+/** Never sends the request again for an ID the payer has seen: `purchase` maps every non-verified outcome to a terminal error. */
+export declare function createTaskMarketTransport(options: TaskMarketTransportOptions): XgateTransport & {
+    status(): Promise<unknown>;
+    reconcile(invocationId: string): Promise<unknown>;
+};
+export {};