castle-web-cli 0.4.107 → 0.4.109

package/dist/agent-prompts.js

@@ -6,6 +6,20 @@
 // Router calls are stateless (a fresh cursor-agent print run each time) so the
 // transcript is the only memory.
 const TRANSCRIPT_LIMIT = 40;
+// Byte ceiling on the replayed transcript, applied AFTER TRANSCRIPT_LIMIT.
+// The count cap above bounds how many messages replay, not how big they are --
+// forty long ones clear 128KB easily. That matters because the whole prompt is
+// handed to the backend CLI as a single argv entry, and Linux caps one argument
+// at MAX_ARG_STRLEN (128KB): past it, spawn() throws E2BIG and the turn dies
+// before it starts. Since the transcript is the only term here that grows
+// without bound (it accumulates for the life of the deck), it's the one that
+// needs a byte budget.
+//
+// Sized to leave room for everything else the prompt carries: the rules
+// (~10KB), the deck's quick reference (~13KB), the file tree, the smith-only
+// deck contents (ROUTER_DECK_CONTENTS_BUDGET, 40KB), the task board, and this
+// turn's instruction.
+const TRANSCRIPT_BYTE_BUDGET = 32 * 1024;
 const ROUTER_RULES = `You are Castle's create assistant: the fast conversational router for a game-making session. The deck (game project) lives in the current directory and runs live in a pane right next to this chat.
 
 What a deck is: a normal web project served by vite -- index.html plus plain JS/JSX modules, with real npm dependencies (more can be installed), the castle-web-sdk package, and usually a kit framework whose engine, behaviors, scenes, editors, and drawings are ordinary files in this directory. The web platform is fully available (DOM, canvas, npm libraries like react, three, etc.). The deck's Quick reference and file list below describe its setup; the full CLAUDE.md / AGENTS.md has deeper detail. NEVER claim something is impossible or unsupported on the platform without checking that context (or, for specifics it doesn't cover, the deck's files) first.
@@ -66,20 +80,55 @@ Conversation style:
 - The user sees a live task board above the chat -- never re-announce task status yourself.
 - Spawning a task does NOT apply the change -- tasks run for minutes and finish on the board. Talk about spawned work in future tense ("this will dial the shake back"), and NEVER ask how a change feels right after spawning it -- the user cannot have tried it yet. Save "how is it?" for things whose task already finished.
 - The user playtests in the pane beside this chat; finished work shows up there after a reload.`;
