@lucid-agents/pi-xgate 0.1.6 → 0.1.8

package/README.md

@@ -10,10 +10,10 @@ reasoning signatures survive the full agent loop.
 
 The release package is `@lucid-agents/pi-xgate`. It includes the client dependency
 and the reviewed model-capability snapshot; the internal router contracts package
-is not required. With Node 24.19+ (below 25) and Pi 1.1.0:
+is not required. With Node 24.19 or later and Pi 1.1.0:
 
 ```sh
-pi install npm:@lucid-agents/pi-xgate@0.1.6
+pi install npm:@lucid-agents/pi-xgate@0.1.8
 ```
 
 For repository development before a release is available:
@@ -56,8 +56,21 @@ Both files must be regular, nonsymlink files with no group/other permissions.
 Select a model through `/model`. Only the broker policy's models with compatible
 live qualifications are offered. OpenAI requires the new
 `openai-anonymous-tools-v2` router profile; an older server will expose no OpenAI
-coding models. Anthropic requires `anthropic-anonymous-usage-v3` and uses only
-`anthropic_no_cache` native Messages scopes.
+coding models. Anthropic requires `anthropic-anonymous-usage-v3` native Messages
+scopes qualified as `anthropic_no_cache`, `anthropic_ephemeral_5m` or
+`anthropic_ephemeral_1h`.
+
+Anthropic caches a prompt only at explicit `cache_control` breakpoints. On a
+cache-qualified scope the provider marks, like Pi's direct Anthropic provider, the
+last tool, the system prompt and the newest user turn (three of Anthropic's four
+breakpoints), so each call in a conversation can read the prefix the previous call
+wrote. Breakpoints are five-minute `ephemeral` writes; Pi's `cacheRetention: "long"`
+selects one-hour writes only on an `anthropic_ephemeral_1h` scope, and
+`cacheRetention: "none"` sends none. An `anthropic_no_cache` scope gets no
+breakpoints, and cache usage it reports is rejected as an invalid result. The
+breakpoints carry no session ID or other key: the provider cache is keyed by the
+content prefix alone. Cache warming stays off, so no unpaid or extra paid call
+is made to keep a cache alive.
 An expired/revoked catalog scope cannot authorize payment just because Pi remembers
 an earlier model list: the provider refreshes before each invocation and the wallet
 client validates the actual quote again.

package/dist/codec.d.ts

@@ -1,10 +1,16 @@
 import type { AssistantMessage, Message, Model, SimpleStreamOptions, Tool, Usage } from "@earendil-works/pi-ai";
 import { type Route } from "@lucid-agents/xgate-client/types";
