castle-web-cli 0.4.173 → 0.4.175

package/dist/agent-prompts.d.ts

@@ -75,7 +75,11 @@ export declare function renderPlanDigest(plan: RouterPlanOpts, tasks: PromptTask
 export declare function planOpenQuestionLines(fileText: string): string[];
 export declare function renderTaskPlanSlice(fileText: string, item: string | undefined, finishedWork?: PlanFinishedWork[]): string;
 export declare const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
-export declare function buildRouterPrompt(opts: {
+export interface RouterPromptParts {
+    system: string;
+    user: string;
+}
+export interface RouterPromptOpts {
     deckLabel: string;
     quickReference?: string;
     deckTree?: string;
@@ -85,7 +89,9 @@ export declare function buildRouterPrompt(opts: {
     plan?: RouterPlanOpts;
     playtest?: boolean;
     instruction: string;
-}): string;
+}
+export declare function buildRouterPromptParts(opts: RouterPromptOpts): RouterPromptParts;
+export declare function buildRouterPrompt(opts: RouterPromptOpts): string;
 export declare function userTurnInstruction(opts: {
     messages: string[];
     interruptedDraft?: string;

package/dist/agent-prompts.js

@@ -35,6 +35,7 @@ Hard rules:
 - IMPORTS ARE YOURS, and they are the one exception to the rule above. Run \`castle-web list-decks --kind kits\` (also \`mine\` and \`saved\`) to see what this deck can import, and \`castle-web add-import <deckIdOrUrl>\` to add one -- both directly, not through a task. Do NOT claim you can list or import anything until you have actually run these; do not describe imports you have not looked at. \`list-decks\` prints one deck per line starting with the id \`add-import\` takes, and marks the ones this deck already has. A pasted castle.xyz deck link works in place of an id. Everything else about a deck's files still goes to task agents.
 - Imported files are READ-ONLY, which is what to say when the user asks whether they can change something a kit or another import gave them, or why an edit to one did not stick: the deck takes its own version of that one file -- a fork, stored beside the import and used in its place -- and that version is what runs. Forking is how their own data and code changes override an import's, and a task agent does it; the tradeoff, worth saying plainly, is that a file done this way stops picking up changes when the import itself is updated, so it stays to the few files the change actually needs. Often it does not come to a fork at all, which is the better thing to say first: a kit picks up the deck's own behaviors and systems, so new logic is usually just a new file in the deck.
 - You are the fast lane: get to your final reply as quickly as possible. When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task, and never read files just to learn conventions already covered by the Quick reference.${playtest ? `\n${PLAYTEST_ROUTER_RULE}` : ""}
+- When you point the user at a file, a line, or a tunable value, write it as a link they can tap: \`[label](game.js)\` for a file, \`[label](game.js#L108)\` for a line, \`[label](game.js#params)\` for a file's tunable values and \`[label](game.js#params:enemySpeed)\` for ONE of them (the key exactly as it is written in that file's \`PARAMS\` object -- \`player.speed\` for a nested one). The label is your own words for the thing; the path must be exact and must be a file this deck actually has, or it renders as plain text. A bare \`game.js#108\` in a sentence links too. Cite a line number ONLY when you have read that file with numbered lines -- any deck contents in this prompt carry none, so never count them yourself; link the file or its params instead when you are unsure.
 - Launch a SET of small steps the user tests one by one -- a pipeline, never one big task they wait on, never untestable fragments. One interacting mechanic = one task (paddle + ball + bricks = one playable core, not three). First step = the smallest genuinely playable thing; later steps build it out. Match breadth to ambition ("basic" = a few steps; "go wild" = many). You're optimizing the user's taste and feedback -- more small testable steps = more points where they steer it into something theirs.
 - The whole goal: every piece of work TESTABLE in actual gameplay ASAP. Start every task as early as possible and run them in PARALLEL. Do NOT break tasks down by which files they touch, and never add \`after:\` just to avoid two tasks editing the same file -- tasks make surgical edits and overlap fine. The only real dependency between tasks is INFORMATION: a task is blocked only when it needs a fact it does not yet have.
 - Dissolve those information-dependencies with a CONTRACT decided up front, instead of serializing tasks. Before spawning, pin the shared names the tasks will agree on -- scene file names, behavior names, drawing file names, tags -- and give each parallel task the exact names it must CREATE or REFERENCE. Pinned names must be EXACT filenames, extension included -- \`drawings/ship.sprite\` in a kit deck (the kit's CLAUDE.md names the format), \`drawings/ship.svg\` in a bare one. A bare deck has no kit to define a default art format or loader, so its contract must also state the format and loading approach every consumer will use. Then they all run at once and converge to a working game with NO follow-up wiring task: the scene task places actors referencing behaviors and drawings by their agreed names before those files even exist; the behavior tasks create those behavior names; the drawing tasks create those drawing files. (Art: pin an exact drawing filename like \`drawings/ship.sprite\` up front -> the scene task points an actor at it while another task draws it, in parallel; no place-it-later task.) Fall back to a separate waiting wire-in task (\`after:\` the maker, on the least possible) ONLY when a task truly needs another's actual produced output, not just its agreed name. Working out this breakdown -- what to parallelize, which names to pin up front -- is the core of your job and differs per game.
@@ -820,7 +821,7 @@ function renderTasks(tasks, showItems) {
 // not included" and burns its first turns hunting for CLAUDE.md. Exported so
 // the platform block (platformDoc.ts) can keep the sentence after itself.
 export const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
-export function buildRouterPrompt(opts) {
+export function buildRouterPromptParts(opts) {
     // Making the ABSENCE explicit, not just omitting the section, matters: a
     // router on a bare/greenfield deck otherwise has no way to tell "no docs
     // exist" from "the docs section just wasn't included in this prompt", and
@@ -842,17 +843,19 @@ export function buildRouterPrompt(opts) {
     const plan = opts.plan
         ? `\n\n== plan ==\n${renderPlanDigest(opts.plan, opts.tasks)}`
         : "";
-    // Section order is stable-to-volatile for prompt caching: rules + deck
-    // identity never change within a serve, the transcript is append-only, and
-    // the churning state (file tree, task board, instruction) rides at the tail
-    // so a task creating a file doesn't invalidate the cached transcript prefix.
-    return `${routerRules(opts.plan !== undefined, opts.playtest === true)}
+    // Two parts, split for prompt caching. `system` holds what is the same from
+    // one turn to the next within a serve -- the rules, the deck identity, the
+    // file tree and (smith) the deck source -- and each backend sends it as
+    // system text, which is the prefix the provider caches turn after turn. A
+    // file edit invalidates it; a chat turn does not. `user` holds what changes
+    // every turn: the transcript, the plan, the board and this instruction.
+    return {
+        system: `${routerRules(opts.plan !== undefined, opts.playtest === true)}
 
 == deck ==
-${opts.deckLabel}${quickReference}
-
-== conversation so far ==
-${renderTranscript(opts.messages)}${deckFiles}${deckSource}${plan}
+${opts.deckLabel}${quickReference}${deckFiles}${deckSource}`,
+        user: `== conversation so far ==
+${renderTranscript(opts.messages)}${plan}
 
 == background tasks ==
 ${renderTasks(opts.tasks, opts.plan !== undefined)}
@@ -860,7 +863,13 @@ ${renderTasks(opts.tasks, opts.plan !== undefined)}
 == now ==
 ${opts.instruction}
 
-Reply now, as "you" in the conversation. Plain reply text only -- no role prefix.`;
+Reply now, as "you" in the conversation. Plain reply text only -- no role prefix.`,
+    };
+}
+// The router prompt as one string, system part first. What the goldens pin.
+export function buildRouterPrompt(opts) {
+    const parts = buildRouterPromptParts(opts);
+    return `${parts.system}\n\n${parts.user}`;
 }
 export function userTurnInstruction(opts) {
     const parts = [];
@@ -984,7 +993,7 @@ phase: wiring the paddle to touch
 
   - \`avatar\` -- what you're doing RIGHT NOW, exactly one of: \`thinking\` (figuring out the plan), \`reading\` (looking through files), \`building\` (writing game logic), \`painting\` (making or editing art/visuals), \`playing\` (trying it in the game).
   - \`phase\` -- a SHORT, plain-language line for this moment ("wiring the paddle to touch", "drawing the flag"). No file or code names. Update \`avatar\` and \`phase\` together each time your stage changes -- a few times across the task, not every turn. (You may also include \`progress: NN\` here, but the progress file above is the primary progress channel.)
-- Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, and no tour of how you built it -- that part is for you, not them. But DO name a file or a value where the user could act on it: a number they might want changed is worth naming, and worth naming the way they would find it ("enemy speed -- \`spawnRate\` in game.js"). Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
+- Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, and no tour of how you built it -- that part is for you, not them. But DO name a file or a value where the user could act on it: a number they might want changed is worth naming, and worth naming the way they would find it, as a link they can tap: "enemy speed -- [spawnRate](game.js#params:spawnRate)" when it is an entry in that file's \`PARAMS\` object, "[the spawn loop](game.js#L42)" for a place in the code (a line number only from a numbered read of the file). Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
 - If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
 - Never touch files under .castle/ other than ${opts.plan ? "those three paths" : "those two paths"}. (The version store lives there too, but you never edit it by hand -- \`castle-web save-version\` writes it for you.)`;
 }

package/dist/agent.js

@@ -27,7 +27,7 @@ import { WebSocketServer } from 'ws';
 import { rawDataToString } from './rawData.js';
 import { atomicWriteFileSync } from './atomicFile.js';
 import { AGENT_ATTACHMENT_PREFIX, AGENT_PLAYTEST_PREFIX, PLAN_FILE } from './localPaths.js';
-import { applyPlanOps, buildRouterPrompt, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
+import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
 import { readCastleJson } from './castleJson.js';
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from './openrouter-catalog.js';
 import { classifyProviderError, failureCopy, setReaderTimeZone, } from './agent-failures.js';
@@ -501,6 +501,17 @@ function claudeSettingsArg(auth) {
         ...(auth?.mode === 'user-key' ? { apiKeyHelper: anthropicKeyHelperCommand() } : {}),
     });
 }
+// The claude CLI puts every CLAUDE.md it finds, and a git-status note, into the
+// first user message of each process, ahead of the prompt. A router turn is a
+// new process, so that text (the kit guide: ~23k tokens on a kit deck) is sent
+// uncached on every call of every turn. The router already carries the deck's
+// quick reference and file tree in its cached system part, and can read a
+// guide on demand; tasks keep the CLI's own loading. Measured on a 30k-token
+// router prompt: a second turn goes from 40k tokens written to 4.6k.
+const ROUTER_CLAUDE_ENV = {
+    CLAUDE_CODE_DISABLE_CLAUDE_MDS: '1',
+    CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS: '1',
+};
 function buildAgentInvocation(backend, role, prompt, claudeModel, 
 // Already resolved for this role by the caller (router turns pass
 // settings.routerOpenrouterModel, task spawns settings.tasksOpenrouterModel).
@@ -512,7 +523,14 @@ metering,
 // The task this spawn belongs to, so its playtest frames land under
 // tasks/<id>/playtest/ and count against that task's call budget. Absent for
 // router turns, which get no playtest tool at all.
-taskId) {
+taskId, 
+// The stable part of a router prompt. claude takes it as appended system
+// text, which its own cache breakpoints cover; cursor has no such flag and
+// gets it ahead of the prompt.
+systemPrompt) {
+    const systemText = [systemPrompt, role === 'task' ? CLAUDE_TASK_SYSTEM_REMINDER : undefined]
+        .filter((text) => Boolean(text))
+        .join('\n\n');
     if (backend === 'claude') {
         const viaOpenrouter = claudeModel === 'openrouter';
         const orAuth = viaOpenrouter ? resolveOpenrouterAuth() : null;
@@ -547,15 +565,18 @@ taskId) {
                 claudeSettingsArg(anAuth),
                 '--strict-mcp-config',
                 ...(role === 'task' ? [mcpConfigArg(metering.deckDir, taskId)] : []),
-                ...(role === 'task' ? ['--append-system-prompt', CLAUDE_TASK_SYSTEM_REMINDER] : []),
+                ...(systemText ? ['--append-system-prompt', systemText] : []),
                 prompt,
             ],
-            env: withCustomHeaders(viaOpenrouter ? envForOpenrouterSpawn(orAuth) : envForClaudeSpawn(anAuth), meteringHeaders({
-                deckDir: metering.deckDir,
-                sessionId: metering.sessionId,
-                route: viaOpenrouter ? 'openrouter' : 'anthropic',
-                direct,
-            })),
+            env: {
+                ...withCustomHeaders(viaOpenrouter ? envForOpenrouterSpawn(orAuth) : envForClaudeSpawn(anAuth), meteringHeaders({
+                    deckDir: metering.deckDir,
+                    sessionId: metering.sessionId,
+                    route: viaOpenrouter ? 'openrouter' : 'anthropic',
+                    direct,
+                })),
+                ...(role === 'router' ? ROUTER_CLAUDE_ENV : {}),
+            },
         };
     }
     return {
@@ -569,7 +590,7 @@ taskId) {
             '--model',
             CURSOR_MODEL,
             ...(role === 'router' ? ['--mode', 'ask'] : ['--force']),
-            prompt,
+            systemPrompt ? `${systemPrompt}\n\n${prompt}` : prompt,
         ],
         env: envForAgentSpawn(backend),
     };
@@ -1852,6 +1873,7 @@ async function runAgentSmith(opts) {
             // "" (auto) becomes undefined so no provider.order is sent.
             providerTier: opts.openrouterTuning?.providerTier || undefined,
             prompt: opts.prompt,
+            system: opts.system,
             systemReminder: opts.systemReminder,
             attachments: opts.attachments,
             timeoutMs: opts.timeoutMs,
@@ -2169,6 +2191,7 @@ async function runAgentTurn(opts) {
             }),
             model: opts.openrouterModel,
             prompt: opts.prompt,
+            system: opts.systemPrompt,
             // Mirrors claude's --append-system-prompt for tasks (the native loop
             // appends it to its own system framing).
             systemReminder: opts.role === 'task' ? CLAUDE_TASK_SYSTEM_REMINDER : undefined,
@@ -2185,7 +2208,7 @@ async function runAgentTurn(opts) {
             onSpawn: opts.onSpawn,
         }));
     }
