castle-web-cli 0.4.91 → 0.4.93

package/dist/agent.js

@@ -190,8 +190,15 @@ const ANTHROPIC_CREDENTIAL_ENV = [
 // for openrouter.ai: it sent `Authorization: Bearer sk-ant-...`. Callers must
 // resolve a key first (preflightOpenrouterRun does); there is deliberately no
 // code path from here to openrouter.ai without an OpenRouter token.
-function envForOpenrouterSpawn(apiKey) {
-    if (!apiKey) {
+// ANTHROPIC_BASE_URL for a user's OWN OpenRouter key -- straight to openrouter.ai
+// (the CLI appends /v1/messages), bypassing the proxy. The proxy branch instead
+// uses openrouterAnthropicBase() (the injected OPENROUTER_BASE_URL origin).
+const OPENROUTER_DIRECT_ANTHROPIC_BASE = "https://openrouter.ai/api";
+// OpenAI-shaped chat-completions ORIGIN for the smith native loop on a user's
+// own OpenRouter key (native/openrouter.ts appends /chat/completions).
+const OPENROUTER_DIRECT_CHAT_BASE = "https://openrouter.ai/api/v1";
+function envForOpenrouterSpawn(auth) {
+    if (!auth.key) {
         // Unreachable via runAgentTurn (pre-flight rejects a keyless run before
         // any spawn). A backstop, so a future caller that skips pre-flight fails
         // loudly instead of quietly leaking.
@@ -200,9 +207,17 @@ function envForOpenrouterSpawn(apiKey) {
     const env = { ...process.env };
     for (const name of ANTHROPIC_CREDENTIAL_ENV)
         delete env[name];
-    env.ANTHROPIC_BASE_URL = openrouterAnthropicBase();
+    if (auth.mode === "user-key") {
+        env.ANTHROPIC_BASE_URL = OPENROUTER_DIRECT_ANTHROPIC_BASE;
+        // An inherited ANTHROPIC_CUSTOM_HEADERS can carry x-castle-* metering
+        // lines (see ANTHROPIC_PROXY_ENV) -- never forward those on a direct run.
+        delete env.ANTHROPIC_CUSTOM_HEADERS;
+    }
+    else {
+        env.ANTHROPIC_BASE_URL = openrouterAnthropicBase();
+    }
     env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1";
-    env.ANTHROPIC_AUTH_TOKEN = apiKey;
+    env.ANTHROPIC_AUTH_TOKEN = auth.key;
     return env;
 }
 // The one OpenRouter credential, shared by BOTH OpenRouter paths: smith's
@@ -351,6 +366,14 @@ openrouterModel,
 metering) {
     if (backend === "claude") {
         const viaOpenrouter = claudeModel === "openrouter";
+        const orAuth = viaOpenrouter ? resolveOpenrouterAuth() : null;
+        const anAuth = viaOpenrouter ? null : resolveAnthropicAuth();
+        // Direct = the user's own credential/login is in play, so this run bypasses
+        // the proxy and must NOT carry metering headers (metering.ts would otherwise
+        // attach them off process.env and the direct spawn would leak them upstream).
+        const direct = viaOpenrouter
+            ? orAuth.mode === "user-key"
+            : anAuth.mode !== "proxy";
         return {
             command: "claude",
             args: [
@@ -385,11 +408,12 @@ metering) {
                 prompt,
             ],
             env: withCustomHeaders(viaOpenrouter
-                ? envForOpenrouterSpawn(openrouterApiKey())
-                : envForAgentSpawn(backend), meteringHeaders({
+                ? envForOpenrouterSpawn(orAuth)
+                : envForClaudeSpawn(anAuth), meteringHeaders({
                 deckDir: metering.deckDir,
                 sessionId: metering.sessionId,
                 route: viaOpenrouter ? "openrouter" : "anthropic",
+                direct,
             })),
         };
     }
@@ -740,6 +764,43 @@ 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)
+        return { mode: "user-key", key: k };
+    return { mode: "proxy", key: openrouterApiKey() };
+}
 // Keys for the SPAWNING backends' env injection (envForAgentSpawn). Smith is
 // absent by design: it never spawns a CLI -- its OpenRouter key flows through
 // openrouterApiKey() into runAgentNative's Authorization header instead.
@@ -791,31 +852,76 @@ function purgeStaleCursorAuth(home, injectedKey) {
         // no auth.json, or unreadable/unparseable -- nothing to purge
     }
 }
-// True when the user has their OWN saved auth for this backend -- a login that we
-// should defer to (and bill to them) instead of injecting Castle's key.
+// 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 Castle's key gets
-// injected and billed 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
+// ~/.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.
+// 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.
 function backendHasSavedAuth(backend) {
     const home = os.homedir();
     if (backend === "claude") {
-        return fs.existsSync(path.join(home, ".claude", ".credentials.json"));
+        const credPath = process.env.CASTLE_CLAUDE_CREDENTIALS_PATH ??
+            path.join(home, ".claude", ".credentials.json");
+        return fs.existsSync(credPath);
     }
     if (backend === "cursor") {
         return cursorHasUserLogin(home);
     }
     return false;
 }
-// Env for an agent spawn: inject Castle's key ONLY when the backend has no saved
-// auth of the user's own. This is what lets internal testers run on their own
-// subscription (log in once in the terminal) instead of Castle's key.
+// 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
+//     (scoped token) untouched -- the metered default in a sandbox, and a no-op
+//     locally where nothing is injected.
+//   - 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.
+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
+// saved auth of the user's own. This is what lets internal testers run on their
+// own subscription (log in once in the terminal) instead of Castle's key. The
+// claude path no longer routes through here -- see envForClaudeSpawn /
+// resolveAnthropicAuth (this stays generic but is only ever called for cursor).
 function envForAgentSpawn(backend) {
     const env = { ...process.env };
     const keyName = BACKEND_KEY_ENV[backend];
@@ -1467,7 +1573,8 @@ async function runAgentSmith(opts) {
             role: opts.role,
             extraHeaders: opts.extraHeaders,
             model: opts.model,
-            apiKey: openrouterApiKey(),
+            apiKey: opts.apiKey,
+            baseUrl: opts.baseUrl,
             reasoningEffort: opts.openrouterTuning?.reasoningEffort,
             routing: opts.openrouterTuning?.routing,
             // "" (auto) becomes undefined so no provider.order is sent.
@@ -1530,9 +1637,10 @@ function configFailure(reason, detail, extra) {
 async function preflightOpenrouterRun(opts) {
     if (!roleUsesOpenrouter(opts.backend, opts.claudeModel))
         return null;
-    const apiKey = openrouterApiKey();
+    const auth = opts.orAuth ?? resolveOpenrouterAuth();
+    const apiKey = auth.key;
     if (!apiKey) {
-        return configFailure("no-key", `no ${OPENROUTER_KEY_NAME} is set (checked ${CASTLE_KEYS_PATH} and the environment)`);
+        return configFailure("no-key", `no ${OPENROUTER_KEY_NAME} is set (checked ${CASTLE_USER_KEYS_PATH}, ${CASTLE_KEYS_PATH}, and the environment)`);
     }
     const model = opts.openrouterModel.trim();
     if (!model) {
@@ -1541,7 +1649,7 @@ async function preflightOpenrouterRun(opts) {
     // Key and slug checks are independent, so overlap them rather than paying
     // both round-trips in series. Both are cached and single-flighted.
     const [key, slug] = await Promise.all([
-        checkOpenrouterKey(apiKey),
+        checkOpenrouterKey(apiKey, { direct: auth.mode === "user-key" }),
         checkOpenrouterModel(model),
     ]);
     if (key.status === "bad-key") {
@@ -1568,11 +1676,17 @@ async function preflightOpenrouterRun(opts) {
 // (buildAgentInvocation -> runAgentCli). Everything downstream consumes the
 // same CliRunResult contract either way.
 async function runAgentTurn(opts) {
+    // Resolve the OpenRouter credential ONCE and reuse it for pre-flight, the run,
+    // and metering, so validation, spend, and the direct/proxy routing decision
+    // can never diverge. Null on a non-OpenRouter path.
+    const orAuth = roleUsesOpenrouter(opts.backend, opts.claudeModel)
+        ? resolveOpenrouterAuth()
+        : null;
     // 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);
+    const failure = await preflightOpenrouterRun({ ...opts, orAuth });
     if (failure) {
         return {
             ok: false,
@@ -1589,13 +1703,18 @@ async function runAgentTurn(opts) {
     // conversation -- nothing is resumed).
     const sessionId = newAgentSessionId(opts.role);
     if (opts.backend === "smith") {
+        // roleUsesOpenrouter is true for smith, so orAuth is non-null here.
+        const direct = orAuth.mode === "user-key";
         return runAgentSmith({
             cwd: opts.cwd,
             role: opts.role,
+            apiKey: orAuth.key,
+            baseUrl: direct ? OPENROUTER_DIRECT_CHAT_BASE : undefined,
             extraHeaders: meteringHeaders({
                 deckDir: opts.cwd,
                 sessionId,
                 route: "openrouter",
+                direct,
             }),
             model: opts.openrouterModel,
             prompt: opts.prompt,

package/dist/api.d.ts

@@ -77,6 +77,14 @@ export interface WebDeckSource {
     archiveUrl: string;
     updatedAt: string;
 }
+export interface DeckMeta {
+    deckId: string;
+    title: string | null;
+    creator: {
+        username: string;
+    } | null;
+}
+export declare function deckMeta(deckId: string): Promise<DeckMeta | null>;
 export declare function webDeckSource(deckId: string): Promise<WebDeckSource | null>;
 export declare function saveWebDeckSource(deckId: string, uploadId: string): Promise<WebDeckSource>;
 export {};

package/dist/api.js

@@ -127,6 +127,16 @@ export async function createWebDeckSourceUploadConfig(deckId) {
     handleAPIError(data);
     return pickData(data, 'createWebDeckSourceUploadConfig');
 }
+// Title + author, for naming an import. Readable without auth for the same decks
+// webDeckSource is (unlisted ones), so this works in a sandbox with no login.
+export async function deckMeta(deckId) {
+    const data = await graphql(`query($deckId: ID!) {
+       deck(deckId: $deckId) {
+         deckId title creator { username }
+       }
+     }`, { deckId });
+    return data?.data?.deck ?? null;
+}
 export async function webDeckSource(deckId) {
     const data = await graphql(`query($deckId: ID!) {
        webDeckSource(deckId: $deckId) {

package/dist/bundle.js

@@ -1,11 +1,11 @@
 import * as path from 'path';
 import { build } from 'vite';
 import { viteSingleFile } from 'vite-plugin-singlefile';
-import { sceneFilesPlugin } from './vitePlugins.js';
+import { sceneFilesPlugin, importsAliasPlugin } from './vitePlugins.js';
 export async function bundleProject(dir) {
     const result = await build({
         root: dir,
-        plugins: [viteSingleFile(), sceneFilesPlugin()],
+        plugins: [importsAliasPlugin(), viteSingleFile(), sceneFilesPlugin()],
         build: {
             write: false,
             rollupOptions: {

package/dist/get-deck.d.ts

@@ -1,4 +1,4 @@
-export declare function extractTarball(archivePath: string, targetDir: string): Promise<void>;
 export declare function getDeck(dir: string, options?: {
     deckId?: string;
+    force?: boolean;
 }): Promise<void>;

package/dist/get-deck.js

@@ -1,46 +1,102 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { spawn } from 'child_process';
 import { nanoid } from 'nanoid';
 import * as api from './api.js';
 import { normalizeDeckPackageJson } from './normalize.js';
+import { archiveSource, runTar, SOURCE_ARCHIVE_EXCLUDES } from './save-deck.js';
+// Refreshing a deck already in the target replaces its source, so a file deleted
+// upstream actually disappears here -- untarring over the old tree would leave it
+// behind. What survives is exactly what the source archive doesn't carry, and it
+// has to be: those paths are missing from the server's copy AND from the backup
+// below (which is that same archive), so deleting one destroys it outright. They're
+// all machine-local anyway -- deps, build output, .castle runtime state, .git.
+const KEEP = SOURCE_ARCHIVE_EXCLUDES;
 function readCastleJson(dir) {
     const p = path.join(dir, 'castle.json');
     if (!fs.existsSync(p))
         return null;
-    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
 }
-export function extractTarball(archivePath, targetDir) {
-    return new Promise((resolve, reject) => {
-        const child = spawn('tar', ['-xzf', archivePath, '-C', targetDir], {
-            stdio: ['ignore', 'inherit', 'pipe'],
-        });
-        let stderr = '';
-        child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
-        child.on('error', reject);
-        child.on('close', (code) => {
-            if (code !== 0) {
-                reject(new Error(`tar exited with code ${code}: ${stderr}`));
-                return;
+// Whether the target already holds a deck, as opposed to being new, empty, or
+// holding only the dirs a refresh preserves.
+function hasSource(dir) {
+    if (!fs.existsSync(dir))
+        return false;
+    return fs.readdirSync(dir).some((entry) => !KEEP.includes(entry));
+}
+function newestSourceMtime(dir) {
+    let newest = 0;
+    const walk = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (current === dir && KEEP.includes(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            let stat;
+            try {
+                stat = fs.statSync(full);
+            }
+            catch {
+                continue; // raced deletion / broken symlink
             }
-            resolve();
-        });
-    });
+            newest = Math.max(newest, stat.mtimeMs);
+            if (entry.isDirectory())
+                walk(full);
+        }
+    };
+    walk(dir);
+    return newest;
 }
+// Fetch a deck's saved source into <dir>. If the deck is already there, its source
+// is REPLACED with the server's latest -- the way to refresh a copy that has fallen
+// behind (edited on another machine, or on a sandbox host this one isn't).
+//
+// Deps are left to `castle-web install`, like a git pull leaves them to you.
 export async function getDeck(dir, options = {}) {
     const targetDir = path.resolve(dir);
-    const existing = readCastleJson(targetDir);
-    const deckId = options.deckId ?? existing?.deckId;
+    const localDeckId = readCastleJson(targetDir)?.deckId;
+    const deckId = options.deckId ?? localDeckId;
     if (!deckId) {
         console.error(`No deckId. Either pass --deck-id <id> or run from a directory whose castle.json has one.`);
         process.exit(1);
     }
+    // The staleness guard below can't catch fetching deck B over a copy of deck A --
+    // nothing about A's mtimes says "wrong target", so a cold copy passes and gets
+    // silently replaced.
+    if (localDeckId && deckId !== localDeckId && !options.force) {
+        console.error(`This directory holds deck ${localDeckId}, but --deck-id ${deckId} was passed.`);
+        console.error(`Pass --force to replace deck ${localDeckId}'s source with deck ${deckId}'s.`);
+        process.exit(1);
+    }
     const source = await api.webDeckSource(deckId);
     if (!source) {
         console.error(`No source archive on server for deck ${deckId}. Run \`castle-web save-deck\` first.`);
         process.exit(1);
     }
+    const refreshing = hasSource(targetDir);
+    // Local edits newer than the server's copy are the ones worth keeping, and the
+    // replace would destroy them -- stop rather than guess. Extraction restores the
+    // archive's own mtimes, so refreshing twice doesn't trip this.
+    if (refreshing && !options.force) {
+        const serverMs = Date.parse(source.updatedAt);
+        if (!Number.isFinite(serverMs)) {
+            console.error(`Can't tell whether this copy is newer than the saved deck: unreadable save time from the server (${source.updatedAt}).`);
+            console.error(`Pass \`--force\` to replace this copy anyway.`);
+            process.exit(1);
+        }
+        const localMs = newestSourceMtime(targetDir);
+        if (localMs > serverMs) {
+            console.error(`This copy has changes newer than the saved deck (local ${new Date(localMs).toISOString()} > server ${source.updatedAt}).`);
+            console.error(`Run \`castle-web save-deck\` to keep them, or \`--force\` to discard them.`);
+            process.exit(1);
+        }
+    }
+    // Everything that can fail over the network happens before anything is deleted.
     console.log(`Fetching ${source.archiveUrl}`);
     const res = await fetch(source.archiveUrl, { signal: AbortSignal.timeout(60000) });
     if (!res.ok) {
@@ -49,11 +105,26 @@ export async function getDeck(dir, options = {}) {
     const buf = Buffer.from(await res.arrayBuffer());
     const sizeKB = buf.length / 1024;
     console.log(`Archive: ${sizeKB.toFixed(1)}KB (updated ${source.updatedAt})`);
-    fs.mkdirSync(targetDir, { recursive: true });
     const tmpFile = path.join(os.tmpdir(), `castle-get-${nanoid(8)}.tar.gz`);
     fs.writeFileSync(tmpFile, buf);
     try {
-        await extractTarball(tmpFile, targetDir);
+        if (refreshing) {
+            // A corrupt archive discovered mid-extract would find the old source already
+            // deleted; prove tar can read the whole thing before touching anything.
+            await runTar(['-tzf', tmpFile]);
+            // Kept out of the deck's parent on purpose: castle-www lists a user's cloud
+            // decks by globbing the decks dir, so a backup beside the deck reads as one.
+            const backup = path.join(os.tmpdir(), `castle-get-deck-backup-${nanoid(8)}.tar.gz`);
+            fs.writeFileSync(backup, await archiveSource(targetDir));
+            console.log(`Backed up the current source to ${backup}`);
+            for (const entry of fs.readdirSync(targetDir)) {
+                if (KEEP.includes(entry))
+                    continue;
+                fs.rmSync(path.join(targetDir, entry), { recursive: true, force: true });
+            }
+        }
+        fs.mkdirSync(targetDir, { recursive: true });
+        await runTar(['-xzf', tmpFile, '-C', targetDir]);
     }
     finally {
         try {
@@ -64,5 +135,5 @@ export async function getDeck(dir, options = {}) {
     if (normalizeDeckPackageJson(targetDir)) {
         console.log(`Repointed package.json at this machine's sdk/cli`);
     }
-    console.log(`Extracted to ${targetDir}`);
+    console.log(`${refreshing ? 'Updated' : 'Extracted to'} ${targetDir}`);
 }