castle-web-cli 0.4.102 → 0.4.104

package/dist/agent-failures.d.ts

@@ -1,4 +1,4 @@
-export type FailureKind = "config" | "transient" | "no-work" | "spawn" | "timeout" | "exit";
+export type FailureKind = "config" | "limit" | "transient" | "no-work" | "spawn" | "timeout" | "exit";
 export type ConfigReason = "no-key" | "bad-key" | "no-credits" | "unknown-model" | "no-tools" | "no-endpoints" | "flagged" | "context-length";
 export interface AgentFailure {
     kind: FailureKind;
@@ -7,6 +7,7 @@ export interface AgentFailure {
     verbose?: string;
     model?: string;
     suggestion?: string;
+    resetAtMs?: number;
 }
 export declare function failureForStatus(status: number, body: string, model?: string): AgentFailure | undefined;
 export declare function classifyProviderError(text: string | undefined, model?: string): AgentFailure | undefined;

package/dist/agent-failures.js

@@ -8,6 +8,9 @@
 //   config    - deterministic and won't fix itself (bad slug, bad key, no
 //               credits). Never retried: retrying is pure latency. Copy names
 //               what's wrong and points at settings / Castle.
+//   limit     - Castle's daily AI allowance for this user is spent. Nothing to
+//               fix in the session and nothing to retry until the reset, so the
+//               copy gives the time and the one way around it (own credential).
 //   transient - the provider was busy or broke. NOT auto-retried either (see
 //               below), but the copy invites the user to send again.
 //   no-work   - the model answered instead of working. Config is fine; the
@@ -137,6 +140,12 @@ export function failureCopy(opts) {
     switch (opts.failure.kind) {
         case "config":
             return `${configCopy(opts.failure)}${tasksNote}`;
+        case "limit": {
+            const resets = opts.failure.resetAtMs
+                ? ` -- resets ${new Date(opts.failure.resetAtMs).toLocaleString()}`
+                : "";
+            return `Daily Castle AI limit reached${resets}. Runs on your own API key or login aren't limited.${tasksNote}`;
+        }
         case "transient":
             return `OpenRouter is busy right now and I couldn't get through. Send that again in a moment.${tasksNote}`;
         case "no-work":

package/dist/agent.js

@@ -24,7 +24,8 @@ 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, reportCursorRun, withCustomHeaders, } from "./metering.js";
+import { fetchBudget, meteringHeaders, newAgentSessionId, reportCursorRun, withCustomHeaders, } from "./metering.js";
+import { anthropicKeyHelperCommand, claudeHasSavedLogin, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from "./byo-auth.js";
 import { runAgentNative } from "./native/loop.js";
 import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
 import { createPlaywrightPlaytestExecutor } from "./native/playtest-executor.js";
@@ -153,17 +154,6 @@ function openrouterAnthropicBase() {
     const injected = process.env.OPENROUTER_BASE_URL;
     return injected ? injected.replace(/\/v1\/?$/, "") : "https://openrouter.ai/api";
 }
-// Anthropic credential sources the claude CLI will fall back to on its own.
-// This env points the CLI at a THIRD PARTY, so every one of these has to be
-// cleared or that third party receives the user's Anthropic credential. Note
-// there is no file to check for here: on macOS the CLI reads a saved login
-// from the Keychain, so `~/.claude/.credentials.json` can be absent while the
-// CLI is still perfectly able to authenticate as the user.
-const ANTHROPIC_CREDENTIAL_ENV = [
-    "ANTHROPIC_API_KEY",
-    "ANTHROPIC_AUTH_TOKEN_HELPER",
-    "CLAUDE_CODE_OAUTH_TOKEN",
-];
 // Env for a claude CLI spawn routed at OpenRouter (claudeModel "openrouter",
 // Path A). Two things make this deterministic regardless of the user's own
 // Anthropic auth (verified live against the real `claude` binary while
@@ -359,6 +349,18 @@ const OPENROUTER_ALLOWED_TOOLS = "--allowedTools=Edit,Write,NotebookEdit,Bash";
 // Cursor's proprietary model. Also the slug reported to the metering ledger, so
 // the two can never drift into disagreeing about what a cursor row ran on.
 const CURSOR_MODEL = "composer-2.5-fast";
+// Keep runs independent of the machine's user config: no user plugins (LSP
+// servers etc.), no user MCP servers. CLAUDE.md auto-discovery and OAuth still
+// work. On a user's own Anthropic KEY this also carries the apiKeyHelper that
+// actually authenticates the run (see anthropicKeyHelperCommand).
+function claudeSettingsArg(auth) {
+    return JSON.stringify({
+        enabledPlugins: {},
+        ...(auth?.mode === "user-key"
+            ? { apiKeyHelper: anthropicKeyHelperCommand() }
+            : {}),
+    });
+}
 function buildAgentInvocation(backend, role, prompt, claudeModel, 
 // Already resolved for this role by the caller (router turns pass
 // settings.routerOpenrouterModel, task spawns settings.tasksOpenrouterModel).
@@ -399,11 +401,8 @@ metering) {
                 // summary before prose). Undocumented in --help but honored.
                 "--thinking-display",
                 "summarized",
-                // Keep runs independent of the machine's user config: no user plugins
-                // (LSP servers etc.), no user MCP servers. CLAUDE.md auto-discovery
-                // and OAuth still work.
                 "--settings",
-                '{"enabledPlugins": {}}',
+                claudeSettingsArg(anAuth),
                 "--strict-mcp-config",
                 ...(role === "task"
                     ? ["--append-system-prompt", CLAUDE_TASK_SYSTEM_REMINDER]
@@ -767,37 +766,6 @@ function castleKeys() {
         return {};
     }
 }
-// A user's OWN provider credentials, kept SEPARATE from Castle's keys.json so
-// castle-www's per-serve re-sync of keys.json (cloudSandbox.ts syncCastleKeys)
-// can't clobber them. Same shape as keys.json (env-var-name keys); the user (or
-// a future editor UI) writes this file, nothing in-process does. When a key is
-// present the run goes DIRECT to that provider on the user's own credential and
-// is NOT metered -- deleting the key reverts to Castle's proxy on the next run.
-// The path override mirrors CASTLE_KEYS_PATH so the QA battery stays isolated
-// from a developer's real ~/.castle. No env fallback on read: the file is the
-// only source, so a delete fully reverts.
-const CASTLE_USER_KEYS_PATH = process.env.CASTLE_USER_KEYS_PATH ??
-    path.join(os.homedir(), ".castle", "user-keys.json");
-function userKeys() {
-    try {
-        return JSON.parse(fs.readFileSync(CASTLE_USER_KEYS_PATH, "utf8"));
-    }
-    catch {
-        return {};
-    }
-}
-function userKey(envName) {
-    const v = userKeys()[envName]?.trim();
-    return v ? v : null;
-}
-function resolveAnthropicAuth() {
-    const k = userKey("ANTHROPIC_API_KEY");
-    if (k)
-        return { mode: "user-key", key: k };
-    if (backendHasSavedAuth("claude"))
-        return { mode: "user-login" };
-    return { mode: "proxy" };
-}
 function resolveOpenrouterAuth() {
     const k = userKey("OPENROUTER_API_KEY");
     if (k)
@@ -856,50 +824,15 @@ function purgeStaleCursorAuth(home, injectedKey) {
     }
 }
 // True when the user has their OWN saved auth for this backend -- a login we
-// route to directly (and bill to them) instead of Castle's proxy / key.
-//
-// KNOWN GAP (macOS): the claude check is a false negative for most logged-in
-// users. `claude /login` stores credentials in the KEYCHAIN there, not in
-// ~/.claude/.credentials.json, so this returns false and the run stays on
-// Castle's proxy even though the user has a perfectly good subscription login
-// the CLI would have used. Verified while tracing the OpenRouter credential
-// leak: on a machine with no .credentials.json at all, the CLI still
-// authenticated from the Keychain. Left alone deliberately -- reading the
-// Keychain (`security find-generic-password`) changes who pays for a run, which
-// is a product decision, not a cleanup. In a Linux sandbox (the case that
-// matters for BYO routing) the file IS authoritative, so the gap doesn't bite.
-//
-// CASTLE_CLAUDE_CREDENTIALS_PATH overrides the claude credentials location so
-// the QA battery can isolate from a developer's REAL ~/.claude login -- which,
-// now that this gates proxy-vs-direct routing (see resolveAnthropicAuth), would
-// otherwise flip every plain-claude scenario to "direct" on a logged-in machine.
-// Mirrors the CASTLE_KEYS_PATH seam.
+// route to directly (and bill to them) instead of Castle's proxy / key. The
+// claude side lives in byo-auth.ts, which the editor terminal shares.
 function backendHasSavedAuth(backend) {
-    const home = os.homedir();
-    if (backend === "claude") {
-        const credPath = process.env.CASTLE_CLAUDE_CREDENTIALS_PATH ??
-            path.join(home, ".claude", ".credentials.json");
-        return fs.existsSync(credPath);
-    }
-    if (backend === "cursor") {
-        return cursorHasUserLogin(home);
-    }
+    if (backend === "claude")
+        return claudeHasSavedLogin();
+    if (backend === "cursor")
+        return cursorHasUserLogin(os.homedir());
     return false;
 }
-// Everything that points the claude CLI at Castle's llm-proxy, or that it could
-// otherwise send there: the injected proxy pair, every Anthropic credential the
-// CLI falls back to, and an inherited ANTHROPIC_CUSTOM_HEADERS. That last one
-// matters because the sandbox host-agent's pty env carries x-castle-* metering
-// lines (castle-sandboxes agentRunner), so a serve started from that terminal
-// inherits them and withCustomHeaders deliberately preserves inherited values.
-// Cleared wholesale on any DIRECT run so none of it can ride along to
-// api.anthropic.com or to the user's own account.
-const ANTHROPIC_PROXY_ENV = [
-    "ANTHROPIC_BASE_URL",
-    "ANTHROPIC_AUTH_TOKEN",
-    "ANTHROPIC_CUSTOM_HEADERS",
-    ...ANTHROPIC_CREDENTIAL_ENV,
-];
 // Env for the plain claude CLI path (NOT claude-via-OpenRouter -- that's
 // envForOpenrouterSpawn). resolveAnthropicAuth decides the routing:
 //   - proxy: inherit the host-injected ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN
@@ -908,16 +841,17 @@ const ANTHROPIC_PROXY_ENV = [
 //   - user-login: strip the proxy pair + all stray Anthropic creds so the CLI
 //     authenticates from the user's own saved login (~/.claude/.credentials.json
 //     or, on macOS, the Keychain) and bills them, direct + unmetered.
-//   - user-key: same strip, then set ANTHROPIC_API_KEY (x-api-key) to the user's
-//     own key, direct + unmetered.
+//   - user-key: same strip, and the key arrives through the --settings
+//     apiKeyHelper buildAgentInvocation adds, NOT through this env -- a headless
+//     claude ignores an unapproved ANTHROPIC_API_KEY (see
+//     anthropicKeyHelperCommand), so setting it here would look like the
+//     credential while doing nothing.
 function envForClaudeSpawn(auth) {
     const env = { ...process.env };
     if (auth.mode === "proxy")
         return env;
     for (const name of ANTHROPIC_PROXY_ENV)
         delete env[name];
-    if (auth.mode === "user-key")
-        env.ANTHROPIC_API_KEY = auth.key;
     return env;
 }
 // Env for a cursor-agent spawn: inject Castle's key ONLY when the backend has no
@@ -1319,8 +1253,12 @@ function makeAgentEventHandler(opts, state) {
         }
         else if (ev.type === "result") {
             state.sawResult = true;
+            // An EMPTY string result falls back to the streamed text. Models that
+            // return their blocks as `text, thinking` (gemini through OpenRouter's
+            // anthropic-compatible endpoint) end the turn on an empty thinking block,
+            // and the CLI reports `result: ""` even though the answer streamed fine.
             state.finalText =
-                typeof ev.result === "string" ? ev.result : state.accumulated;
+                typeof ev.result === "string" && ev.result ? ev.result : state.accumulated;
             state.resultIsError = ev.is_error === true;
             state.usage = parseCliUsage(ev.usage);
         }
@@ -1355,8 +1293,12 @@ function makeAgentEventHandler(opts, state) {
         }
         else if (ev.type === "result") {
             state.sawResult = true;
+            // An EMPTY string result falls back to the streamed text. Models that
+            // return their blocks as `text, thinking` (gemini through OpenRouter's
+            // anthropic-compatible endpoint) end the turn on an empty thinking block,
+            // and the CLI reports `result: ""` even though the answer streamed fine.
             state.finalText =
-                typeof ev.result === "string" ? ev.result : state.accumulated;
+                typeof ev.result === "string" && ev.result ? ev.result : state.accumulated;
             state.resultIsError = ev.is_error === true;
             state.usage = parseCliUsage(ev.usage);
         }
@@ -1613,6 +1555,98 @@ async function preflightOpenrouterRun(opts) {
     }
     return null;
 }
+// Every run that Castle pays for moves the usage bar, and runAgentTurn is the
+// one place that knows a run just ended. The serve subscribes to refresh the
+// number it pushes to the editor; a run with no serve attached has no listener.
+const runFinishedListeners = new Set();
+function onAgentRunFinished(listener) {
+    runFinishedListeners.add(listener);
+    return () => {
+        runFinishedListeners.delete(listener);
+    };
+}
+function notifyAgentRunFinished() {
+    for (const listener of runFinishedListeners)
+        listener();
+}
+// True when THIS run spends Castle's credential rather than the user's own.
+// Resolves exactly as buildAgentInvocation / runAgentSmith will, one step
+// earlier, so the gate and the run can never disagree about who is paying.
+// Cursor counts: it runs on Castle's key by default, and gating it here is the
+// only gate there is -- its traffic never reaches the proxy.
+function runIsCastlePaid(backend, claudeModel, orAuth) {
+    if (backend === "cursor")
+        return true;
+    return roleUsesOpenrouter(backend, claudeModel)
+        ? (orAuth ?? resolveOpenrouterAuth()).mode === "proxy"
+        : resolveAnthropicAuth().mode === "proxy";
+}
+// Whether Castle's budget is this editor's to spend at all, which is what makes
+// the usage bar worth drawing. Both roles count, and they can disagree: an
+// Anthropic login covers the claude roles while a cursor role still spends
+// Castle's key. Re-read per refresh, so adding or removing a credential (or
+// switching a role's backend) moves the bar on the next one.
+function anyRoleIsCastlePaid(settings) {
+    return (runIsCastlePaid(settings.router, settings.routerClaudeModel, null) ||
+        runIsCastlePaid(settings.tasks, settings.tasksClaudeModel, null));
+}
+// The proxy 403s a spent-out user mid-stream, which a CLI surfaces as a generic
+// provider error after a spawn. Asking first turns that into one sentence and
+// no spawn. Fails open on every non-answer: the proxy is the real backstop.
+async function budgetRefusal(backend, claudeModel, orAuth) {
+    if (!runIsCastlePaid(backend, claudeModel, orAuth))
+        return null;
+    const budget = await fetchBudget();
+    if (!budget?.blocked)
+        return null;
+    return {
+        kind: "limit",
+        detail: "daily Castle AI limit reached",
+        resetAtMs: budget.resetAtMs || undefined,
+    };
+}
+// Slow on purpose: usage only moves because a run spent something, and a
+// finished run already refreshes. This is for the spend this serve never sees
+// -- a `claude` invoked straight from the sandbox terminal.
+const USAGE_POLL_MS = 60_000;
+/**
+ * The editor's daily-usage feed, pushed over the agent socket exactly the way
+ * settings are: the current value rides `hello`, and a change is broadcast.
+ * Outside a sandbox fetchBudget answers null forever, so nothing is ever sent
+ * and the shell simply has no bar to show.
+ *
+ * Null is a value here, not just "no answer yet": a user running on their own
+ * credential is told nothing about Castle's daily limit, because none of their
+ * runs spend it and none of them are gated on it -- showing the bar (worse, a
+ * spent-out red one) would describe a limit that doesn't apply to them. It has
+ * to be broadcast rather than merely withheld, so the bar clears when a
+ * credential appears mid-session.
+ */
+function createUsageFeed(opts) {
+    let latest = null;
+    async function refreshAsync() {
+        const next = opts.castlePaid() ? await fetchBudget() : null;
+        if (JSON.stringify(next ?? null) === JSON.stringify(latest ?? null))
+            return;
+        latest = next;
+        opts.broadcast({ type: "usage", usage: next });
+    }
+    const refresh = () => void refreshAsync();
+    const stopRunWatch = onAgentRunFinished(refresh);
+    const timer = setInterval(() => {
+        if (opts.hasClients())
+            refresh();
+    }, USAGE_POLL_MS);
+    timer.unref?.();
+    return {
+        latest: () => latest,
+        refresh,
+        stop: () => {
+            stopRunWatch();
+            clearInterval(timer);
+        },
+    };
+}
 // The one backend dispatch point for running an agent turn: smith runs
 // in-process (runAgentSmith -> runAgentNative); cursor/claude spawn a CLI
 // (buildAgentInvocation -> runAgentCli). Everything downstream consumes the
@@ -1627,8 +1661,11 @@ async function runAgentTurn(opts) {
     // Deterministic config errors stop here: nothing spawned, no request issued,
     // nothing billed. Returned (not thrown) because the callers' catch paths
     // emit generic "something went wrong" copy, which would bury the specific
-    // reason this pre-flight exists to produce.
-    const failure = await preflightOpenrouterRun({ ...opts, orAuth });
+    // reason this pre-flight exists to produce. A spent-out daily budget is the
+    // same shape of answer, and comes second so a misconfigured run is still
+    // reported as misconfigured.
+    const failure = (await preflightOpenrouterRun({ ...opts, orAuth })) ??
+        (await budgetRefusal(opts.backend, opts.claudeModel, orAuth));
     if (failure) {
         return {
             ok: false,
@@ -1644,10 +1681,11 @@ async function runAgentTurn(opts) {
     // in runTaskAgentIn calls this once per attempt, and each attempt is its own
     // conversation -- nothing is resumed).
     const sessionId = newAgentSessionId(opts.role);
+    const settled = (run) => run.finally(() => notifyAgentRunFinished());
     if (opts.backend === "smith") {
         // roleUsesOpenrouter is true for smith, so orAuth is non-null here.
         const direct = orAuth.mode === "user-key";
-        return runAgentSmith({
+        return settled(runAgentSmith({
             cwd: opts.cwd,
             role: opts.role,
             apiKey: orAuth.key,
@@ -1674,7 +1712,7 @@ async function runAgentTurn(opts) {
             onActivity: opts.onActivity,
             onThinking: opts.onThinking,
             onSpawn: opts.onSpawn,
-        });
+        }));
     }
     const invocation = buildAgentInvocation(opts.backend, opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, { sessionId, deckDir: opts.cwd });
     const startedMs = Date.now();
@@ -1700,8 +1738,8 @@ async function runAgentTurn(opts) {
     // run is reported from here. Every other backend is already recorded upstream,
     // and reporting them here too would double-count them in the same table.
     if (opts.backend !== "cursor")
-        return run;
-    return run.then((result) => {
+        return settled(run);
+    return settled(run.then((result) => {
         reportCursorRun({
             deckDir: opts.cwd,
             sessionId,
@@ -1710,7 +1748,7 @@ async function runAgentTurn(opts) {
             ok: result.ok,
         });
         return result;
-    });
+    }));
 }
 // -- task store ---------------------------------------------------------------
 function persistTaskFile(tasksDir, task) {
@@ -3463,7 +3501,17 @@ export function createAgentServer(opts) {
         tasksProviderTier: normalizeProviderTier(storedSettings?.tasksProviderTier) ??
             DEFAULT_SETTINGS.tasksProviderTier,
     };
-    const applySettings = (incoming) => applyAgentSettings(incoming, { settings, settingsPath, broadcast });
+    const usageFeed = createUsageFeed({
+        broadcast,
+        hasClients: () => clients.size > 0,
+        castlePaid: () => anyRoleIsCastlePaid(settings),
+    });
+    const applySettings = (incoming) => {
+        applyAgentSettings(incoming, { settings, settingsPath, broadcast });
+        // A backend switch can change who pays (a cursor role always spends
+        // Castle's), so the bar follows the change instead of the poll.
+        usageFeed.refresh();
+    };
     const taskFeeds = createTaskFeeds(broadcast);
     const messageThinking = createMessageThinking(broadcast);
     const taskStore = createTaskStore({
@@ -3534,8 +3582,12 @@ export function createAgentServer(opts) {
             thinking: messageThinking.snapshot(),
             running: routerQueue.isRunning(),
             queued: routerQueue.queuedSnippets(),
+            usage: usageFeed.latest(),
         };
         socket.send(JSON.stringify(hello));
+        // A newly attached client is the one moment the cached value may be stale
+        // by a whole poll interval (nothing refreshes while nobody is watching).
+        usageFeed.refresh();
         // Slug verdicts follow hello rather than riding it: they're async, and the
         // boot snapshot must never wait on a network call. This is what makes a
         // stored-but-bad slug warn the first time the popover opens -- without it,
@@ -3601,6 +3653,7 @@ export function createAgentServer(opts) {
             }
         }
         stopChildRegistry();
+        usageFeed.stop();
         wss.close();
         void playtestBrowserManager.shutdown();
     }

package/dist/anthropic-key-helper.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/anthropic-key-helper.js

@@ -0,0 +1,7 @@
+// Printed to stdout for the claude CLI's `apiKeyHelper` setting: the user's own
+// Anthropic key, read from ~/.castle/user-keys.json at call time (see
+// byo-auth.ts anthropicKeyHelperCommand for why a helper and not an env var).
+// Reading it here rather than passing it in keeps the key out of the command
+// line and out of the spawned CLI's environment.
+import { userKey } from "./byo-auth.js";
+process.stdout.write(userKey("ANTHROPIC_API_KEY") ?? "");

package/dist/byo-auth.d.ts

@@ -0,0 +1,23 @@
+export declare const CASTLE_USER_KEYS_PATH: string;
+export declare function userKey(envName: "ANTHROPIC_API_KEY" | "OPENROUTER_API_KEY"): string | null;
+export type AnthropicAuth = {
+    mode: "user-key";
+    key: string;
+} | {
+    mode: "user-login";
+} | {
+    mode: "proxy";
+};
+export type OpenrouterAuth = {
+    mode: "user-key";
+    key: string;
+} | {
+    mode: "proxy";
+    key: string;
+};
+export declare function claudeHasSavedLogin(): boolean;
+export declare function resolveAnthropicAuth(): AnthropicAuth;
+export declare const ANTHROPIC_CREDENTIAL_ENV: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN_HELPER", "CLAUDE_CODE_OAUTH_TOKEN"];
+export declare const ANTHROPIC_PROXY_ENV: readonly ["ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_CUSTOM_HEADERS", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN_HELPER", "CLAUDE_CODE_OAUTH_TOKEN"];
+export declare function anthropicKeyHelperCommand(): string;
+export declare function envForUserShell(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/byo-auth.js

@@ -0,0 +1,130 @@
+// Whose Anthropic credential a run spends: the user's own (straight to
+// api.anthropic.com, unmetered) or Castle's (through the sandbox llm-proxy on
+// the injected scoped token). Split out of agent.ts because the editor's PTY
+// terminal has to answer the same question for the `claude` a user runs by
+// hand -- and must answer it the SAME way, or the terminal quietly spends
+// Castle's budget while the agent panel spends the user's.
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
+// A user's OWN provider credentials, kept SEPARATE from Castle's keys.json so
+// castle-www's per-serve re-sync of keys.json (cloudSandbox.ts syncCastleKeys)
+// can't clobber them. Same shape as keys.json (env-var-name keys); the user (or
+// a future editor UI) writes this file, nothing in-process does. When a key is
+// present the run goes DIRECT to that provider on the user's own credential and
+// is NOT metered -- deleting the key reverts to Castle's proxy on the next run.
+// The path override mirrors CASTLE_KEYS_PATH so the QA battery stays isolated
+// from a developer's real ~/.castle. No env fallback on read: the file is the
+// only source, so a delete fully reverts.
+export const CASTLE_USER_KEYS_PATH = process.env.CASTLE_USER_KEYS_PATH ??
+    path.join(os.homedir(), ".castle", "user-keys.json");
+function userKeys() {
+    try {
+        return JSON.parse(fs.readFileSync(CASTLE_USER_KEYS_PATH, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function userKey(envName) {
+    const v = userKeys()[envName]?.trim();
+    return v ? v : null;
+}
+// KNOWN GAP (macOS): a false negative for most logged-in users. `claude /login`
+// stores credentials in the KEYCHAIN there, not in ~/.claude/.credentials.json,
+// so this returns false and the run stays on Castle's proxy even though the
+// user has a perfectly good subscription login the CLI would have used. Left
+// alone deliberately -- reading the Keychain (`security find-generic-password`)
+// changes who pays for a run, which is a product decision, not a cleanup. In a
+// Linux sandbox (the case that matters for BYO routing) the file IS
+// authoritative, so the gap doesn't bite.
+//
+// CASTLE_CLAUDE_CREDENTIALS_PATH overrides the location so the QA battery can
+// isolate from a developer's REAL ~/.claude login -- which, since this gates
+// proxy-vs-direct routing, would otherwise flip every plain-claude scenario to
+// "direct" on a logged-in machine. Mirrors the CASTLE_KEYS_PATH seam.
+export function claudeHasSavedLogin() {
+    const credPath = process.env.CASTLE_CLAUDE_CREDENTIALS_PATH ??
+        path.join(os.homedir(), ".claude", ".credentials.json");
+    return fs.existsSync(credPath);
+}
+export function resolveAnthropicAuth() {
+    const k = userKey("ANTHROPIC_API_KEY");
+    if (k)
+        return { mode: "user-key", key: k };
+    if (claudeHasSavedLogin())
+        return { mode: "user-login" };
+    return { mode: "proxy" };
+}
+// Anthropic credential sources the claude CLI will fall back to on its own.
+// A spawn pointed at a THIRD PARTY (OpenRouter) has to clear every one of
+// these or that third party receives the user's Anthropic credential.
+export const ANTHROPIC_CREDENTIAL_ENV = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN_HELPER",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
+// Everything that points the claude CLI at Castle's llm-proxy, or that it could
+// otherwise send there: the injected proxy pair, every Anthropic credential the
+// CLI falls back to, and an inherited ANTHROPIC_CUSTOM_HEADERS. That last one
+// matters because the sandbox host-agent's pty env carries x-castle-* metering
+// lines (castle-sandboxes agentRunner), so a serve started from that terminal
+// inherits them and withCustomHeaders deliberately preserves inherited values.
+// Cleared wholesale on any DIRECT run so none of it can ride along to
+// api.anthropic.com or to the user's own account.
+export const ANTHROPIC_PROXY_ENV = [
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_CUSTOM_HEADERS",
+    ...ANTHROPIC_CREDENTIAL_ENV,
+];
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+// How a user's own Anthropic KEY actually reaches a headless `claude -p` run.
+//
+// Not ANTHROPIC_API_KEY: verified against claude 2.1.220 that a key in the
+// environment is IGNORED unless the user approved it interactively first
+// (/config's "Use custom API key"), and an unapproved key doesn't fall back to
+// anything either -- the run dies with "Not logged in - Please run /login"
+// having issued no request at all. Pre-seeding the approval
+// (customApiKeyResponses.approved in .claude.json) did NOT help. apiKeyHelper
+// is honored with no login, no approval and no prompt: claude runs the command
+// and sends its stdout as both x-api-key and Authorization: Bearer.
+//
+// The helper reads the key from the file at call time rather than taking it as
+// an argument, so the user's key never lands in a command line or in the
+// spawned CLI's environment.
+export function anthropicKeyHelperCommand() {
+    return `${shellQuote(process.execPath)} ${shellQuote(path.join(DIST_DIR, "anthropic-key-helper.js"))}`;
+}
+// Env for the editor's PTY terminal. The container env the serve inherits
+// carries the llm-proxy pair, and Claude Code ranks ANTHROPIC_AUTH_TOKEN ABOVE
+// a claude.ai login -- so without this a user who ran `claude /login` in the
+// terminal still gets "claude.ai connectors are disabled because
+// ANTHROPIC_API_KEY or another auth source is set", their login unused and
+// their session billed to Castle. Resolved at shell start, so a login taken in
+// an open terminal applies to the next one.
+//
+// A user KEY goes in as ANTHROPIC_API_KEY here, unlike the agent path's
+// apiKeyHelper (see above): an interactive claude CAN show the one-time
+// "use this custom API key?" approval, and the terminal is the one place a
+// person is there to answer it.
+export function envForUserShell(base) {
+    const env = { ...base };
+    const anthropic = resolveAnthropicAuth();
+    if (anthropic.mode !== "proxy") {
+        for (const name of ANTHROPIC_PROXY_ENV)
+            delete env[name];
+        if (anthropic.mode === "user-key")
+            env.ANTHROPIC_API_KEY = anthropic.key;
+    }
+    const openrouter = userKey("OPENROUTER_API_KEY");
+    if (openrouter) {
+        env.OPENROUTER_API_KEY = openrouter;
+        delete env.OPENROUTER_BASE_URL;
+    }
+    return env;
+}

package/dist/ide.js

@@ -15,6 +15,7 @@ import headlessPkg from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 import { WebSocketServer } from "ws";
 import { IMPORTS_DIR, importStatuses, updateImport } from "./imports.js";
+import { envForUserShell } from "./byo-auth.js";
 const HeadlessTerminal = headlessPkg.Terminal;
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
 // The bundled shell app (vite build output). `/` serves its index.html and
@@ -178,6 +179,12 @@ function listDeckFiles(deckDir) {
     out.sort((a, b) => a.localeCompare(b));
     return out;
 }
+function asFileTypes(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value.filter((e) => Boolean(e) && typeof e === "object" && typeof e.ext === "string");
+    return out.length > 0 ? out : undefined;
+}
 function asStringArray(value) {
     if (Array.isArray(value) && value.every((e) => typeof e === "string")) {
         return value;
@@ -202,7 +209,9 @@ function readEditorConfig(deckDir) {
             : undefined,
         hiddenPaths: asStringArray(editor.hiddenPaths),
         visiblePaths: asStringArray(editor.visiblePaths),
+        fileTypes: asFileTypes(editor.fileTypes),
         extensions: asStringArray(editor.extensions) ?? asStringArray(data.editorExtensions),
+        defaultPlayFile: typeof editor.defaultPlayFile === "string" ? editor.defaultPlayFile : undefined,
     };
     return config;
 }
@@ -233,7 +242,12 @@ function findKitRoot(deckDir) {
     return null;
 }
 function kitEditorExtensions(deckDir) {
-    const configured = readEditorConfig(deckDir).extensions;
+    const config = readEditorConfig(deckDir);
+    // Declared file types win: they say outright which extensions the kit edits.
+    if (config.fileTypes) {
+        return config.fileTypes.filter((t) => t.editor === "kit").map((t) => t.ext);
+    }
+    const configured = config.extensions;
     if (configured)
         return configured;
     const kitRoot = findKitRoot(deckDir);
@@ -476,6 +490,8 @@ function handleFilesApi(deckDir, req, res, reqPath) {
             // Stable per-deck id for client-side layout persistence (localStorage key).
             deckId: path.resolve(deckDir),
             kitEditorExtensions: kitEditorExtensions(deckDir),
+            fileTypes: config.fileTypes ?? null,
+            defaultPlayFile: config.defaultPlayFile ?? null,
             initialPanels: config.initialPanels ?? null,
             hiddenPaths: config.hiddenPaths ?? [],
             visiblePaths: config.visiblePaths ?? [],
@@ -597,7 +613,7 @@ function defaultShell() {
 }
 function ptyEnv() {
     const env = {
-        ...process.env,
+        ...envForUserShell(process.env),
         TERM: PTY_TERM,
         COLORTERM: "truecolor",
         CLICOLOR: "1",