+function renderTranscriptLine(m) {
+    if (m.role === "user")
+        return `user: ${m.text}`;
+    const label = m.interrupted
+        ? "you (interrupted draft -- not a complete reply)"
+        : "you";
+    return `${label}: ${m.text}`;
+}
+// Cut a line to fit `budget` BYTES without splitting a multi-byte character
+// (a half-written character would render as a replacement glyph mid-sentence).
+function truncateToBytes(line, budget) {
+    const buf = Buffer.from(line, "utf8");
+    if (buf.byteLength <= budget)
+        return line;
+    return new TextDecoder("utf8", { fatal: false, ignoreBOM: true })
+        .decode(buf.subarray(0, budget))
+        .replace(/�+$/, "");
+}
 function renderTranscript(messages) {
     const recent = messages.slice(-TRANSCRIPT_LIMIT);
     if (recent.length === 0)
         return "(no conversation yet)";
-    return recent
-        .map((m) => {
-        if (m.role === "user")
-            return `user: ${m.text}`;
-        const label = m.interrupted
-            ? "you (interrupted draft -- not a complete reply)"
-            : "you";
-        return `${label}: ${m.text}`;
-    })
-        .join("\n\n");
+    // Newest-first, keeping WHOLE messages until the budget is spent: the recent
+    // exchanges are the ones a reply actually depends on, and half-including a
+    // message would read as the user having said something they didn't.
+    const kept = [];
+    let bytes = 0;
+    for (let i = recent.length - 1; i >= 0; i -= 1) {
+        const line = renderTranscriptLine(recent[i]);
+        // +2 for the "\n\n" this line will be joined with.
+        const size = Buffer.byteLength(line, "utf8") + 2;
+        if (bytes + size > TRANSCRIPT_BYTE_BUDGET) {
+            // One message bigger than the whole budget (a huge paste) still has to
+            // yield something -- an empty transcript would strand the router with no
+            // idea what was just asked. Truncate that one rather than drop it, so the
+            // bound genuinely holds no matter what a single message contains.
+            if (kept.length === 0) {
+                kept.push(truncateToBytes(line, TRANSCRIPT_BYTE_BUDGET));
+            }
+            break;
+        }
+        kept.unshift(line);
+        bytes += size;
+    }
+    const elided = recent.length - kept.length;
+    if (elided <= 0)
+        return kept.join("\n\n");
+    const plural = elided === 1 ? "message" : "messages";
+    return `(${elided} earlier ${plural} trimmed to keep this prompt within its size limit)\n\n${kept.join("\n\n")}`;
 }
 function renderTasks(tasks) {
     if (tasks.length === 0)

package/dist/agent.js

@@ -14,7 +14,7 @@
 // Backend CLI: cursor-agent in headless print mode (stream-json). The router
 // runs with --mode ask (read-only at the CLI level); task agents run with
 // --force. Claude support can slot in later behind runAgentCli.
-import { execFileSync, spawn } from "child_process";
+import { execFileSync, spawn, } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -26,7 +26,7 @@ import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, prime
 import { classifyProviderError, failureCopy, setReaderTimeZone, } from "./agent-failures.js";
 import { fetchBudget, meteringHeaders, newAgentSessionId, reportCursorRun, withCustomHeaders, } from "./metering.js";
 import { anthropicKeyHelperCommand, claudeHasSavedLogin, cursorAuthPath, cursorHasUserLogin, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from "./byo-auth.js";
-import { accountsSnapshot, loginProviderFor, writeCredential, } from "./byo-accounts.js";
+import { accountsSnapshot, loginProviderFor, watchCredentials, writeCredential, } from "./byo-accounts.js";
 import { cancelLogin, logout, startLogin, submitLoginCode, } from "./byo-login.js";
 import { runAgentNative } from "./native/loop.js";
 import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
@@ -1341,11 +1341,33 @@ function makeAgentEventHandler(opts, state) {
 // end with a result event carrying the canonical final text.
 function runAgentCli(opts) {
     return new Promise((resolve) => {
-        const child = spawn(opts.command, opts.args, {
-            cwd: opts.cwd,
-            env: opts.env,
-            stdio: ["ignore", "pipe", "pipe"],
-        });
+        // spawn() throws SYNCHRONOUSLY for the failures the OS rejects at exec
+        // time -- in practice E2BIG, when the prompt argv exceeds Linux's
+        // MAX_ARG_STRLEN (128KB per argument). That throw escapes this executor
+        // and rejects the promise, so it never reaches the child.on("error")
+        // handler below and never becomes an AgentFailure: the turn dies
+        // unclassified and the composer spins forever with nothing shown. Settle
+        // it here in the same shape that handler uses so it lands on the normal
+        // "spawn" copy instead. The declared type mirrors the stdio tuple below:
+        // stdin ignored, stdout/stderr piped.
+        let child;
+        try {
+            child = spawn(opts.command, opts.args, {
+                cwd: opts.cwd,
+                env: opts.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            resolve({
+                ok: false,
+                finalText: "",
+                error: `could not run ${opts.command}: ${message}`,
+                failure: { kind: "spawn", detail: `${opts.command}: ${message}` },
+            });
+            return;
+        }
         opts.children.add(child);
         opts.onSpawn?.(child.pid);
         const log = opts.logPath
@@ -3022,25 +3044,73 @@ function applyAgentSettings(incoming, ctx) {
     ctx.broadcast({ type: "settings", settings });
     void broadcastSettingsWarnings(ctx);
 }
-// Store or remove one BYO credential for the editor's Accounts rows. Unlike a
-// settings change this persists nothing itself -- byo-accounts owns the file --
-// and it always answers with a fresh snapshot, including on a rejected write,
-// so a client that sent something invalid learns why instead of watching its
-// input silently do nothing. The snapshot carries presence and a hint only; no
-// frame from here ever moves a key value toward a browser.
-function broadcastAccounts(broadcast, error) {
-    broadcast({
-        type: "accounts",
-        accounts: accountsSnapshot(),
-        ...(error ? { accountsError: error } : {}),
-    });
+// Belt to watchCredentials' braces: a directory that didn't exist at boot has
+// no watcher on it, and an inotify watch can be lost. Slow, because the watch is
+// what makes this feel live -- this only has to stop a miss from lasting.
+const ACCOUNTS_POLL_MS = 15_000;
+// The editor's view of which credentials exist, kept live. Unlike settings --
+// which nothing outside this process writes -- a credential changes behind the
+// editor's back all the time: `claude /login` or `cursor-agent logout` in the
+// terminal panel, a hand-edited user-keys.json, an agent run that refreshes an
+// OAuth token. Push those, or the popover reports whatever was true when the
+// page loaded and a terminal sign-in reads as having done nothing.
+//
+// The snapshot carries presence and a hint only; no frame from here ever moves
+// a key value toward a browser.
+function createAccountsFeed(opts) {
+    let last = "";
+    // Tracked apart from the whole snapshot so a sign-in's phase transitions
+    // (starting -> awaiting-code -> ...) don't each cost a budget fetch: they
+    // move `login`, never a credential.
+    let lastProviders = "";
+    function push(error) {
+        const accounts = accountsSnapshot();
+        const serialized = JSON.stringify(accounts);
+        const providers = JSON.stringify(accounts.providers);
+        if (providers !== lastProviders) {
+            lastProviders = providers;
+            opts.onCredentialChange();
+        }
+        // A refusal always goes out. It is the only answer a rejected write gets,
+        // and a rejected write leaves the snapshot identical by definition -- so
+        // deduping on the snapshot alone would swallow exactly the frame that
+        // carries the reason.
+        if (serialized === last && !error)
+            return;
+        last = serialized;
+        opts.broadcast({
+            type: "accounts",
+            accounts,
+            ...(error ? { accountsError: error } : {}),
+        });
+    }
+    function snapshot() {
+        const accounts = accountsSnapshot();
+        last = JSON.stringify(accounts);
+        lastProviders = JSON.stringify(accounts.providers);
+        return accounts;
+    }
+    const stopWatch = watchCredentials(() => push());
+    const timer = setInterval(() => {
+        if (opts.hasClients())
+            push();
+    }, ACCOUNTS_POLL_MS);
+    timer.unref?.();
+    return {
+        snapshot,
+        push,
+        stop: () => {
+            stopWatch();
+            clearInterval(timer);
+        },
+    };
 }
 function applyCredentialChange(msg, ctx) {
     const clearing = msg.type === "clear-credential";
     if (!clearing && typeof msg.value !== "string")
         return;
     const result = writeCredential(msg.id, clearing ? null : msg.value);
-    broadcastAccounts(ctx.broadcast, result.ok
+    ctx.pushAccounts(result.ok
         ? undefined
         : { id: typeof msg.id === "string" ? msg.id : "", message: result.message });
 }
@@ -3518,6 +3588,11 @@ export function createAgentServer(opts) {
         hasClients: () => clients.size > 0,
         castlePaid: () => anyRoleIsCastlePaid(settings),
     });
+    const accountsFeed = createAccountsFeed({
+        broadcast,
+        hasClients: () => clients.size > 0,
+        onCredentialChange: () => usageFeed.refresh(),
+    });
     const applySettings = (incoming) => {
         applyAgentSettings(incoming, { settings, settingsPath, broadcast });
         // A backend switch can change who pays (a cursor role always spends
@@ -3595,7 +3670,7 @@ export function createAgentServer(opts) {
             running: routerQueue.isRunning(),
             queued: routerQueue.queuedSnippets(),
             usage: usageFeed.latest(),
-            accounts: accountsSnapshot(),
+            accounts: accountsFeed.snapshot(),
         };
         socket.send(JSON.stringify(hello));
         // A newly attached client is the one moment the cached value may be stale
@@ -3638,12 +3713,12 @@ export function createAgentServer(opts) {
             }
             else if (msg.type === "set-credential" ||
                 msg.type === "clear-credential") {
-                applyCredentialChange(msg, { broadcast });
+                applyCredentialChange(msg, { pushAccounts: accountsFeed.push });
             }
             else if (msg.type === "account-login") {
                 const provider = loginProviderFor(msg.id);
                 if (provider)
-                    startLogin(provider, () => broadcastAccounts(broadcast));
+                    startLogin(provider, () => accountsFeed.push());
             }
             else if (msg.type === "account-login-code" && typeof msg.value === "string") {
                 submitLoginCode(msg.value);
@@ -3654,7 +3729,7 @@ export function createAgentServer(opts) {
             else if (msg.type === "account-logout") {
                 const provider = loginProviderFor(msg.id);
                 if (provider)
-                    logout(provider, () => broadcastAccounts(broadcast));
+                    logout(provider, () => accountsFeed.push());
             }
             else if (msg.type === "client-timezone" && typeof msg.timeZone === "string") {
                 setReaderTimeZone(msg.timeZone);
@@ -3690,6 +3765,7 @@ export function createAgentServer(opts) {
         }
         stopChildRegistry();
         usageFeed.stop();
+        accountsFeed.stop();
         wss.close();
         void playtestBrowserManager.shutdown();
     }

package/dist/byo-accounts.d.ts

@@ -18,6 +18,23 @@ export interface AccountsState {
     login: LoginState | null;
 }
 export declare function accountsSnapshot(): AccountsState;
+/**
+ * Call `onChange` when a credential this module reports on changes on disk.
+ *
+ * The editor is not the only writer: `claude /login` and `cursor-agent login`
+ * in the terminal panel, an agent run that refreshes an OAuth token, and a
+ * hand-edited `user-keys.json` all change the answer behind its back. Without
+ * this the account state is whatever was true when the page loaded, so a
+ * terminal sign-in looks like it did nothing until a reload.
+ *
+ * Directories, never the credential files themselves: the CLIs replace those by
+ * rename, which leaves a file watch holding the old inode and silently deaf --
+ * the same reason castle-sandboxes persists these paths as directory symlinks.
+ * A directory that doesn't exist yet (no `~/.castle` until the first key) simply
+ * isn't watched; the caller's poll is what covers that, and losing a watcher
+ * costs freshness, never correctness.
+ */
+export declare function watchCredentials(onChange: () => void): () => void;
 export type CredentialWriteResult = {
     ok: true;
     changed: boolean;

package/dist/byo-accounts.js

@@ -4,13 +4,13 @@
 //
 // Split from byo-auth.ts deliberately. That module is the RESOLVER -- pure,
 // read-only, and imported by the terminal shim's helper on EVERY `claude` run
-// (see installClaudeShim), so it must stay free of anything stateful. This one
+// (see installCliShims), so it must stay free of anything stateful. This one
 // is allowed to write. The login subprocesses live in byo-login.ts; this module
 // only reports their state as part of one snapshot.
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
-import { CASTLE_USER_KEYS_PATH, claudeHasSavedLogin, cursorHasUserLogin, readUserKeys, } from "./byo-auth.js";
+import { CASTLE_USER_KEYS_PATH, claudeCredentialsPath, claudeHasSavedLogin, cursorAuthPath, cursorHasUserLogin, readUserKeys, } from "./byo-auth.js";
 import { activeLogin } from "./byo-login.js";
 import { inCastleSandbox } from "./metering.js";
 // Providers, not credentials: Anthropic is reachable by EITHER a key or a
@@ -90,6 +90,60 @@ export function accountsSnapshot() {
         login: activeLogin(),
     };
 }
+// Several events land for one credential change (a rename is a delete plus a
+// create, and the CLIs write neighbouring files in the same breath); one
+// snapshot after the burst is what the editor wants.
+const WATCH_DEBOUNCE_MS = 250;
+/**
+ * Call `onChange` when a credential this module reports on changes on disk.
+ *
+ * The editor is not the only writer: `claude /login` and `cursor-agent login`
+ * in the terminal panel, an agent run that refreshes an OAuth token, and a
+ * hand-edited `user-keys.json` all change the answer behind its back. Without
+ * this the account state is whatever was true when the page loaded, so a
+ * terminal sign-in looks like it did nothing until a reload.
+ *
+ * Directories, never the credential files themselves: the CLIs replace those by
+ * rename, which leaves a file watch holding the old inode and silently deaf --
+ * the same reason castle-sandboxes persists these paths as directory symlinks.
+ * A directory that doesn't exist yet (no `~/.castle` until the first key) simply
+ * isn't watched; the caller's poll is what covers that, and losing a watcher
+ * costs freshness, never correctness.
+ */
+export function watchCredentials(onChange) {
+    const dirs = new Set([
+        claudeCredentialsPath(),
+        cursorAuthPath(os.homedir()),
+        CASTLE_USER_KEYS_PATH,
+    ].map((p) => path.dirname(p)));
+    let timer = null;
+    const fire = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(onChange, WATCH_DEBOUNCE_MS);
+        timer.unref?.();
+    };
+    const watchers = [];
+    for (const dir of dirs) {
+        try {
+            const w = fs.watch(dir, fire);
+            // A watch that dies later (the directory is removed, inotify runs out)
+            // must not take the serve with it -- fs.watch reports those as an error
+            // event, which is fatal when nothing is listening.
+            w.on("error", () => undefined);
+            watchers.push(w);
+        }
+        catch {
+            /* not watchable here */
+        }
+    }
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        for (const w of watchers)
+            w.close();
+    };
+}
 // Generous -- provider key formats are not ours to predict -- but bounded, so a
 // stray paste of a whole file can't land in the credential store.
 const MAX_KEY_LENGTH = 500;

package/dist/byo-auth.d.ts

@@ -17,6 +17,7 @@ export type OpenrouterAuth = {
     mode: "proxy";
     key: string;
 };
+export declare function claudeCredentialsPath(): string;
 export declare function claudeHasSavedLogin(): boolean;
 export declare function cursorAuthPath(home: string): string;
 export declare function cursorHasUserLogin(home: string): boolean;
@@ -25,5 +26,10 @@ export declare const ANTHROPIC_CREDENTIAL_ENV: readonly ["ANTHROPIC_API_KEY", "A
 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;
-export declare function claudeShellEnvScript(env: NodeJS.ProcessEnv, shimDir: string): string;
-export declare function installClaudeShim(deckDir: string): string | null;
+export declare const SHIMMED_CLIS: readonly ["claude", "cursor-agent"];
+export type ShimmedCli = (typeof SHIMMED_CLIS)[number];
+export declare function claudeShellEnvScript(env: NodeJS.ProcessEnv, args?: readonly string[]): string;
+export declare function cursorShellEnvScript(env: NodeJS.ProcessEnv): string;
+export declare function shimEnvScript(cli: string, env: NodeJS.ProcessEnv, shimDir: string, args?: readonly string[]): string;
+export declare function ensureClaudeOnboarded(): void;
+export declare function installCliShims(deckDir: string): string | null;