+/** The widest Anthropic prompt-cache write lifetime a scope's qualification permits. */
+export type CacheTtl = "none" | "5m" | "1h";
 export type Entry = {
     model: Model<any>;
     catalog: any;
     route: Route;
     efforts: string[];
+    /** Anthropic only: requests may carry `cache_control` breakpoints up to this lifetime. */
+    cache: CacheTtl;
+    /** Anthropic only: the per-million-token price of a one-hour cache write. */
+    cacheWrite1h: number;
 };
 export declare function catalogEntries(rows: any[]): Entry[];
 /**

package/dist/codec.js

@@ -2,6 +2,16 @@ 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);
@@ -44,7 +54,7 @@ export function catalogEntries(rows) {
         if (!q ||
             row.privacy?.revision !== "anonymous-volatile-v1" ||
             row.privacy.result_replay_available !== false ||
-            (anthropic && q.cache_mode !== "anthropic_no_cache"))
+            (anthropic && !Object.hasOwn(ANTHROPIC_CACHE, q.cache_mode)))
             continue;
         if (q.valid_until !== undefined &&
             Number(q.valid_until) * 1000 <= Date.now())
@@ -84,8 +94,13 @@ export function catalogEntries(rows) {
                     ["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",
@@ -107,9 +122,7 @@ export function catalogEntries(rows) {
                     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,
+                    cacheWrite: write5m ? rate(write5m) : 0,
                 },
                 inputLimits: { maxRequestBytes: 8 * 1024 * 1024 },
             },
@@ -301,23 +314,38 @@ export function encode(entry, context, options = {}) {
     need(history.length > 0 && history.length <= 256, "history_limit");
     let request;
     if (anthropic) {
-        const cap = entry.catalog.execution_profile.capabilities;
+        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 } : {}),
+            ...(system
+                ? {
+                    system: cache
+                        ? [{ type: "text", text: system, cache_control: cache }]
+                        : system,
+                }
+                : {}),
             ...(tools.length
                 ? {
-                    tools: tools.map((t) => ({
+                    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)
@@ -357,6 +385,13 @@ export function encode(entry, context, options = {}) {
     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;
@@ -483,14 +518,22 @@ export function decode(entry, body) {
         ? (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");
+        : (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 * rates.cacheWrite) / 1e6,
+        cacheWrite: ((write - write1h) * rates.cacheWrite + write1h * entry.cacheWrite1h) /
+            1e6,
         total: 0,
     };
     cost.total = cost.input + cost.output + cost.cacheRead + cost.cacheWrite;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucid-agents/pi-xgate",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "exports": {
     ".": {
@@ -32,14 +32,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@lucid-agents/xgate-client": "0.1.6"
+    "@lucid-agents/xgate-client": "0.1.8"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.85.1 || 1.1.0",
     "@earendil-works/pi-coding-agent": "0.85.1 || 1.1.0"
   },
   "engines": {
-    "node": ">=24.19 <25"
+    "node": ">=24.19"
   },
   "description": "Wallet-paid OpenAI and Anthropic inference through xgate for the Pi coding agent",
   "repository": {
@@ -56,10 +56,10 @@
     "registry": "https://registry.npmjs.org"
   },
   "license": "MIT",
-  "gitHead": "f26a9cdf35db07e8aa6b6ad7c6408884aa283ebc",
+  "gitHead": "d410140f8e57fd3fc4309a1c54772b8a9f99ccd9",
   "xgateRelease": {
-    "version": "v0.1.6",
-    "sourceSha": "f26a9cdf35db07e8aa6b6ad7c6408884aa283ebc",
-    "candidateId": "rc-f26a9cdf35db-38096296216-1"
+    "version": "v0.1.8",
+    "sourceSha": "d410140f8e57fd3fc4309a1c54772b8a9f99ccd9",
+    "candidateId": "rc-d410140f8e57-42908627975-1"
   }
 }

package/src/codec.ts

@@ -13,11 +13,27 @@ import type {
 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";
+/** The widest Anthropic prompt-cache write lifetime a scope's qualification permits. */
+export type CacheTtl = "none" | "5m" | "1h";
 export type Entry = {
   model: Model<any>;
   catalog: any;
   route: Route;
   efforts: string[];
+  /** Anthropic only: requests may carry `cache_control` breakpoints up to this lifetime. */
+  cache: CacheTtl;
+  /** Anthropic only: the per-million-token price of a one-hour cache write. */
+  cacheWrite1h: number;
+};
+/**
+ * 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: Record<string, CacheTtl> = {
+  anthropic_no_cache: "none",
+  anthropic_ephemeral_5m: "5m",
+  anthropic_ephemeral_1h: "1h",
 };
 const need = (x: unknown, code: string): void => {
   if (!x) throw new XgateError(code);
@@ -70,7 +86,7 @@ export function catalogEntries(rows: any[]): Entry[] {
       !q ||
       row.privacy?.revision !== "anonymous-volatile-v1" ||
       row.privacy.result_replay_available !== false ||
-      (anthropic && q.cache_mode !== "anthropic_no_cache")
+      (anthropic && !Object.hasOwn(ANTHROPIC_CACHE, q.cache_mode))
     )
       continue;
     if (
@@ -123,8 +139,13 @@ export function catalogEntries(rows: any[]): Entry[] {
           ["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",
@@ -146,9 +167,7 @@ export function catalogEntries(rows: any[]): Entry[] {
           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,
+          cacheWrite: write5m ? rate(write5m) : 0,
         },
         inputLimits: { maxRequestBytes: 8 * 1024 * 1024 },
       },
@@ -397,23 +416,39 @@ export function encode(
   need(history.length > 0 && history.length <= 256, "history_limit");
   let request: any;
   if (anthropic) {
-    const cap = entry.catalog.execution_profile.capabilities;
+    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 } : {}),
+      ...(system
+        ? {
+            system: cache
+              ? [{ type: "text", text: system, cache_control: cache }]
+              : system,
+          }
+        : {}),
       ...(tools.length
         ? {
-            tools: tools.map((t) => ({
+            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) {
@@ -456,6 +491,15 @@ export function encode(
   );
   return request;
 }
+function cacheControl(
+  qualified: CacheTtl,
+  retention: SimpleStreamOptions["cacheRetention"],
+): { type: "ephemeral"; ttl?: "1h" } | undefined {
+  if (qualified === "none" || retention === "none") return undefined;
+  return retention === "long" && qualified === "1h"
+    ? { type: "ephemeral", ttl: "1h" }
+    : { type: "ephemeral" };
+}
 function tokens(value: any): number {
   need(Number.isSafeInteger(value) && value >= 0, "invalid_usage");
   return value;
@@ -628,9 +672,17 @@ export function decode(
     ),
     totalInput = tokens(u.input_tokens),
     output = tokens(u.output_tokens),
-    input = anthropic ? totalInput : totalInput - read - write;
+    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 && (!anthropic || (read === 0 && write === 0)),
+    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;
@@ -638,7 +690,9 @@ export function decode(
     input: (input * rates.input) / 1e6,
     output: (output * rates.output) / 1e6,
     cacheRead: (read * rates.cacheRead) / 1e6,
-    cacheWrite: (write * rates.cacheWrite) / 1e6,
+    cacheWrite:
+      ((write - write1h) * rates.cacheWrite + write1h * entry.cacheWrite1h) /
+      1e6,
     total: 0,
   };
   cost.total = cost.input + cost.output + cost.cacheRead + cost.cacheWrite;