@lucid-agents/pi-xgate 0.0.0-stage → 0.1.6

package/src/codec.ts

@@ -0,0 +1,658 @@
+import * as pi from "@earendil-works/pi-ai";
+import type {
+  AssistantMessage,
+  Context,
+  Message,
+  Model,
+  SimpleStreamOptions,
+  Tool,
+  TranscriptContext,
+  Usage,
+  ThinkingLevelMap,
+} from "@earendil-works/pi-ai";
+import { XgateError, type Route } from "@lucid-agents/xgate-client/types";
+import capabilities from "./generated/openai-model-capabilities.json" with { type: "json" };
+import { createHash } from "node:crypto";
+export type Entry = {
+  model: Model<any>;
+  catalog: any;
+  route: Route;
+  efforts: string[];
+};
+const need = (x: unknown, code: string): void => {
+  if (!x) throw new XgateError(code);
+};
+const object = (x: any): boolean =>
+  x !== null && typeof x === "object" && !Array.isArray(x);
+const rate = (x: any): number => {
+  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: any[]): Entry[] {
+  need(Array.isArray(rows) && rows.length <= 128, "invalid_catalog");
+  const entries: Entry[] = [];
+  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 as any)[row.id];
+    if (!cap || (!anthropic && !cap.tools)) continue;
+    const op = anthropic ? "messages" : "responses";
+    const q = row.qualified_profiles.find(
+      (q: any) =>
+        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 && q.cache_mode !== "anthropic_no_cache")
+    )
+      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: string[] = anthropic ? cap.effort : cap.reasoning_efforts;
+    const levels = [
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+    ] as const;
+    const thinkingLevelMap: 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;
+    }
+    entries.push({
+      catalog: row,
+      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: p.rates.input_cache_write
+            ? rate(p.rates.input_cache_write)
+            : 0,
+        },
+        inputLimits: { maxRequestBytes: 8 * 1024 * 1024 },
+      },
+    });
+  }
+  return entries;
+}
+/**
+ * Pi 1.1 passes a normalized transcript; Pi 0.85 passes `systemPrompt` and `tools` beside the
+ * messages. Structural, so published types do not name a type only one Pi version has.
+ */
+export type PiContext = {
+  messages: Message[];
+  systemPrompt?: string;
+  tools?: Tool[];
+};
+type Turn = Exclude<Message, { role: "system" }>;
+export function transcript(context: PiContext): {
+  system: string;
+  tools: Tool[];
+  messages: Turn[];
+} {
+  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 as Context;
+    return {
+      system: raw.systemPrompt ?? "",
+      tools: raw.tools ?? [],
+      messages: raw.messages as Turn[],
+    };
+  }
+  const collapsed = pi.collapseSystemMessages(
+    legacy
+      ? pi.normalizeContext(context as Context)
+      : (context as TranscriptContext),
+  );
+  return {
+    system: pi.getCurrentSystemPrompt(collapsed.messages),
+    tools: pi.getCurrentTools(collapsed.messages),
+    messages: collapsed.messages.filter((m): m is Turn => m.role !== "system"),
+  };
+}
+function text(content: any): string {
+  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: any) => b.text).join("\n");
+}
+function callId(id: string): string {
+  return /^[A-Za-z0-9_:.\-]{1,128}$/.test(id)
+    ? id
+    : "call_" + createHash("sha256").update(id).digest("hex").slice(0, 40);
+}
+function validateTools(tools: any[], anthropic: boolean): void {
+  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: Entry,
+  context: PiContext,
+  options: SimpleStreamOptions = {},
+): any {
+  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: any[] = [];
+  const append = (role: string, content: any[]) => {
+    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: any[] = [];
+    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: any;
+          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: any;
+  if (anthropic) {
+    const cap = entry.catalog.execution_profile.capabilities;
+    request = {
+      model: entry.model.id,
+      messages: history,
+      max_tokens: max,
+      stream: false,
+      ...(system ? { system } : {}),
+      ...(tools.length
+        ? {
+            tools: tools.map((t) => ({
+              name: t.name,
+              description: t.description,
+              input_schema: t.parameters,
+            })),
+          }
+        : {}),
+    };
+    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 tokens(value: any): number {
+  need(Number.isSafeInteger(value) && value >= 0, "invalid_usage");
+  return value;
+}
+export function decode(
+  entry: Entry,
+  body: any,
+): {
+  content: AssistantMessage["content"];
+  usage: Usage;
+  stopReason: "stop" | "toolUse";
+  responseId: string;
+} {
+  need(
+    object(body) && typeof body.id === "string" && object(body.usage),
+    "invalid_result",
+  );
+  const anthropic = entry.route.endsWith("/messages"),
+    content: AssistantMessage["content"] = [];
+  let stopReason: "stop" | "toolUse";
+  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 as any)[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: any) => {
+            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;
+  need(
+    input >= 0 && (!anthropic || (read === 0 && write === 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 * rates.cacheWrite) / 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,
+  };
+}