castle-web-cli 0.4.166 → 0.4.168

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/castle-host/host.d.ts

@@ -62,6 +62,8 @@ export interface MultiplayerGetSessionResult {
   url: string | null;
   nonce: string | null;
   sessionId: string | null;
+  /** Set when `status` is 'solo'; null otherwise. */
+  soloReason: 'private_deck' | 'no_server_bundle' | 'unavailable' | null;
 }
 
 export interface LeaderboardStreakCredit {

package/dist/castle-host/host.js

@@ -171,14 +171,27 @@ function multiplayerSessionRequest(params) {
 function multiplayerSessionResult(value) {
     const sessionId = asOptionalString(value?.sessionId);
     if (value?.isSingleUserSession === true) {
-        return { status: "solo", url: null, nonce: null, sessionId };
+        return {
+            status: "solo",
+            url: null,
+            nonce: null,
+            sessionId,
+            soloReason: asSoloReason(value?.soloReason),
+        };
     }
     const url = asOptionalString(value?.url);
     const nonce = asOptionalString(value?.nonce);
     if (!url || !nonce) {
-        return { status: "unavailable", url: null, nonce: null, sessionId };
+        return { status: "unavailable", url: null, nonce: null, sessionId, soloReason: null };
     }
-    return { status: "ok", url, nonce, sessionId };
+    return { status: "ok", url, nonce, sessionId, soloReason: null };
+}
+// A reason this SDK does not know reads as the catch-all: the deck still
+// learns it is solo, just not why. This does not cover a ghost older than the
+// field: that rejects the whole query as invalid, so ghost deploys before any
+// host that carries this selection.
+function asSoloReason(value) {
+    return value === "private_deck" || value === "no_server_bundle" ? value : "unavailable";
 }
 // Dispatch a platform/capability command to the host's platformHandler. No
 // handler → the command's normalized "unavailable" outcome (a SUCCESS, not an
@@ -1092,6 +1105,7 @@ const CAULDRON_MULTIPLAYER_SESSION_QUERY = `
       isSingleUserSession
       url
       nonce
+      soloReason
     }
   }
 `;

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/platformDoc.js

@@ -219,7 +219,7 @@ const COMMON_SECTIONS = `## Imports are read-only
   \`\`\`
 
   \`named\` puts everyone passing the same \`key\` in one session, which is how you build room codes and invite links. \`public\` drops a player into a shared session for the deck; \`party\` uses the Castle party they are already in.
-- **Always handle \`conn.isSolo\`.** When a player cannot join — signed out, blocked, private deck, or no capacity free — the SDK returns a working single-player connection instead of throwing. Keep the deck playable on its own rather than gating the whole game behind other people showing up.
+- **Always handle \`conn.isSolo\`.** When a player cannot join — signed out, blocked, private deck, or no capacity free — the SDK returns a working single-player connection instead of throwing. Keep the deck playable on its own rather than gating the whole game behind other people showing up. \`conn.soloReason\` says why: \`private_deck\` and \`no_server_bundle\` are things the creator can fix (make the deck unlisted or public; publish with a server entry), so it is worth telling them in the HUD; \`unavailable\` is everything else.
 - **What the server may and may not do.** Roughly 128MB of memory, no filesystem that survives, and **no network access at all**: no \`fetch\`, no database, no third-party API. Keep state in memory and send it to clients. A session ends once its last player leaves and its memory goes with it.
 - **\`session.storage\` is what outlives a session**, and it is the same store the deck's clients see through \`Store\`:
 

package/dist/save-deck.js

@@ -376,7 +376,19 @@ export async function saveDeck(dir, opts = {}) {
         else {
             console.log(`Saved "${title}" to Castle.`);
         }
-        await traceSaveStage('server_publish', () => publishServerBundle(projectDir, result.deckId));
+        // The deck went live above, so anything failing here leaves it skewed: the
+        // published client runs against whatever server was last deployed. Say that
+        // in the thrown message -- it is the only line the cloud editor gets back
+        // (it forwards stderr), and "not valid JSON" reads as a glitch, not as a
+        // deck that is now half-published.
+        try {
+            await traceSaveStage('server_publish', () => publishServerBundle(projectDir, result.deckId));
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            throw new Error(`Server bundle NOT published (${reason}). ` +
+                `"${title}" is live on the new client but its server is unchanged.`);
+        }
         console.log('Uploading source archive...');
         await uploadSource(projectDir, result.deckId);
         console.log('Source archive saved.');

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;
                 }
@@ -469,6 +472,7 @@ async function handleCastleCommand(ws, projectDir, broadcast, multiplayer, multi
                     url: null,
                     nonce: null,
                     sessionId: null,
+                    soloReason: null,
                 });
             }
             return Promise.resolve({
@@ -476,6 +480,7 @@ async function handleCastleCommand(ws, projectDir, broadcast, multiplayer, multi
                 url: multiplayerUrl,
                 nonce: multiplayer.mintNonce(devMultiplayerIdentity(ctx)),
                 sessionId: multiplayer.sessionId,
+                soloReason: null,
             });
         },
     });
@@ -778,6 +783,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');