-    const invocation = buildAgentInvocation(opts.backend, opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, { sessionId, deckDir: opts.cwd }, opts.taskId);
+    const invocation = buildAgentInvocation(opts.backend, opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, { sessionId, deckDir: opts.cwd }, opts.taskId, opts.systemPrompt);
     const startedMs = Date.now();
     const run = runAgentCli({
         cwd: opts.cwd,
@@ -3273,7 +3296,7 @@ function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
     // ROUTER_DECK_CONTENTS_BUDGET's comment (the router prompt is already the
     // largest one this serve builds).
     const isSmith = ctx.backend() === 'smith';
-    return buildRouterPrompt({
+    return buildRouterPromptParts({
         deckLabel: ctx.deckLabel,
         quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, ctx.backend()),
         deckTree: buildDeckTree(ctx.deckDir, isSmith
@@ -3409,7 +3432,8 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
     void runAgentTurn({
         backend,
         role: 'router',
-        prompt,
+        prompt: prompt.user,
+        systemPrompt: prompt.system,
         claudeModel: ctx.claudeModel(),
         openrouterModel: ctx.openrouterModel(),
         openrouterTuning: ctx.openrouterTuning(),

package/dist/ide.d.ts

@@ -1,6 +1,8 @@
 import * as http from 'http';
 import { Duplex } from 'stream';
 import { COVER_FILE } from './localPaths.js';
+/** Cache only Vite's content-fingerprinted executable, style, and font output. */
+export declare function shellAssetCacheControl(asset: string): string;
 export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
 export declare const PTY_WS_PATH = "/__castle/pty";
 export declare const VENDOR_PREFIX = "/__castle/vendor/";

package/dist/ide.js

@@ -51,6 +51,13 @@ const SHELL_MIME = {
     '.ttf': 'font/ttf',
     '.map': 'application/json; charset=utf-8',
 };
+const IMMUTABLE_SHELL_ASSET = /^assets\/[^/\\]+-[A-Za-z0-9_-]{8}\.(?:css|js|woff2?|ttf)$/;
+/** Cache only Vite's content-fingerprinted executable, style, and font output. */
+export function shellAssetCacheControl(asset) {
+    return IMMUTABLE_SHELL_ASSET.test(asset)
+        ? 'public, max-age=31536000, immutable'
+        : 'no-store';
+}
 // Does the deck serve this root-level file itself? Vite serves both the deck
 // root and its `public/` dir at `/`, so either location counts.
 function deckHasFile(deckDir, name) {
@@ -97,7 +104,10 @@ function serveShellFile(res, asset) {
     }
     res.writeHead(200, {
         'content-type': SHELL_MIME[path.extname(filePath)] ?? 'application/octet-stream',
-        'cache-control': 'no-store',
+        // These built assets are platform-global bytes. The shell HTML and all
+        // unversioned files stay no-store because only the Vite hash makes a URL
+        // safe to retain across CLI updates.
+        'cache-control': shellAssetCacheControl(asset),
     });
     fs.createReadStream(filePath).pipe(res);
     return true;
@@ -366,6 +376,49 @@ function filterImportedFiles(deckDir, imported) {
     }
     return out;
 }
+// The deck's files as the Files panel sees them. Each deck curates its own: the
+// importing deck's visible/hidden paths name its own dirs (a kit's name scenes/,
+// drawings/ ...), so applying them to imports would hide every import by
+// omission -- an import is instead filtered by the config of the deck it came
+// from, which is the deck that knows which of its files are worth showing.
+function curatedDeckFiles(deckDir) {
+    const listed = listDeckFiles(deckDir);
+    const own = listed.filter((f) => !isImportPath(f));
+    return [
+        ...filterOwnFiles(own, readEditorConfig(deckDir)),
+        ...filterImportedFiles(deckDir, listed.filter(isImportPath)),
+    ].sort((a, b) => a.localeCompare(b));
+}
+// The source extensions a `PARAMS` object can be read out of -- the same ones
+// the shell parses as JS/TS. Not a kit's vocabulary: `export const PARAMS` is a
+// JavaScript declaration, not a file type somebody declared.
+const PARAMS_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+// Deliberately looser than the shell's parser, which also accepts a `const
+// PARAMS` that is never exported. A prefilter that were TIGHTER than the parser
+// would drop files the panel can actually edit; the shell re-parses each
+// candidate and discards the ones that only look like a match.
+const PARAMS_DECLARATION = /\bconst\s+PARAMS\b/;
+// Which of the deck's files declare params. Scanning here rather than in the
+// browser because a physics-2d deck carries a hundred-plus files under
+// `imports/`, and reading each one over HTTP to open a panel is the wrong cost.
+function filesDeclaringParams(deckDir) {
+    const out = [];
+    for (const rel of curatedDeckFiles(deckDir)) {
+        if (!PARAMS_EXTS.has(path.extname(rel).toLowerCase()))
+            continue;
+        const resolved = resolveDeckPath(deckDir, rel);
+        if (!resolved.ok)
+            continue;
+        try {
+            if (PARAMS_DECLARATION.test(fs.readFileSync(resolved.abs, 'utf8')))
+                out.push(rel);
+        }
+        catch {
+            /* raced a delete, or not readable -- it simply has no params to offer */
+        }
+    }
+    return out;
+}
 // Read a raw (binary) request body, refusing anything over `limit`. Uploads are
 // arbitrary device files, so the cap is enforced as bytes arrive rather than
 // after buffering the whole thing.
@@ -859,21 +912,12 @@ function handleFilesApi(deckDir, req, res, reqPath, restart, invalidate) {
         // toggle) -- still minus the always-ignored dirs (node_modules/.castle/...),
         // just without the deck's visible/hidden path curation.
         const url = new URL(req.url ?? '/', 'http://localhost');
-        const listed = listDeckFiles(deckDir);
-        let files = listed;
-        if (url.searchParams.get('all') !== '1') {
-            // Each deck curates its own files. The importing deck's visible/hidden
-            // paths name its own dirs (a kit's name scenes/, drawings/ ...), so
-            // applying them to imports would hide every import by omission -- an
-            // import is instead filtered by the config of the deck it came from, which
-            // is the deck that knows which of its files are worth showing.
-            const own = listed.filter((f) => !isImportPath(f));
-            files = [
-                ...filterOwnFiles(own, readEditorConfig(deckDir)),
-                ...filterImportedFiles(deckDir, listed.filter(isImportPath)),
-            ].sort((a, b) => a.localeCompare(b));
-        }
-        sendJson(res, 200, { files });
+        const all = url.searchParams.get('all') === '1';
+        sendJson(res, 200, { files: all ? listDeckFiles(deckDir) : curatedDeckFiles(deckDir) });
+        return true;
+    }
+    if (action === 'params') {
+        sendJson(res, 200, { files: filesDeclaringParams(deckDir) });
         return true;
     }
     if (action === 'read') {

package/dist/native/loop.js

@@ -319,6 +319,8 @@ const ROLE_FRAMING = {
 };
 function buildSystemMessage(opts) {
     const parts = [ROLE_FRAMING[opts.role]];
+    if (opts.system)
+        parts.push(opts.system);
     if (opts.systemReminder)
         parts.push(opts.systemReminder);
     return parts.join("\n\n");
@@ -700,10 +702,17 @@ async function runLoop(opts, toolSchemas, log) {
                 };
             }
             usedAnyTool = true;
+            // The reasoning goes back with the turn it belongs to. Anthropic treats an
+            // assistant turn returned without its thinking as a changed prefix and
+            // recomputes every message after it, so without this no call in the loop
+            // reads the cache (measured: 0 cached tokens per call, 30k written each).
             messages.push({
                 role: "assistant",
                 content: streamResult.message.content || null,
                 tool_calls: toolCalls,
+                ...(streamResult.message.reasoning_details
+                    ? { reasoning_details: streamResult.message.reasoning_details }
+                    : {}),
             });
             const toolResults = await runToolCalls(toolCalls, opts.role, toolCtx, playtestFrames, toolLabels, imageLabels, log, opts.onActivity);
             messages.push(...toolResults);

package/dist/native/openrouter.d.ts

@@ -25,11 +25,13 @@ export interface ORMessage {
     content?: string | null | ORContentPart[];
     tool_calls?: ORToolCall[];
     tool_call_id?: string;
+    reasoning_details?: unknown[];
 }
 export interface ORAssistantMessage {
     role: "assistant";
     content: string;
     tool_calls?: ORToolCall[];
+    reasoning_details?: unknown[];
 }
 export type ORReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type ORRoutingMode = "balanced" | "nitro" | "exacto" | "floor";

package/dist/native/openrouter.js

@@ -344,6 +344,7 @@ export async function streamChatCompletion(opts) {
         return { message: null, crashed: false, error: "could not run openrouter: empty response body" };
     }
     let content = "";
+    const reasoningDetails = [];
     // Observed live (2026-07): some providers' MID-stream usage passthrough is
     // junk (constant cache_read=128 / cache_created=0 on every event) while the
     // FINAL usage chunk -- the one OpenRouter emits at/after finish_reason --
@@ -398,6 +399,9 @@ export async function streamChatCompletion(opts) {
             if (typeof delta.reasoning === "string" && delta.reasoning) {
                 opts.onThinking?.(delta.reasoning);
             }
+            if (Array.isArray(delta.reasoning_details)) {
+                reasoningDetails.push(...delta.reasoning_details);
+            }
             const toolCallDeltas = delta.tool_calls;
             if (Array.isArray(toolCallDeltas)) {
                 for (const tc of toolCallDeltas) {
@@ -461,7 +465,12 @@ export async function streamChatCompletion(opts) {
         };
     }
     return {
-        message: { role: "assistant", content, tool_calls: finalizeToolCalls(pendingToolCalls) },
+        message: {
+            role: "assistant",
+            content,
+            tool_calls: finalizeToolCalls(pendingToolCalls),
+            ...(reasoningDetails.length ? { reasoning_details: reasoningDetails } : {}),
+        },
         usage: finalUsage ?? usage,
         reasoningTokens: finalReasoningTokens ?? reasoningTokens,
         crashed: false,

package/dist/native/types.d.ts

@@ -23,6 +23,7 @@ export interface NativeRunOpts {
     routing?: ORRoutingMode;
     providerTier?: string;
     prompt: string;
+    system?: string;
     systemReminder?: string;
     attachments?: string[];
     playtest?: NativePlaytestOpts;

package/dist/platformDoc.js

@@ -53,7 +53,7 @@ export function everyDeckBullets(deckDir) {
         "- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.",
         "- The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe under `## Editors` in the deck's guide (its kit's `CLAUDE.md` under `imports/`). Editors under `imports/` are read-only; add or fork, don't edit.",
         '- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. One-off or generated data stays code.',
-        "- **Put the values someone would tune while playtesting in a `PARAMS` object**: `export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08 };` near the top of the file that uses them. Every `.js` / `.jsx` / `.ts` / `.tsx` file has a Params view beside its Code view that renders those values as fields -- a number scrubs, a boolean toggles, a `'#rrggbb'` string opens a color picker -- and writes the edit back into the file. That is how a creator tunes a game on a phone without putting a cursor inside an expression. Nested one level deep (`player: { speed: 5 }`) renders as a group; a value that is an expression (`speed: BASE * 2`) still shows, read-only.",
+        "- **Put the values someone would tune while playtesting in a `PARAMS` object**: `export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08 };` near the top of the file that uses them. The Parameters panel lists every file in the deck that has one and renders their values as fields -- a number scrubs, a boolean toggles, a `'#rrggbb'` string opens a color picker -- and writes the edit back into the file. It edits every file's params in one place, so nobody has to remember which file a setting lives in, and a file that has params says so above its code with a way in. That is how a creator tunes a game on a phone without putting a cursor inside an expression. Nested one level deep (`player: { speed: 5 }`) renders as a group; a value that is an expression (`speed: BASE * 2`) still shows, read-only.",
         '- **This is for the handful of numbers someone would actually reach for between playtests, not every constant in the file.** A `PARAMS` with sixty keys is a wall nobody can scan, which is how a creator stops opening the pane at all. A magic number that only ever has one right value is not a param.',
         "- **Read them through the object where they are used** -- `PARAMS.jumpHeight`, not `const { jumpHeight } = PARAMS` at module load. A destructured copy is taken once when the module loads and can never track a later change, so keeping the read at the use site is what leaves a tuned value able to reach the running deck.",
         MODE_BULLET,

package/dist/serve.js

@@ -266,6 +266,7 @@ const EDIT_CONTENT_READ_ENDPOINTS = new Set([
     '/__castle/files/read',
     '/__castle/files/info',
     '/__castle/files/list',
+    '/__castle/files/params',
     '/__castle/files/forks',
 ]);
 export function isAllowedContentFilesRequest(role, method, reqPath) {
@@ -596,6 +597,15 @@ function lockExistingImports(projectDir) {
         }
     }
 }
+function importPinsFingerprint(projectDir) {
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(projectDir, 'castle.json'), 'utf8'));
+        return JSON.stringify(config.imports ?? {});
+    }
+    catch {
+        return null;
+    }
+}
 export async function serve(dir, options = {}) {
     const projectDir = path.resolve(dir);
     if (!fs.existsSync(projectDir)) {
@@ -642,11 +652,18 @@ export async function serve(dir, options = {}) {
     //
     // Also skipped when CASTLE_NO_AUTO_UPDATE is set (local kit development:
     // keep hand-synced imports/ instead of pulling published kits).
+    let importsChangedAtStartup = false;
     if (!existingServe(projectDir)) {
+        const importsBeforeUpdate = importPinsFingerprint(projectDir);
         // A failure to check must never keep the deck from opening.
-        await autoUpdateImports(projectDir).catch((e) => {
+        const updated = await autoUpdateImports(projectDir).catch((e) => {
             console.warn(`auto-update: skipped -- ${e instanceof Error ? e.message : String(e)}`);
+            return [];
         });
+        // Comparing pins as well as the returned list preserves the invalidation
+        // if a later step throws after one or more imported trees were replaced.
+        importsChangedAtStartup =
+            updated.length > 0 || importsBeforeUpdate !== importPinsFingerprint(projectDir);
     }
     // Start pulling the headless browser now, in the background.
     //
@@ -815,6 +832,13 @@ export async function serve(dir, options = {}) {
     playtestHolder.run = (req) => agentServer.runPlaytestFor(req);
     const vite = await createViteServer({
         root: projectDir,
+        // Vite's cached optimizer metadata keys package/lock/config inputs, not the
+        // source of an imported deck. A serve-start auto-update can therefore add
+        // bare imports while leaving Vite convinced its old pre-bundle is current.
+        // Force only that startup's cold optimization: unchanged serves keep the
+        // warm cache, while the first page after replaced import source never has
+        // to recover from an outdated optimized-dependency response (HMR is off).
+        ...(importsChangedAtStartup ? { optimizeDeps: { force: true } } : {}),
         plugins: [
             castlePlugin(security, ideServer, agentServer, options.host),
             forksOverlayPlugin(),