castle-web-cli 0.4.185 → 0.4.186

package/dist/agent.js

@@ -31,7 +31,7 @@ import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, pl
 import { readCastleJson } from './castleJson.js';
 import { checkOpenrouterKey, checkOpenrouterModel, primeOpenrouterCatalog, } from './openrouter-catalog.js';
 import { classifyProviderError, failureCopy, setReaderTimeZone, } from './agent-failures.js';
-import { castleCreditsExhausted, createRefreshQueue, fetchAiCredits, fetchBudget, freeRolesFor, freeTierForRoles, meteringHeaders, modelIsFree, newAgentSessionId, spendableMicros, withCustomHeaders, } from './metering.js';
+import { castleCreditsExhausted, createBudgetRefreshRetry, createRefreshQueue, fetchAiCredits, fetchBudget, freeRolesFor, freeTierForRoles, meteringHeaders, modelIsFree, newAgentSessionId, spendableMicros, withCustomHeaders, } from './metering.js';
 import { anthropicKeyHelperCommand, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from './byo-auth.js';
 import { accountsSnapshot, loginProviderFor, watchCredentials, writeCredential, } from './byo-accounts.js';
 import { cancelLogin, logout, startLogin, submitLoginCode } from './byo-login.js';
@@ -1537,17 +1537,20 @@ function createUsageFeed(opts) {
     let latest = null;
     let credits = null;
     let budgetPolls = 0;
-    async function readUsage(refreshCredits = false) {
+    let stopped = false;
+    async function readUsage(refreshCredits = false, allowFollowUp = true) {
         const settings = opts.settings();
         if (!anyRoleIsCastlePaid(settings)) {
             credits = null;
-            return null;
+            return { usage: null, refreshAfterMs: null, allowFollowUp };
         }
         // Budget is the authoritative spendable amount and its read can force a
         // stale proxy gate to sync after a purchase. Read credits second so the
         // descriptive fields (plan, rate, reload state) describe that same or a
         // newer account snapshot instead of racing ahead of the gate refresh.
-        const budget = await fetchBudget();
+        // Only a full credit-state refresh asks the host to sync its held budget. Cheap polls and
+        // spend preflight stay local to the proxy, so control-plane health cannot delay a run.
+        const budget = await fetchBudget(refreshCredits);
         if (refreshCredits) {
             const nextCredits = await fetchAiCredits();
             // Once the richer field has loaded, a transient GraphQL failure should
@@ -1555,7 +1558,11 @@ function createUsageFeed(opts) {
             if (nextCredits)
                 credits = nextCredits;
         }
-        return usageFrame(budget, credits, settings);
+        return {
+            usage: usageFrame(budget, credits, settings),
+            refreshAfterMs: budget?.refreshAfterMs ?? null,
+            allowFollowUp,
+        };
     }
     function publishUsage(next) {
         if (JSON.stringify(next ?? null) === JSON.stringify(latest ?? null))
@@ -1563,11 +1570,24 @@ function createUsageFeed(opts) {
         latest = next;
         opts.broadcast({ type: 'usage', usage: next });
     }
+    function publishRead(read) {
+        if (stopped)
+            return;
+        publishUsage(read.usage);
+        if (!read.allowFollowUp || read.refreshAfterMs === null)
+            return;
+        budgetRetry.schedule(read.refreshAfterMs);
+    }
     // Focus, host relay, popover-open and run-finished can all arrive together.
-    const refreshQueue = createRefreshQueue({ read: readUsage, publish: publishUsage });
-    const requestRefresh = (withCredits) => {
-        void refreshQueue.request(withCredits);
-    };
+    const refreshQueue = createRefreshQueue({ read: readUsage, publish: publishRead });
+    const budgetRetry = createBudgetRefreshRetry(() => requestRefresh(true, false, false));
+    function requestRefresh(withCredits, allowFollowUp = withCredits, supersedeRetry = allowFollowUp) {
+        if (stopped)
+            return;
+        if (supersedeRetry)
+            budgetRetry.cancel();
+        void refreshQueue.request(withCredits, allowFollowUp);
+    }
     const refresh = () => requestRefresh(true);
     const stopRunWatch = onAgentRunFinished(refresh);
     const timer = setInterval(() => {
@@ -1582,8 +1602,10 @@ function createUsageFeed(opts) {
         latest: () => latest,
         refresh,
         stop: () => {
+            stopped = true;
             stopRunWatch();
             clearInterval(timer);
+            budgetRetry.dispose();
         },
     };
 }

package/dist/metering.d.ts

@@ -20,6 +20,7 @@ export interface CastleBudget {
     limitMicros: number | null;
     resetAtMs: number;
     blocked: boolean;
+    refreshAfterMs?: number;
     blockedModelPrefixes: string[];
     freeModelPrefixes: string[];
 }
@@ -84,10 +85,16 @@ export declare function freeRolesFor(spends: readonly RoleSpend[], prefixes: rea
  * calls: a cheap poll cannot downgrade a pending user-requested full refresh.
  */
 export declare function createRefreshQueue<T>(opts: {
-    read: (withFullState: boolean) => Promise<T>;
+    read: (withFullState: boolean, allowFollowUp: boolean) => Promise<T>;
     publish: (value: T) => void;
 }): {
-    request: (withFullState: boolean) => Promise<void>;
+    request: (withFullState: boolean, allowFollowUp?: boolean) => Promise<void>;
+};
+export declare function budgetRefreshDelay(value: unknown): number | null;
+export declare function createBudgetRefreshRetry(run: () => void): {
+    schedule: (afterMs: unknown) => void;
+    cancel: () => void;
+    dispose: () => void;
 };
 export declare function castleCreditsExhausted(budget: CastleBudget, credits: AiCredits | null): boolean;
 /** Rich credit state, or null when ghost/proxy cannot provide the new field. */
@@ -102,7 +109,7 @@ export declare function fetchAiCredits(): Promise<AiCredits | null>;
  * 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 fetchBudget(forceRefresh?: boolean): Promise<CastleBudget | null>;
 export declare function meteringHeaders(opts: {
     deckDir: string;
     sessionId: string;

package/dist/metering.js

@@ -63,6 +63,7 @@ const CASTLE_BUDGET_PATH = "/castle/budget";
 const CASTLE_API_PATH = "/castle/api/graphql";
 // Read before a run starts, so it must not be able to hold one up for long.
 const BUDGET_FETCH_TIMEOUT_MS = 5_000;
+const MAX_BUDGET_REFRESH_AFTER_MS = 5_000;
 export function spendableMicros(budget) {
     if (budget.limitMicros === null)
         return null;
@@ -130,23 +131,34 @@ export function freeRolesFor(spends, prefixes) {
 export function createRefreshQueue(opts) {
     let queued = false;
     let queuedFullState = false;
+    let queuedFollowUp = false;
     let active = null;
-    const request = (withFullState) => {
+    const request = (withFullState, allowFollowUp = true) => {
         queued = true;
         queuedFullState ||= withFullState;
+        queuedFollowUp ||= allowFollowUp;
         if (active)
             return active;
         active = (async () => {
             while (queued) {
                 const fullState = queuedFullState;
+                const followUp = queuedFollowUp;
                 queued = false;
                 queuedFullState = false;
-                const value = await opts.read(fullState);
+                queuedFollowUp = false;
+                const value = await opts.read(fullState, followUp);
                 // If another trigger arrived while this read was in flight, its result
                 // is already the one the caller wants. Skip the older intermediate
                 // frame instead of flashing it before the trailing refresh completes.
-                if (!queued)
+                // Preserve its stronger intent, though: a cheap poll queued behind a
+                // full read must not swallow that read's retry hint.
+                if (queued) {
+                    queuedFullState ||= fullState;
+                    queuedFollowUp ||= followUp;
+                }
+                else {
                     opts.publish(value);
+                }
             }
         })().finally(() => {
             active = null;
@@ -155,6 +167,40 @@ export function createRefreshQueue(opts) {
     };
     return { request };
 }
+export function budgetRefreshDelay(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return null;
+    return Math.min(MAX_BUDGET_REFRESH_AFTER_MS, Math.ceil(value));
+}
+export function createBudgetRefreshRetry(run) {
+    let timer = null;
+    let disposed = false;
+    const cancel = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+    };
+    return {
+        schedule: (afterMs) => {
+            if (disposed)
+                return;
+            const delay = budgetRefreshDelay(afterMs);
+            cancel();
+            if (delay === null)
+                return;
+            timer = setTimeout(() => {
+                timer = null;
+                run();
+            }, delay + 50);
+            timer.unref?.();
+        },
+        cancel,
+        dispose: () => {
+            disposed = true;
+            cancel();
+        },
+    };
+}
 const EXHAUSTED_BALANCE_CREDITS = 50;
 export function castleCreditsExhausted(budget, credits) {
     if (!budget.blocked || credits?.plan !== "credits")
@@ -246,13 +292,14 @@ export async function fetchAiCredits() {
  * 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() {
+export async function fetchBudget(forceRefresh = false) {
     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}`, {
+        const suffix = forceRefresh ? '?refresh=1' : '';
+        const resp = await fetch(`${base}${CASTLE_BUDGET_PATH}${suffix}`, {
             headers: { authorization: `Bearer ${token}` },
             signal: AbortSignal.timeout(BUDGET_FETCH_TIMEOUT_MS),
         });
@@ -262,11 +309,13 @@ export async function fetchBudget() {
         if (typeof body?.usedMicros !== "number" || typeof body.blocked !== "boolean") {
             return null;
         }
+        const refreshAfterMs = budgetRefreshDelay(body.refreshAfterMs);
         return {
             usedMicros: body.usedMicros,
             limitMicros: typeof body.limitMicros === "number" ? body.limitMicros : null,
             resetAtMs: typeof body.resetAtMs === "number" ? body.resetAtMs : 0,
             blocked: body.blocked,
+            ...(refreshAfterMs !== null ? { refreshAfterMs } : {}),
             blockedModelPrefixes: Array.isArray(body.blockedModelPrefixes)
                 ? body.blockedModelPrefixes.filter((p) => typeof p === "string")
                 : [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.185",
+  "version": "0.4.186",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"