@lucid-agents/pi-xgate 0.1.5 → 0.1.7

package/dist/codec.js

@@ -0,0 +1,553 @@
+import * as pi from "@earendil-works/pi-ai";
+import { XgateError } from "@lucid-agents/xgate-client/types";
+import capabilities from "./generated/openai-model-capabilities.json" with { type: "json" };
+import { createHash } from "node:crypto";
+/**
+ * The router quotes the class a request's `cache_control` markers select, and serves it only
+ * when the scope's qualification covers that class. A wider qualification covers narrower
+ * requests, so a cache-qualified scope still serves a request without markers.
+ */
+const ANTHROPIC_CACHE = {
+    anthropic_no_cache: "none",
+    anthropic_ephemeral_5m: "5m",
+    anthropic_ephemeral_1h: "1h",
+};
+const need = (x, code) => {
+    if (!x)
+        throw new XgateError(code);
+};
+const object = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const rate = (x) => {
+    need(x &&
+        typeof x.numerator === "string" &&
+        /^[0-9]{1,13}$/.test(x.numerator) &&
+        Number(x.numerator) <= 1e12 &&
+        Number.isSafeInteger(x.denominator) &&
+        x.denominator > 0 &&
+        x.denominator <= 1e6, "invalid_catalog_rate");
+    return Number(x.numerator) / x.denominator;
+};
+export function catalogEntries(rows) {
+    need(Array.isArray(rows) && rows.length <= 128, "invalid_catalog");
+    const entries = [];
+    for (const row of rows) {
+        const p = row?.execution_profile;
+        if (!object(p) ||
+            p.model !== row.id ||
+            !Array.isArray(row.qualified_profiles))
+            continue;
+        const anthropic = row.owned_by === "anthropic", cap = anthropic ? p.capabilities : capabilities[row.id];
+        if (!cap || (!anthropic && !cap.tools))
+            continue;
+        const op = anthropic ? "messages" : "responses";
+        const q = row.qualified_profiles.find((q) => q.model === row.id &&
+            q.operation === op &&
+            q.provider === (anthropic ? "anthropic" : "open_ai") &&
+            q.normalizer_revision ===
+                (anthropic
+                    ? "anthropic-anonymous-usage-v3"
+                    : "openai-anonymous-usage-v1") &&
+            q.transformation_revision ===
+                (anthropic
+                    ? "anthropic-anonymous-messages-v1"
+                    : "openai-anonymous-tools-v2"));
+        if (!q ||
+            row.privacy?.revision !== "anonymous-volatile-v1" ||
+            row.privacy.result_replay_available !== false ||
+            (anthropic && !Object.hasOwn(ANTHROPIC_CACHE, q.cache_mode)))
+            continue;
+        if (q.valid_until !== undefined &&
+            Number(q.valid_until) * 1000 <= Date.now())
+            continue;
+        if (row.lifecycle?.stop_before != null &&
+            Number(row.lifecycle.stop_before) * 1000 <= Date.now())
+            continue;
+        const contextWindow = Math.min(p.max_input_tokens, p.provider_limits?.context_window ??
+            cap.context_window ??
+            p.max_input_tokens), maxTokens = Math.min(8192, p.max_output_tokens);
+        need(Number.isSafeInteger(contextWindow) &&
+            contextWindow > 0 &&
+            Number.isSafeInteger(maxTokens) &&
+            maxTokens > 0, "invalid_catalog_limits");
+        const efforts = anthropic ? cap.effort : cap.reasoning_efforts;
+        const levels = [
+            "minimal",
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "max",
+        ];
+        const thinkingLevelMap = {
+            off: anthropic
+                ? cap.thinking.disabled
+                    ? "disabled"
+                    : null
+                : efforts.length === 0 || efforts.includes("none")
+                    ? "none"
+                    : null,
+        };
+        for (const level of levels) {
+            const allowed = efforts.includes(level) ||
+                (anthropic &&
+                    cap.thinking.enabled &&
+                    ["minimal", "low", "medium", "high"].includes(level));
+            thinkingLevelMap[level] = allowed ? level : null;
+        }
+        const write5m = p.rates.input_cache_write_5m ?? p.rates.input_cache_write;
+        entries.push({
+            catalog: row,
+            cache: anthropic ? ANTHROPIC_CACHE[q.cache_mode] : "none",
+            cacheWrite1h: p.rates.input_cache_write_1h
+                ? rate(p.rates.input_cache_write_1h)
+                : 0,
+            route: anthropic
+                ? "/providers/anthropic/v1/messages"
+                : "/providers/openai/v1/responses",
+            efforts,
+            model: {
+                id: row.id,
+                name: `${row.id} (xgate)`,
+                api: anthropic ? "xgate-messages" : "xgate-responses",
+                provider: "xgate",
+                baseUrl: row.xgate_origin ?? "https://api.xgate.run",
+                input: ["text"],
+                contextWindow,
+                maxTokens,
+                reasoning: anthropic
+                    ? Boolean(cap.thinking?.adaptive || cap.thinking?.enabled)
+                    : efforts.some((effort) => effort !== "none"),
+                thinkingLevelMap,
+                cost: {
+                    input: rate(p.rates.input_uncached),
+                    output: rate(p.rates.output),
+                    cacheRead: rate(p.rates.input_cache_read),
+                    cacheWrite: write5m ? rate(write5m) : 0,
+                },
+                inputLimits: { maxRequestBytes: 8 * 1024 * 1024 },
+            },
+        });
+    }
+    return entries;
+}
+export function transcript(context) {
+    const legacy = "systemPrompt" in context || "tools" in context;
+    if (typeof pi.collapseSystemMessages !== "function") {
+        need(!context.messages.some((m) => m.role === "system"), "unsupported_context");
+        const raw = context;
+        return {
+            system: raw.systemPrompt ?? "",
+            tools: raw.tools ?? [],
+            messages: raw.messages,
+        };
+    }
+    const collapsed = pi.collapseSystemMessages(legacy
+        ? pi.normalizeContext(context)
+        : context);
+    return {
+        system: pi.getCurrentSystemPrompt(collapsed.messages),
+        tools: pi.getCurrentTools(collapsed.messages),
+        messages: collapsed.messages.filter((m) => m.role !== "system"),
+    };
+}
+function text(content) {
+    if (typeof content === "string")
+        return content;
+    need(Array.isArray(content) &&
+        content.every((b) => b.type === "text" && typeof b.text === "string"), "text_only_request");
+    return content.map((b) => b.text).join("\n");
+}
+function callId(id) {
+    return /^[A-Za-z0-9_:.\-]{1,128}$/.test(id)
+        ? id
+        : "call_" + createHash("sha256").update(id).digest("hex").slice(0, 40);
+}
+function validateTools(tools, anthropic) {
+    need(tools.length <= (anthropic ? 32 : 8), "too_many_tools");
+    need(tools.every((t) => /^[A-Za-z0-9_-]{1,64}$/.test(t.name) &&
+        object(t.parameters) &&
+        t.parameters.type === "object"), "unsupported_tool_schema");
+    need(new Set(tools.map((t) => t.name)).size === tools.length, "duplicate_tools");
+}
+export function encode(entry, context, options = {}) {
+    need(options.toolChoice === undefined || options.toolChoice === "auto", "unsupported_tool_choice");
+    need(options.reasoning === undefined || typeof options.reasoning === "string", "unsupported_reasoning");
+    need(options.temperature === undefined &&
+        (!options.samplingParams ||
+            Object.keys(options.samplingParams).length === 0), "unsupported_sampling");
+    const anthropic = entry.route.endsWith("/messages"), { system, tools, messages } = transcript(context);
+    validateTools(tools, anthropic);
+    const max = options.maxTokens ?? Math.min(4096, entry.model.maxTokens);
+    need(Number.isSafeInteger(max) && max > 0 && max <= entry.model.maxTokens, "output_limit");
+    const requested = options.reasoning, effort = requested && entry.efforts.includes(requested)
+        ? requested
+        : entry.efforts[0];
+    if (requested)
+        need(entry.model.thinkingLevelMap?.[requested] !== null &&
+            (entry.efforts.includes(requested) ||
+                (anthropic &&
+                    entry.catalog.execution_profile.capabilities.thinking.enabled)), "unsupported_reasoning");
+    const history = [];
+    const append = (role, content) => {
+        const previous = history.at(-1);
+        if (previous?.role === role)
+            previous.content.push(...content);
+        else
+            history.push({ role, content });
+    };
+    if (!anthropic && system)
+        history.push({ role: "system", content: system });
+    for (const message of messages) {
+        if (message.role === "user") {
+            const value = text(message.content);
+            if (anthropic)
+                append("user", [{ type: "text", text: value }]);
+            else
+                history.push({ role: "user", content: value });
+            continue;
+        }
+        if (message.role === "toolResult") {
+            const value = text(message.content), id = callId(message.toolCallId);
+            if (anthropic)
+                append("user", [
+                    {
+                        type: "tool_result",
+                        tool_use_id: id,
+                        content: value,
+                        ...(message.isError ? { is_error: true } : {}),
+                    },
+                ]);
+            else
+                history.push({
+                    type: "function_call_output",
+                    call_id: id,
+                    output: message.isError ? "Tool error: " + value : value,
+                });
+            continue;
+        }
+        need(message.role === "assistant", "unsupported_message");
+        if (message.stopReason === "error" || message.stopReason === "aborted")
+            continue;
+        const same = message.provider === "xgate" &&
+            message.model === entry.model.id &&
+            message.api === entry.model.api;
+        const blocks = [];
+        for (const block of message.content) {
+            if (block.type === "text") {
+                if (anthropic) {
+                    if (block.text)
+                        blocks.push({ type: "text", text: block.text });
+                }
+                else if (block.text) {
+                    let signature;
+                    try {
+                        signature = block.textSignature
+                            ? JSON.parse(block.textSignature)
+                            : undefined;
+                    }
+                    catch { }
+                    const previous = history.at(-1);
+                    if (same &&
+                        signature?.id &&
+                        previous?.type === "message" &&
+                        previous.id === signature.id &&
+                        previous.phase === signature.phase) {
+                        previous.content.push({ type: "output_text", text: block.text });
+                        continue;
+                    }
+                    history.push({
+                        type: "message",
+                        role: "assistant",
+                        content: [{ type: "output_text", text: block.text }],
+                        ...(same && signature?.id
+                            ? {
+                                id: signature.id,
+                                ...(signature.phase ? { phase: signature.phase } : {}),
+                            }
+                            : {}),
+                    });
+                }
+            }
+            else if (block.type === "toolCall") {
+                need(!block.namespace && object(block.arguments), "unsupported_tool_call");
+                const id = callId(block.id);
+                if (anthropic) {
+                    need(tools.some((t) => t.name === block.name), "history_tool_not_declared");
+                    blocks.push({
+                        type: "tool_use",
+                        id,
+                        name: block.name,
+                        input: block.arguments,
+                    });
+                }
+                else
+                    history.push({
+                        type: "function_call",
+                        call_id: id,
+                        name: block.name,
+                        arguments: JSON.stringify(block.arguments),
+                    });
+            }
+            else if (block.type === "thinking" && same) {
+                if (anthropic) {
+                    need(typeof block.thinkingSignature === "string" &&
+                        block.thinkingSignature.length > 0, "missing_thinking_signature");
+                    blocks.push(block.redacted
+                        ? { type: "redacted_thinking", data: block.thinkingSignature }
+                        : {
+                            type: "thinking",
+                            thinking: block.thinking,
+                            signature: block.thinkingSignature,
+                        });
+                }
+                else if (block.thinkingSignature) {
+                    const reasoning = JSON.parse(block.thinkingSignature);
+                    need(reasoning.type === "reasoning" &&
+                        typeof reasoning.encrypted_content === "string", "invalid_reasoning_history");
+                    history.push(reasoning);
+                }
+            }
+        }
+        if (anthropic && blocks.length)
+            append("assistant", blocks);
+    }
+    need(history.length > 0 && history.length <= 256, "history_limit");
+    let request;
+    if (anthropic) {
+        const cap = entry.catalog.execution_profile.capabilities, cache = cacheControl(entry.cache, options.cacheRetention);
+        request = {
+            model: entry.model.id,
+            messages: history,
+            max_tokens: max,
+            stream: false,
+            ...(system
+                ? {
+                    system: cache
+                        ? [{ type: "text", text: system, cache_control: cache }]
+                        : system,
+                }
+                : {}),
+            ...(tools.length
+                ? {
+                    tools: tools.map((t, i) => ({
+                        name: t.name,
+                        description: t.description,
+                        input_schema: t.parameters,
+                        ...(cache && i === tools.length - 1
+                            ? { cache_control: cache }
+                            : {}),
+                    })),
+                }
+                : {}),
+        };
+        // Anthropic caches nothing without a breakpoint. Like Pi's direct Anthropic provider, mark
+        // the tools, the system prompt and the newest turn: the next request in the conversation
+        // reads the whole previous prefix. A final user turn ends in text or a tool result.
+        const last = history.at(-1);
+        if (cache && last.role === "user")
+            last.content.at(-1).cache_control = cache;
+        if (effort)
+            request.output_config = { effort };
+        if (cap.thinking.adaptive)
+            request.thinking = { type: "adaptive" };
+        else if (requested && cap.thinking.enabled) {
+            need(max > 1024, "thinking_output_limit");
+            request.thinking = {
+                type: "enabled",
+                budget_tokens: Math.min(2048, max - 1),
+            };
+        }
+    }
+    else
+        request = {
+            model: entry.model.id,
+            input: history,
+            max_output_tokens: max,
+            stream: false,
+            store: false,
+            include: ["reasoning.encrypted_content"],
+            ...(effort ? { reasoning: { effort } } : {}),
+            ...(tools.length
+                ? {
+                    tools: tools.map((t) => ({
+                        type: "function",
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.parameters,
+                    })),
+                    parallel_tool_calls: false,
+                }
+                : {}),
+        };
+    if (request.tools)
+        need(Buffer.byteLength(JSON.stringify(request.tools)) <=
+            (anthropic ? 65536 : 8192), "tool_schema_bound");
+    need(Buffer.byteLength(JSON.stringify(request)) <= 8 * 1024 * 1024, "request_bound");
+    return request;
+}
+function cacheControl(qualified, retention) {
+    if (qualified === "none" || retention === "none")
+        return undefined;
+    return retention === "long" && qualified === "1h"
+        ? { type: "ephemeral", ttl: "1h" }
+        : { type: "ephemeral" };
+}
+function tokens(value) {
+    need(Number.isSafeInteger(value) && value >= 0, "invalid_usage");
+    return value;
+}
+export function decode(entry, body) {
+    need(object(body) && typeof body.id === "string" && object(body.usage), "invalid_result");
+    const anthropic = entry.route.endsWith("/messages"), content = [];
+    let stopReason;
+    if (anthropic) {
+        need(body.type === "message" &&
+            body.role === "assistant" &&
+            body.model === entry.model.id &&
+            ["end_turn", "tool_use", "stop_sequence"].includes(body.stop_reason) &&
+            Array.isArray(body.content), "invalid_result");
+        stopReason = body.stop_reason === "tool_use" ? "toolUse" : "stop";
+        for (const b of body.content) {
+            if (b.type === "text") {
+                need(typeof b.text === "string", "invalid_text");
+                content.push({ type: "text", text: b.text });
+            }
+            else if (b.type === "tool_use") {
+                need(typeof b.id === "string" &&
+                    typeof b.name === "string" &&
+                    object(b.input), "invalid_tool_result");
+                content.push({
+                    type: "toolCall",
+                    id: b.id,
+                    name: b.name,
+                    arguments: b.input,
+                });
+            }
+            else if (b.type === "thinking") {
+                need(typeof b.thinking === "string" && typeof b.signature === "string", "invalid_thinking");
+                content.push({
+                    type: "thinking",
+                    thinking: b.thinking,
+                    thinkingSignature: b.signature,
+                });
+            }
+            else if (b.type === "redacted_thinking") {
+                need(typeof b.data === "string", "invalid_thinking");
+                content.push({
+                    type: "thinking",
+                    thinking: "",
+                    thinkingSignature: b.data,
+                    redacted: true,
+                });
+            }
+            else
+                throw new XgateError("unsupported_result_block");
+        }
+    }
+    else {
+        const cap = capabilities[entry.model.id];
+        need(cap.response_models.includes(body.model) &&
+            body.status === "completed" &&
+            !body.error &&
+            !body.incomplete_details &&
+            Array.isArray(body.output), "invalid_result");
+        stopReason = "stop";
+        for (const b of body.output) {
+            if (b.type === "message") {
+                need(b.status === "completed" && Array.isArray(b.content), "invalid_result");
+                for (const t of b.content) {
+                    need(t.type === "output_text" && typeof t.text === "string", "invalid_text");
+                    content.push({
+                        type: "text",
+                        text: t.text,
+                        ...(b.id
+                            ? {
+                                textSignature: JSON.stringify({
+                                    v: 1,
+                                    id: b.id,
+                                    ...(b.phase ? { phase: b.phase } : {}),
+                                }),
+                            }
+                            : {}),
+                    });
+                }
+            }
+            else if (b.type === "function_call") {
+                need(typeof b.call_id === "string" &&
+                    typeof b.name === "string" &&
+                    typeof b.arguments === "string", "invalid_tool_result");
+                const args = JSON.parse(b.arguments);
+                need(object(args), "invalid_tool_result");
+                content.push({
+                    type: "toolCall",
+                    id: b.call_id,
+                    name: b.name,
+                    arguments: args,
+                });
+                stopReason = "toolUse";
+            }
+            else if (b.type === "reasoning") {
+                need(Array.isArray(b.summary), "invalid_thinking");
+                const summary = b.summary
+                    .map((s) => {
+                    need(s.type === "summary_text" && typeof s.text === "string", "invalid_thinking");
+                    return s.text;
+                })
+                    .join("\n");
+                need(typeof b.encrypted_content === "string" &&
+                    b.encrypted_content.length > 0, "missing_encrypted_reasoning");
+                content.push({
+                    type: "thinking",
+                    thinking: summary,
+                    thinkingSignature: JSON.stringify({
+                        type: "reasoning",
+                        id: b.id,
+                        summary: b.summary,
+                        encrypted_content: b.encrypted_content,
+                        ...(b.status === "completed" ? { status: b.status } : {}),
+                    }),
+                });
+            }
+            else
+                throw new XgateError("unsupported_result_block");
+        }
+    }
+    need(content.some((c) => (c.type === "text" && c.text.length > 0) || c.type === "toolCall"), "empty_result");
+    need((stopReason === "toolUse") === content.some((c) => c.type === "toolCall"), "tool_stop_mismatch");
+    const u = body.usage, read = tokens(anthropic
+        ? (u.cache_read_input_tokens ?? 0)
+        : u.input_tokens_details?.cached_tokens), write = tokens(anthropic
+        ? (u.cache_creation_input_tokens ?? 0)
+        : (u.input_tokens_details?.cache_write_tokens ?? 0)), totalInput = tokens(u.input_tokens), output = tokens(u.output_tokens), input = anthropic ? totalInput : totalInput - read - write, 
+    // Anthropic splits writes by lifetime; an unsplit write is the default five minutes.
+    write1h = anthropic && object(u.cache_creation)
+        ? tokens(u.cache_creation.ephemeral_1h_input_tokens ?? 0)
+        : 0;
+    need(input >= 0 &&
+        write1h <= write &&
+        (!anthropic || entry.cache !== "none" || (read === 0 && write === 0)) &&
+        (!anthropic || entry.cache === "1h" || write1h === 0), "cache_usage_mismatch");
+    const rates = entry.model.cost;
+    const cost = {
+        input: (input * rates.input) / 1e6,
+        output: (output * rates.output) / 1e6,
+        cacheRead: (read * rates.cacheRead) / 1e6,
+        cacheWrite: ((write - write1h) * rates.cacheWrite + write1h * entry.cacheWrite1h) /
+            1e6,
+        total: 0,
+    };
+    cost.total = cost.input + cost.output + cost.cacheRead + cost.cacheWrite;
+    return {
+        content,
+        usage: {
+            input,
+            output,
+            cacheRead: read,
+            cacheWrite: write,
+            totalTokens: input + read + write + output,
+            cost,
+        },
+        stopReason,
+        responseId: body.id,
+    };
+}

package/dist/extension.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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>);
+}
+/** Rail-neutral: atomic units of the named asset; decimals are not assumed. */
+export declare function paymentStatus(p: XgatePayment): string;
+/** Pi extension factory. The default export is the standalone wallet-broker extension. */
+export declare function createXgateExtension(options?: XgateExtensionOptions): (pi: ExtensionAPI) => Promise<void>;
+declare const _default: (pi: ExtensionAPI) => Promise<void>;
+export default _default;