castle-web-cli 0.4.165 → 0.4.167

package/dist/agent-prompts.js

@@ -964,7 +964,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, NO file/behavior names or implementation notes -- those are for you, not the player. 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 ("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}
 - 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.d.ts

@@ -3,8 +3,6 @@ import { Duplex } from 'stream';
 import type { ORReasoningEffort, ORRoutingMode } from './native/openrouter.js';
 import { type PlaytestToolResult } from './native/playtest.js';
 export declare const AGENT_WS_PATH = "/__castle/agent";
-export declare const AGENT_ATTACHMENT_PREFIX = "/__castle/agent/attachments/";
-export declare const AGENT_PLAYTEST_PREFIX = "/__castle/agent/playtest/";
 export declare const AGENT_MODEL_CAPS_PREFIX = "/__castle/agent/model-caps";
 export type AgentBackend = 'cursor' | 'claude' | 'smith';
 export type ClaudeModel = 'sonnet' | 'opus' | 'fable' | 'openrouter';
@@ -90,6 +88,7 @@ export declare function createAgentServer(opts: {
     port?: number;
     playtestServeUrl?: string;
     browserContentUrl?: () => string | null;
+    signPath?: (reqPath: string) => string;
     restart?: () => void;
     authorizeUpgrade?: (req: http.IncomingMessage, endpoint: 'agent') => boolean;
 }): AgentServer;

package/dist/agent.js

@@ -24,7 +24,7 @@ import * as path from 'path';
 import { nanoid } from 'nanoid';
 import { WebSocketServer } from 'ws';
 import { rawDataToString } from './rawData.js';
-import { PLAN_FILE } from './localPaths.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 { readCastleJson } from './castleJson.js';
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from './openrouter-catalog.js';
@@ -39,10 +39,6 @@ import { createPlaywrightPlaytestExecutor } from './native/playtest-executor.js'
 import { createRemotePlaytestExecutor } from './native/playtest-remote.js';
 import { runPlaytest, } from './native/playtest.js';
 export const AGENT_WS_PATH = '/__castle/agent';
-export const AGENT_ATTACHMENT_PREFIX = '/__castle/agent/attachments/';
-// Playtest frame PNGs (tasks/<id>/playtest/<file>.png), served for the
-// finished-task card's thumbnails -- see makePlaytestFrameHandler.
-export const AGENT_PLAYTEST_PREFIX = '/__castle/agent/playtest/';
 // Same-origin proxy for OpenRouter model capabilities (avoids browser CORS
 // against openrouter.ai). GET ?model=<slug> -> ModelCaps JSON. Powers the
 // settings popover's dynamic reasoning-effort / provider-tier pickers.
@@ -3077,7 +3073,7 @@ function asPromptTask(task) {
         blockedBy: task.status === 'blocked' ? task.blockedBy : undefined,
     };
 }
