castle-web-cli 0.4.102 → 0.4.103

package/dist/metering.d.ts

@@ -30,6 +30,24 @@ export declare function reportCursorRun(opts: {
     durationMs: number;
     ok: boolean;
 }): void;
+/** Mirrors `CastleBudgetResponse` in castle-sandboxes/shared. */
+export interface CastleBudget {
+    usedMicros: number;
+    limitMicros: number | null;
+    resetAtMs: number;
+    blocked: boolean;
+}
+/**
+ * The daily Castle-paid AI budget for the user this sandbox belongs to, or null
+ * when there is nothing to say: outside a sandbox, on a host whose proxy
+ * predates this route, or on any failure at all.
+ *
+ * Null means "don't gate, don't display" in every caller. The proxy is the
+ * actual enforcement point -- this read exists so a blocked user gets a
+ * sentence instead of a spawned agent failing against a 403, and so the editor
+ * can show the bar. Neither is worth failing a run over.
+ */
+export declare function fetchBudget(): Promise<CastleBudget | null>;
 export declare function meteringHeaders(opts: {
     deckDir: string;
     sessionId: string;

package/dist/metering.js

@@ -100,6 +100,48 @@ export function reportCursorRun(opts) {
         /* best-effort: metering must never surface in a finished run */
     });
 }
+// Path on the proxy that reports this sandbox's daily budget. Must match
+// CASTLE_BUDGET_PATH in castle-sandboxes/shared/src/index.ts.
+const CASTLE_BUDGET_PATH = "/castle/budget";
+// Read before a run starts, so it must not be able to hold one up for long.
+const BUDGET_FETCH_TIMEOUT_MS = 5_000;
+/**
+ * The daily Castle-paid AI budget for the user this sandbox belongs to, or null
+ * when there is nothing to say: outside a sandbox, on a host whose proxy
+ * predates this route, or on any failure at all.
+ *
+ * Null means "don't gate, don't display" in every caller. The proxy is the
+ * actual enforcement point -- this read exists so a blocked user gets a
+ * sentence instead of a spawned agent failing against a 403, and so the editor
+ * can show the bar. Neither is worth failing a run over.
+ */
+export async function fetchBudget() {
+    const base = process.env.CASTLE_LLM_PROXY_URL;
+    const token = process.env.CASTLE_LLM_PROXY_TOKEN;
+    if (!base || !token)
+        return null;
+    try {
+        const resp = await fetch(`${base}${CASTLE_BUDGET_PATH}`, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(BUDGET_FETCH_TIMEOUT_MS),
+        });
+        if (!resp.ok)
+            return null;
+        const body = (await resp.json());
+        if (typeof body?.usedMicros !== "number" || typeof body.blocked !== "boolean") {
+            return null;
+        }
+        return {
+            usedMicros: body.usedMicros,
+            limitMicros: typeof body.limitMicros === "number" ? body.limitMicros : null,
+            resetAtMs: typeof body.resetAtMs === "number" ? body.resetAtMs : 0,
+            blocked: body.blocked,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 export function meteringHeaders(opts) {
     if (opts.direct || !proxyInjected(opts.route))
         return {};

package/dist/native/openrouter.d.ts

@@ -11,6 +11,9 @@ export interface ORToolCall {
 export type ORContentPart = {
     type: "text";
     text: string;
+    cache_control?: {
+        type: "ephemeral";
+    };
 } | {
     type: "image_url";
     image_url: {

package/dist/native/openrouter.js

@@ -222,11 +222,65 @@ function finalizeToolCalls(pending) {
         };
     });
 }
+// Anthropic prompt caching is EXPLICIT: without `cache_control` breakpoints
+// nothing is cached, and a tool loop re-pays for its whole transcript every
+// call. (Google caches implicitly, which is why gemini showed a ~66% hit rate
+// here while sonnet showed 0%.) Measured: sonnet through this loop cost $8.10
+// uncached versus $2.27 through the claude CLI, which sets breakpoints itself.
+//
+// Two breakpoints, the most a growing transcript needs: the system message,
+// which never changes, and the tail of what we are about to send, so the NEXT
+// call finds this whole turn already cached. Anthropic matches the longest
+// cached prefix ending at a breakpoint.
+//
+// Only for providers that need the marker. Slugs that don't support it would
+// carry an uninterpreted field at best, and OpenRouter's docs scope
+// cache_control to Anthropic-family models.
+function needsExplicitCacheControl(model) {
+    return model.startsWith("anthropic/");
+}
+function markCached(message) {
+    const { content } = message;
+    if (typeof content === "string") {
+        if (!content)
+            return message;
+        return { ...message, content: [{ type: "text", text: content, cache_control: { type: "ephemeral" } }] };
+    }
+    if (!Array.isArray(content) || content.length === 0)
+        return message;
+    const parts = content.slice();
+    const last = parts[parts.length - 1];
+    if (last.type !== "text")
+        return message;
+    parts[parts.length - 1] = { ...last, cache_control: { type: "ephemeral" } };
+    return { ...message, content: parts };
+}
+function withCacheBreakpoints(messages, model) {
+    if (!needsExplicitCacheControl(model) || messages.length === 0)
+        return messages;
+    const out = messages.slice();
+    const systemIndex = out.findIndex((m) => m.role === "system");
+    if (systemIndex !== -1)
+        out[systemIndex] = markCached(out[systemIndex]);
+    const lastIndex = out.length - 1;
+    if (lastIndex !== systemIndex)
+        out[lastIndex] = markCached(out[lastIndex]);
+    return out;
+}
+// A hard thinking budget, when one is asked for, else the effort word. Read
+// from the environment rather than settings: this exists to A/B the two forms
+// against each other, and a run wants it applied to every call it makes.
+function reasoningField(effort) {
+    const cap = Number(process.env.CASTLE_REASONING_MAX_TOKENS);
+    if (Number.isFinite(cap) && cap > 0)
+        return { reasoning: { max_tokens: Math.floor(cap) } };
+    return effort ? { reasoning: { effort } } : {};
+}
 export async function streamChatCompletion(opts) {
     const body = {
         // Routing mode rides the slug as a suffix (see applyRoutingMode).
         model: applyRoutingMode(opts.model, opts.routing),
-        messages: opts.messages,
+        messages: withCacheBreakpoints(opts.messages, opts.model),
         stream: true,
         // Deprecated on OpenRouter's side (usage is always included now) but
         // harmless to send -- keeps this client correct against providers that
@@ -235,7 +289,14 @@ export async function streamChatCompletion(opts) {
         ...(opts.tools && opts.tools.length > 0 ? { tools: opts.tools } : {}),
         // See ORReasoningEffort / StreamChatOpts.reasoningEffort above for the
         // doc reference and the graceful-degradation guarantee this relies on.
-        ...(opts.reasoningEffort ? { reasoning: { effort: opts.reasoningEffort } } : {}),
+        //
+        // `effort` means different things per provider: Anthropic derives a thinking
+        // budget as a fraction of max_tokens, so it caps; Gemini 3 maps it straight
+        // to `thinkingLevel`, so it FLOORS. A hard `reasoning.max_tokens` is the one
+        // form that means the same thing everywhere, so it is available as an
+        // override for measuring that difference. OpenRouter treats the two as
+        // mutually exclusive -- send one or the other, never both.
+        ...reasoningField(opts.reasoningEffort),
         // Pin a provider tier when requested (see StreamChatOpts.providerTier).
         ...(opts.providerTier
             ? { provider: { order: [opts.providerTier], allow_fallbacks: true } }