castle-web-cli 0.4.90 → 0.4.92

package/dist/agent.js

@@ -24,6 +24,7 @@ import { rawDataToString } from "./ide.js";
 import { buildRouterPrompt, buildTaskPrompt, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from "./agent-prompts.js";
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from "./openrouter-catalog.js";
 import { classifyProviderError, failureCopy, } from "./agent-failures.js";
+import { meteringHeaders, newAgentSessionId, withCustomHeaders, } from "./metering.js";
 import { runAgentNative } from "./native/loop.js";
 import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
 import { createPlaywrightPlaytestExecutor } from "./native/playtest-executor.js";
@@ -343,7 +344,11 @@ const OPENROUTER_ALLOWED_TOOLS = "--allowedTools=Edit,Write,NotebookEdit,Bash";
 function buildAgentInvocation(backend, role, prompt, claudeModel, 
 // Already resolved for this role by the caller (router turns pass
 // settings.routerOpenrouterModel, task spawns settings.tasksOpenrouterModel).
-openrouterModel) {
+openrouterModel, 
+// This run's ledger identity, and the deck dir its castle.json is read from.
+// Only the claude branch can carry it: cursor-agent runs on its own key and
+// never traverses the llm-proxy.
+metering) {
     if (backend === "claude") {
         const viaOpenrouter = claudeModel === "openrouter";
         return {
@@ -379,9 +384,13 @@ openrouterModel) {
                     : []),
                 prompt,
             ],
-            env: viaOpenrouter
+            env: withCustomHeaders(viaOpenrouter
                 ? envForOpenrouterSpawn(openrouterApiKey())
-                : envForAgentSpawn(backend),
+                : envForAgentSpawn(backend), meteringHeaders({
+                deckDir: metering.deckDir,
+                sessionId: metering.sessionId,
+                route: viaOpenrouter ? "openrouter" : "anthropic",
+            })),
         };
     }
     return {
@@ -1456,6 +1465,7 @@ async function runAgentSmith(opts) {
         const result = await runAgentNative({
             cwd: opts.cwd,
             role: opts.role,
+            extraHeaders: opts.extraHeaders,
             model: opts.model,
             apiKey: openrouterApiKey(),
             reasoningEffort: opts.openrouterTuning?.reasoningEffort,
@@ -1574,10 +1584,19 @@ async function runAgentTurn(opts) {
             crashed: false,
         };
     }
+    // One id per call: a router turn, or a single task attempt (the retry loop
+    // in runTaskAgentIn calls this once per attempt, and each attempt is its own
+    // conversation -- nothing is resumed).
+    const sessionId = newAgentSessionId(opts.role);
     if (opts.backend === "smith") {
         return runAgentSmith({
             cwd: opts.cwd,
             role: opts.role,
+            extraHeaders: meteringHeaders({
+                deckDir: opts.cwd,
+                sessionId,
+                route: "openrouter",
+            }),
             model: opts.openrouterModel,
             prompt: opts.prompt,
             // Mirrors claude's --append-system-prompt for tasks (the native loop
@@ -1596,7 +1615,7 @@ async function runAgentTurn(opts) {
             onSpawn: opts.onSpawn,
         });
     }
-    const invocation = buildAgentInvocation(opts.backend, opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel);
+    const invocation = buildAgentInvocation(opts.backend, opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, { sessionId, deckDir: opts.cwd });
     return runAgentCli({
         cwd: opts.cwd,
         command: invocation.command,

package/dist/metering.d.ts

@@ -0,0 +1,21 @@
+export type MeteringRoute = "anthropic" | "openrouter";
+/**
+ * A fresh id for one agent run -- one router turn (one user message) or one
+ * task attempt. Every provider call in that run's agentic loop carries it, so
+ * the ledger can price a single turn even though concurrent tasks interleave
+ * with chat in wall-clock time. The role prefix keeps "chat spend vs.
+ * background-task spend" a prefix match with no extra column.
+ */
+export declare function newAgentSessionId(role: "router" | "task"): string;
+export declare function meteringHeaders(opts: {
+    deckDir: string;
+    sessionId: string;
+    route: MeteringRoute;
+}): Record<string, string>;
+/**
+ * Merge metering headers into a claude spawn env. ANTHROPIC_CUSTOM_HEADERS is
+ * the claude CLI's newline-separated `Name: Value` list, forwarded on every
+ * request it makes to ANTHROPIC_BASE_URL. An inherited value is kept, first,
+ * rather than clobbered.
+ */
+export declare function withCustomHeaders(env: NodeJS.ProcessEnv, headers: Record<string, string>): NodeJS.ProcessEnv;

package/dist/metering.js

@@ -0,0 +1,75 @@
+// Per-request metering identity for agent runs inside a Castle sandbox.
+//
+// The per-host llm-proxy (castle-sandboxes/llm-proxy) terminates every
+// provider call a sandbox makes, records a usage row, and strips these two
+// headers before forwarding upstream -- so they never reach Anthropic or
+// OpenRouter. Names must match LLM_SESSION_HEADER / LLM_DECK_HEADER in
+// castle-sandboxes/shared/src/index.ts.
+//
+// The proxy already knows the user (its token is minted per sandbox) and the
+// sandbox. These headers add the two dimensions only this process knows: which
+// deck the work belongs to, and which agent run issued the call.
+import * as fs from "fs";
+import * as path from "path";
+import { randomBytes } from "crypto";
+const SESSION_HEADER = "x-castle-agent-session-id";
+const DECK_HEADER = "x-castle-deck-id";
+/**
+ * A fresh id for one agent run -- one router turn (one user message) or one
+ * task attempt. Every provider call in that run's agentic loop carries it, so
+ * the ledger can price a single turn even though concurrent tasks interleave
+ * with chat in wall-clock time. The role prefix keeps "chat spend vs.
+ * background-task spend" a prefix match with no extra column.
+ */
+export function newAgentSessionId(role) {
+    return `${role === "router" ? "r" : "t"}-${randomBytes(12).toString("hex")}`;
+}
+// Outside a sandbox nothing injects a base URL, and the headers would be sent
+// to the provider itself -- handing a deck id to a third party to no purpose.
+function proxyInjected(route) {
+    return Boolean(route === "anthropic"
+        ? process.env.ANTHROPIC_BASE_URL
+        : process.env.OPENROUTER_BASE_URL);
+}
+// castle.json is written by the first save (see save-deck.ts), so an unsaved
+// deck has no Castle id and its spend stays unattributed rather than being
+// labelled with the sandbox-local directory name, which never becomes the
+// deck id. Re-read per run: a deck saved mid-session starts attributing on its
+// next turn.
+function deckIdFor(deckDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(path.join(deckDir, "castle.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.deckId !== "string" || !parsed.deckId)
+        return null;
+    return parsed.deckId.replace(/[\r\n]/g, "") || null;
+}
+export function meteringHeaders(opts) {
+    if (!proxyInjected(opts.route))
+        return {};
+    const deckId = deckIdFor(opts.deckDir);
+    return {
+        [SESSION_HEADER]: opts.sessionId,
+        ...(deckId ? { [DECK_HEADER]: deckId } : {}),
+    };
+}
+/**
+ * Merge metering headers into a claude spawn env. ANTHROPIC_CUSTOM_HEADERS is
+ * the claude CLI's newline-separated `Name: Value` list, forwarded on every
+ * request it makes to ANTHROPIC_BASE_URL. An inherited value is kept, first,
+ * rather than clobbered.
+ */
+export function withCustomHeaders(env, headers) {
+    const lines = Object.entries(headers).map(([name, value]) => `${name}: ${value}`);
+    if (lines.length === 0)
+        return env;
+    const inherited = env.ANTHROPIC_CUSTOM_HEADERS;
+    return {
+        ...env,
+        ANTHROPIC_CUSTOM_HEADERS: [...(inherited ? [inherited] : []), ...lines].join("\n"),
+    };
+}

package/dist/native/loop.js

@@ -607,6 +607,7 @@ async function runLoop(opts, toolSchemas, log) {
                 reasoningEffort: opts.reasoningEffort ?? REASONING_EFFORT[opts.role],
                 routing: opts.routing,
                 providerTier: opts.providerTier,
+                extraHeaders: opts.extraHeaders,
                 maxTokens: MAX_COMPLETION_TOKENS,
                 signal: controller.signal,
                 onDelta: opts.onDelta,

package/dist/native/openrouter.d.ts

@@ -39,6 +39,7 @@ export interface StreamChatOpts {
     reasoningEffort?: ORReasoningEffort;
     routing?: ORRoutingMode;
     providerTier?: string;
+    extraHeaders?: Record<string, string>;
     maxTokens?: number;
     signal?: AbortSignal;
     onDelta?: (delta: string) => void;

package/dist/native/openrouter.js

@@ -247,6 +247,7 @@ export async function streamChatCompletion(opts) {
         res = await connectWithRetry({
             method: "POST",
             headers: {
+                ...opts.extraHeaders,
                 Authorization: `Bearer ${opts.apiKey}`,
                 "Content-Type": "application/json",
             },

package/dist/native/types.d.ts

@@ -28,6 +28,7 @@ export interface NativeRunOpts {
     restart?: () => void;
     logPath?: string;
     timeoutMs: number;
+    extraHeaders?: Record<string, string>;
     signal?: AbortSignal;
     onDelta?: (delta: string) => void;
     onActivity?: (activity: string | null) => void;

package/kits/basic-2d/editors/SceneEditor.jsx

@@ -797,7 +797,9 @@ function useSelectionGesture(args) {
     const point = { x: raw.x + cam.x, y: raw.y + cam.y };
     current.canvasRef.current.setPointerCapture(event.pointerId);
     const scene = makeScene(current.sceneData, behaviorClasses, current.sprites, current.files);
-    const actor = scene.actorAt(point.x, point.y);
+    const stack = scene.actorsAt(point.x, point.y);
+    const stackIds = stack.map((a) => a.id);
+    const actor = stack[0] ?? null;
     const drag = {
       pointerId: event.pointerId,
       startPoint: point,
@@ -820,7 +822,7 @@ function useSelectionGesture(args) {
     } else if (current.multiSelectMode) {
       handleModePointerDown(drag, actor, current);
     } else {
-      handleDefaultPointerDown(drag, actor, point, current);
+      handleDefaultPointerDown(drag, actor, point, current, stackIds);
     }
     drag.moveStarts = collectMoveStarts(current.sceneData, drag.movingActorIds);
     dragRef.current = drag;
@@ -891,6 +893,13 @@ function useSelectionGesture(args) {
       finalizeMarquee(drag, current);
     } else if (drag.kind === 'idle' && !drag.movedFar && !drag.longPressFired) {
       handleTap(drag, current);
+    } else if (
+      drag.kind === 'move' &&
+      !drag.movedFar &&
+      !drag.longPressFired &&
+      drag.cycleStack
+    ) {
+      cycleSelection(drag, current);
     }
     current.marqueeRef.current = null;
     dragRef.current = null;
@@ -1198,13 +1207,23 @@ function handleModePointerDown(drag, actor, current) {
     drag.pendingMarquee = true;
   }
 }
-function handleDefaultPointerDown(drag, actor, point, current) {
+function handleDefaultPointerDown(drag, actor, point, current, stackIds) {
   if (actor) {
-    if (!current.selectedActorIds.includes(actor.id)) {
+    const sel = current.selectedActorIds;
+    if (sel.length === 1 && stackIds.length > 1 && stackIds.includes(sel[0])) {
+      // Overlapping pile with a single selected actor under the cursor: keep it
+      // selected so it stays draggable, and arm click-to-cycle so a stationary
+      // click descends to the next actor beneath it (see cycleSelection).
+      drag.movingActorIds = [...sel];
+      drag.cycleStack = stackIds;
+    } else if (sel.includes(actor.id)) {
+      // Pressed an actor that's part of the current selection: keep the
+      // selection so the whole group stays draggable.
+      drag.movingActorIds = [...sel];
+    } else {
+      // Fresh pick: select the topmost actor under the cursor.
       current.onSelectActorIds([actor.id]);
       drag.movingActorIds = [actor.id];
-    } else {
-      drag.movingActorIds = [...current.selectedActorIds];
     }
     drag.kind = 'move';
     drag.longPressTimer = window.setTimeout(() => {
@@ -1235,6 +1254,20 @@ function finalizeMarquee(drag, current) {
   for (const id of hits) merged.add(id);
   current.onSelectActorIds([...merged]);
 }
+// A stationary click on a pile of overlapping actors advances the selection to
+// the next actor below the currently selected one, wrapping around at the
+// bottom. This lets repeated clicks in the same spot reach an actor buried under
+// others that would otherwise always win the topmost hit-test.
+function cycleSelection(drag, current) {
+  const stack = drag.cycleStack;
+  if (!stack || stack.length < 2) return;
+  const sel = current.selectedActorIds;
+  if (sel.length !== 1) return;
+  const idx = stack.indexOf(sel[0]);
+  if (idx === -1) return;
+  const nextId = stack[(idx + 1) % stack.length];
+  if (nextId !== sel[0]) current.onSelectActorIds([nextId]);
+}
 function handleTap(drag, current) {
   if (!drag.modeAtStart) return;
   if (drag.startedOnActorId !== null) {

package/kits/basic-2d/engine/scene.js

@@ -281,7 +281,15 @@ export class SceneRuntime {
   }
 
   actorAt(x, y) {
+    return this.actorsAt(x, y)[0] ?? null;
+  }
+
+  // All actors whose Layout box contains the point, ordered topmost-first (high
+  // z -> low z). Used by the editor's click-to-cycle so repeated clicks in the
+  // same spot can walk down through overlapping actors.
+  actorsAt(x, y) {
     const actors = this.getActors().slice().reverse();
+    const hits = [];
     for (const actor of actors) {
       const layout = getLayout(actor);
       if (!layout) continue;
@@ -291,10 +299,10 @@ export class SceneRuntime {
         y >= layout.y &&
         y <= layout.y + layout.height
       ) {
-        return actor;
+        hits.push(actor);
       }
     }
-    return null;
+    return hits;
   }
 
   actorIdsInRect(rect) {