-function asClientTask(task) {
+function asClientTask(task, signPath) {
     return {
         id: task.id,
         title: task.title,
@@ -3094,7 +3090,20 @@ function asClientTask(task) {
         rejected: task.rejected,
         errorCopy: task.errorCopy,
         errorDetail: task.errorDetail,
-        playtestFrames: (task.playtestFrames ?? []).map((rel) => `${AGENT_PLAYTEST_PREFIX}${task.id}/${path.basename(rel)}`),
+        playtestFrames: (task.playtestFrames ?? []).map((rel) => clientUrl(`${AGENT_PLAYTEST_PREFIX}${task.id}/${path.basename(rel)}`, signPath)),
+    };
+}
+function clientUrl(reqPath, signPath) {
+    return signPath ? `${reqPath}?t=${signPath(reqPath)}` : reqPath;
+}
+// A sent message renders its pasted images as `<img src>`, which cannot carry
+// the serve token any more than a playtest frame can -- see ServeSecurity.signPath.
+function asClientMessage(message, signPath) {
+    if (!message.attachments?.length)
+        return message;
+    return {
+        ...message,
+        attachments: message.attachments.map((name) => clientUrl(`${AGENT_ATTACHMENT_PREFIX}${name}`, signPath)),
     };
 }
 function createTaskFeeds(broadcast) {
@@ -3133,7 +3142,7 @@ function createMessageThinking(broadcast) {
     }
     return { append, snapshot };
 }
-function createMessageLog(messagesPath, broadcast, welcomeMessage) {
+function createMessageLog(messagesPath, broadcast, welcomeMessage, forClient) {
     const loaded = readJsonFile(messagesPath) ?? [];
     const messages = loaded
         .filter((m) => m.text.trim() !== '' || m.role === 'user')
@@ -3154,7 +3163,7 @@ function createMessageLog(messagesPath, broadcast, welcomeMessage) {
     function add(message) {
         messages.push(message);
         persist();
-        broadcast({ type: 'message-add', message });
+        broadcast({ type: 'message-add', message: forClient(message) });
     }
     function addLog(text) {
         add({ id: nanoid(8), role: 'log', text, at: nowIso(), status: 'done' });
@@ -4215,7 +4224,7 @@ export function createAgentServer(opts) {
                 socket.send(payload);
         }
     }
-    const log = createMessageLog(messagesPath, broadcast, welcomeMessage);
+    const log = createMessageLog(messagesPath, broadcast, welcomeMessage, (message) => asClientMessage(message, opts.signPath));
     const messages = log.messages;
     const addLog = (text) => log.addLog(text);
     // Which CLI backs the router and the task agents -- independently
@@ -4265,7 +4274,7 @@ export function createAgentServer(opts) {
         playtest,
         restart: opts.restart,
         // Task lifecycle stays on the board only -- log lines for it were spam.
-        onUpdate: (task) => broadcast({ type: 'task-update', task: asClientTask(task) }),
+        onUpdate: (task) => broadcast({ type: 'task-update', task: asClientTask(task, opts.signPath) }),
         onStarted: () => undefined,
         onRetry: (task, attempt) => addLog(`agent died, retrying (${attempt}/${MAX_TASK_ATTEMPTS}): ${task.title}`),
         onFinished: (task) => taskFeeds.map.delete(task.id),
@@ -4345,8 +4354,8 @@ export function createAgentServer(opts) {
         clients.add(socket);
         const hello = {
             type: 'hello',
-            messages,
-            tasks: taskStore.sorted().map(asClientTask),
+            messages: messages.map((message) => asClientMessage(message, opts.signPath)),
+            tasks: taskStore.sorted().map((task) => asClientTask(task, opts.signPath)),
             settings,
             feeds: Object.fromEntries(taskFeeds.map),
             thinking: messageThinking.snapshot(),

package/dist/api.js

@@ -23,7 +23,22 @@ export async function graphql(query, variables, options = {}) {
         body: JSON.stringify(variables ? { query, variables } : { query }),
         signal,
     });
-    return res.json();
+    const body = await res.text();
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        // A body that isn't JSON never reached the GraphQL layer at all -- a sandbox
+        // proxy refusing the operation, a gateway error page. Parsing it blind reports
+        // that as `Unexpected token 'G'`, which hid a broken publish for days.
+        throw new Error(`Castle API ${res.status}: ${firstLine(body)}`);
+    }
+}
+function firstLine(body) {
+    const line = body.split('\n', 1)[0].trim();
+    if (!line)
+        return '(empty response body)';
+    return line.length > 200 ? `${line.slice(0, 200)}...` : line;
 }
 export async function runBrowserJob(contentGrant, operation, signal) {
     const data = await graphql(`mutation($contentGrant: String!, $operation: Json!) {

package/dist/imports.js

@@ -664,11 +664,22 @@ function importOptsIntoAutoUpdate(deckDir, alias) {
 // publish (the framework kits -- the same account `init` qualifies their aliases
 // with).
 //
-// Deliberately not a setting: nothing a deck or a person can flip, since that
-// would be the leash undoing itself. The env var is a test seam -- the automated
-// check can't publish a deck to the castle account (nothing should), so it
-// substitutes which account counts and exercises both branches for real.
+// Deliberately not a deck setting: nothing in castle.json a person can flip,
+// since that would be the leash undoing itself. Process env is the escape
+// hatch for local kit work and tests:
+//   - CASTLE_NO_AUTO_UPDATE=1 -- skip serve-start auto-update entirely (keep
+//     whatever is already under imports/, including hand-synced kits from this
+//     checkout).
+//   - CASTLE_AUTO_UPDATE_TRUSTED_ACCOUNT -- which username counts as trusted
+//     (default `castle`). Tests set it to exercise both branches; setting it to
+//     a non-matching name also disables updates as a side effect.
 const AUTO_UPDATE_ACCOUNT = process.env.CASTLE_AUTO_UPDATE_TRUSTED_ACCOUNT ?? 'castle';
+function autoUpdateDisabled() {
+    const raw = process.env.CASTLE_NO_AUTO_UPDATE;
+    if (raw == null || raw === '')
+        return false;
+    return raw !== '0' && raw.toLowerCase() !== 'false' && raw.toLowerCase() !== 'no';
+}
 // Who published a deck. Readable without auth for the same decks webDeckSource
 // is, so this answers in a sandbox with no login. A lookup that fails answers
 // "not trusted": the failure direction has to be the one that leaves an import
@@ -689,6 +700,10 @@ async function importIsOnTrustedAccount(deckId) {
 // checked (offline, no source on the server, a bad archive) stays exactly as it
 // is pinned, and the serve starts anyway.
 export async function autoUpdateImports(deckDir) {
+    if (autoUpdateDisabled()) {
+        console.log('auto-update: skipped (CASTLE_NO_AUTO_UPDATE)');
+        return [];
+    }
     const pins = tryReadCastleJson(deckDir)?.imports ?? {};
     const updated = [];
     for (const [alias, pin] of Object.entries(pins)) {

package/dist/localPaths.d.ts

@@ -5,4 +5,6 @@ export declare function getSdkPackagePath(): string;
 export declare function getKitsDir(): string;
 export declare const COVER_FILE = "preview.png";
 export declare const PLAN_FILE = "plan.md";
+export declare const AGENT_PLAYTEST_PREFIX = "/__castle/agent/playtest/";
+export declare const AGENT_ATTACHMENT_PREFIX = "/__castle/agent/attachments/";
 export declare function toPosixPath(filepath: string): string;

package/dist/localPaths.js

@@ -41,6 +41,12 @@ export const COVER_FILE = 'preview.png';
 // instead. Named here because the serve's file listing has to know it too, to
 // keep it out of a deck's path curation.
 export const PLAN_FILE = 'plan.md';
+// Request-path prefixes the agent server serves a task's playtest frame PNGs
+// and a chat message's pasted images under. Named here because ServeSecurity
+// has to know them too -- they are the shell prefixes a signed path may open --
+// and agent.ts already imports that.
+export const AGENT_PLAYTEST_PREFIX = '/__castle/agent/playtest/';
+export const AGENT_ATTACHMENT_PREFIX = '/__castle/agent/attachments/';
 export function toPosixPath(filepath) {
     return filepath.split(path.sep).join('/');
 }

package/dist/serve.js

@@ -404,7 +404,10 @@ window.__castleShellOrigin=(function(){
                 const publicShellPath = reqPath === '/' ||
                     reqPath.startsWith('/__castle/ide/') ||
                     FAVICON_FILES.some((name) => reqPath === `/${name}`);
-                if (reqPath.startsWith('/__castle/') && !publicShellPath && !security.authorizeHttp(req)) {
+                if (reqPath.startsWith('/__castle/') &&
+                    !publicShellPath &&
+                    !security.authorizeHttp(req) &&
+                    !security.authorizeSignedPath(req, reqPath)) {
                     security.rejectHttpAuth(res);
                     return;
                 }
@@ -778,6 +781,7 @@ export async function serve(dir, options = {}) {
         deckLabel: path.basename(projectDir),
         port,
         playtestServeUrl: security.localContentOrigin('play'),
+        signPath: (reqPath) => security.signPath(reqPath),
         browserContentUrl: process.env.CASTLE_SANDBOX_ID
             ? () => security.browserContentOrigin('play')
             : undefined,

package/dist/serveSecurity.d.ts

@@ -18,6 +18,7 @@ export declare class ServeSecurity {
     private readonly contentProxyToken;
     private readonly signingKey;
     private readonly serveNonce;
+    private readonly pathKey;
     private readonly tickets;
     private localContentPorts;
     private localContentHost;
@@ -26,6 +27,17 @@ export declare class ServeSecurity {
     setLocalContentHost(host: string): void;
     authorizeHttp(req: http.IncomingMessage): boolean;
     rejectHttpAuth(res: http.ServerResponse): void;
+    /**
+     * Sign one shell path so a browser can load it WITHOUT the serve token. The
+     * bootstrap supplies that token by patching `window.fetch`, and an `<img
+     * src>` or a `target="_blank"` link never goes through fetch -- so a URL the
+     * page hands to the browser instead of fetching itself has to carry its own
+     * capability. Bound to the exact path, and only a SIGNABLE_PATH_PREFIXES
+     * path: a signature minted for one frame opens nothing else under
+     * `/__castle/`, and a path outside that set cannot be signed at all.
+     */
+    signPath(reqPath: string): string;
+    authorizeSignedPath(req: http.IncomingMessage, reqPath: string): boolean;
     issueTicket(endpoint: SocketEndpoint): string;
     /** One-use admission for an SDK that predates the shell's MessagePort bridge. */
     issueLegacyContentTicket(role: ContentRole): string;

package/dist/serveSecurity.js

@@ -1,4 +1,5 @@
 import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
+import { AGENT_ATTACHMENT_PREFIX, AGENT_PLAYTEST_PREFIX } from './localPaths.js';
 export const SERVE_AUTH_FAILURE_HEADER = 'x-castle-serve-auth';
 export const SERVE_AUTH_FAILURE_VALUE = 'invalid';
 const CROCKFORD = '0123456789abcdefghjkmnpqrstvwxyz';
@@ -7,6 +8,13 @@ const MAX_GRANT_SECONDS = 12 * 60 * 60;
 const GRANT_CLOCK_SKEW_SECONDS = 60;
 const BROWSER_GRANT_SECONDS = 3 * 60;
 export const MOBILE_HOST_PROTOCOL = '2';
+// A signature covers the request path and nothing else, so every path it can
+// open must be a static file the path alone names. A query-driven endpoint
+// here (`/__castle/files/read?path=`) would be opened wholesale by one signature.
+const SIGNABLE_PATH_PREFIXES = [AGENT_PLAYTEST_PREFIX, AGENT_ATTACHMENT_PREFIX];
+function isSignablePath(reqPath) {
+    return SIGNABLE_PATH_PREFIXES.some((prefix) => reqPath.startsWith(prefix));
+}
 function base32Lower(bytes) {
     let bits = 0;
     let value = 0;
@@ -57,6 +65,7 @@ export class ServeSecurity {
     contentProxyToken = randomBytes(32).toString('base64url');
     signingKey = process.env.CASTLE_AGENT_TOKEN || randomBytes(32).toString('base64url');
     serveNonce = base32Lower(randomBytes(8));
+    pathKey = randomBytes(32).toString('base64url');
     tickets = new Map();
     localContentPorts;
     localContentHost = '127.0.0.1';
@@ -87,6 +96,39 @@ export class ServeSecurity {
         })
             .end();
     }
+    /**
+     * Sign one shell path so a browser can load it WITHOUT the serve token. The
+     * bootstrap supplies that token by patching `window.fetch`, and an `<img
+     * src>` or a `target="_blank"` link never goes through fetch -- so a URL the
+     * page hands to the browser instead of fetching itself has to carry its own
+     * capability. Bound to the exact path, and only a SIGNABLE_PATH_PREFIXES
+     * path: a signature minted for one frame opens nothing else under
+     * `/__castle/`, and a path outside that set cannot be signed at all.
+     */
+    signPath(reqPath) {
+        if (!isSignablePath(reqPath)) {
+            throw new Error(`refusing to sign a shell path outside the signable set: ${reqPath}`);
+        }
+        return base32Lower(createHmac('sha256', this.pathKey)
+            .update(`castle-path-v1\n${reqPath}`)
+            .digest()
+            .subarray(0, 12));
+    }
+    authorizeSignedPath(req, reqPath) {
+        const method = req.method?.toUpperCase();
+        if (method !== 'GET' && method !== 'HEAD')
+            return false;
+        if (!isSignablePath(reqPath))
+            return false;
+        let signature = '';
+        try {
+            signature = new URL(req.url || '/', 'http://localhost').searchParams.get('t') || '';
+        }
+        catch {
+            return false;
+        }
+        return signature !== '' && safeEqual(this.signPath(reqPath), signature);
+    }
     issueTicket(endpoint) {
         this.pruneTickets();
         const ticket = randomBytes(16).toString('base64url');