castle-web-cli 0.4.163 → 0.4.165

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/dist/agent-prompts.d.ts +3 -0
  2. package/dist/agent-prompts.js +14 -6
  3. package/dist/agent.js +14 -1
  4. package/dist/castle-host/host.js +276 -0
  5. package/dist/devSessionChild.js +66 -1
  6. package/dist/devSessionServer.js +21 -2
  7. package/dist/devSessionStorage.d.ts +9 -0
  8. package/dist/devSessionStorage.js +139 -0
  9. package/dist/forks.js +1 -1
  10. package/dist/headlessCover.js +12 -1
  11. package/dist/ide.d.ts +0 -2
  12. package/dist/ide.js +1 -7
  13. package/dist/imports.js +5 -0
  14. package/dist/init.js +1 -1
  15. package/dist/platformDoc.js +18 -3
  16. package/dist/rawData.d.ts +2 -0
  17. package/dist/rawData.js +10 -0
  18. package/dist/save-deck.d.ts +2 -0
  19. package/dist/save-deck.js +53 -20
  20. package/dist/serve.js +98 -0
  21. package/dist/shell/assets/index-CG9TrvCm.js +444 -0
  22. package/dist/shell/assets/index-CIRBt1qf.css +1 -0
  23. package/dist/shell/index.html +2 -2
  24. package/kits/base/CLAUDE.md +1 -1
  25. package/kits/base/castle.json +1 -1
  26. package/kits/base/node_modules/.package-lock.json +28 -0
  27. package/kits/base/node_modules/castle-web-fonts/README.md +114 -0
  28. package/kits/base/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
  29. package/kits/base/node_modules/castle-web-fonts/dist/catalog.js +142 -0
  30. package/kits/base/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
  31. package/kits/base/node_modules/castle-web-fonts/dist/face.js +52 -0
  32. package/kits/base/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
  33. package/kits/base/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
  34. package/kits/base/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
  35. package/kits/base/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
  36. package/kits/base/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
  37. package/kits/base/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
  38. package/kits/base/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
  39. package/kits/base/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
  40. package/kits/base/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
  41. package/kits/base/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
  42. package/kits/base/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
  43. package/kits/base/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
  44. package/kits/base/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
  45. package/kits/base/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
  46. package/kits/base/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
  47. package/kits/base/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
  48. package/kits/base/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
  49. package/kits/base/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
  50. package/kits/base/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
  51. package/kits/base/node_modules/castle-web-fonts/dist/index.js +15 -0
  52. package/kits/base/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
  53. package/kits/base/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
  54. package/kits/base/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
  55. package/kits/base/node_modules/castle-web-fonts/package.json +47 -0
  56. package/kits/base/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  57. package/kits/base/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  58. package/kits/base/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  59. package/kits/base/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  60. package/kits/base/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  61. package/kits/base/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  62. package/kits/base/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
  63. package/kits/base/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  64. package/kits/base/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  65. package/kits/base/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  66. package/kits/base/package-lock.json +1 -1
  67. package/kits/base/sdk/README.md +184 -38
  68. package/kits/base/sdk/castle.d.ts +2 -0
  69. package/kits/base/sdk/castle.js +1 -0
  70. package/kits/base/sdk/chunk.d.ts +1 -0
  71. package/kits/base/sdk/chunk.js +15 -0
  72. package/kits/base/sdk/commands.d.ts +86 -0
  73. package/kits/base/sdk/runtime.js +21 -12
  74. package/kits/base/sdk/server/platformHandle.d.ts +10 -0
  75. package/kits/base/sdk/server/storage.d.ts +46 -0
  76. package/kits/base/sdk/server/storage.js +218 -0
  77. package/kits/base/sdk/server/wrapper.d.ts +14 -1
  78. package/kits/base/sdk/server/wrapper.js +4 -1
  79. package/kits/base/sdk/storage.d.ts +15 -0
  80. package/kits/base/sdk/storage.js +29 -86
  81. package/kits/base/sdk/storageJson.d.ts +5 -0
  82. package/kits/base/sdk/storageJson.js +69 -0
  83. package/kits/base/sdk/store.d.ts +67 -0
  84. package/kits/base/sdk/store.js +313 -0
  85. package/kits/base/sdk/unloadFlush.d.ts +3 -0
  86. package/kits/base/sdk/unloadFlush.js +30 -0
  87. package/kits/blank/node_modules/.package-lock.json +13 -0
  88. package/kits/blank/node_modules/castle-web-fonts/README.md +114 -0
  89. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
  90. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.js +142 -0
  91. package/kits/blank/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
  92. package/kits/blank/node_modules/castle-web-fonts/dist/face.js +52 -0
  93. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
  94. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
  95. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
  96. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
  97. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
  98. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
  99. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
  100. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
  101. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
  102. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
  103. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
  104. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
  105. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
  106. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
  107. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
  108. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
  109. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
  110. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
  111. package/kits/blank/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
  112. package/kits/blank/node_modules/castle-web-fonts/dist/index.js +15 -0
  113. package/kits/blank/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
  114. package/kits/blank/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
  115. package/kits/blank/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
  116. package/kits/blank/node_modules/castle-web-fonts/package.json +47 -0
  117. package/kits/blank/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  118. package/kits/blank/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  119. package/kits/blank/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  120. package/kits/blank/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  121. package/kits/blank/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  122. package/kits/blank/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  123. package/kits/blank/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
  124. package/kits/blank/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  125. package/kits/blank/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  126. package/kits/blank/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  127. package/kits/physics-2d/castle.json +1 -1
  128. package/kits/physics-2d/editors/SceneEditor.jsx +2 -1
  129. package/kits/physics-2d/engine/blueprint.js +29 -28
  130. package/kits/physics-2d/engine/ui.jsx +24 -0
  131. package/kits/physics-2d/engine/ui.module.css +5 -0
  132. package/kits/physics-2d/package-lock.json +1 -6
  133. package/package.json +3 -2
  134. package/dist/shell/assets/index-BJO7LVCM.js +0 -422
  135. package/dist/shell/assets/index-DfZmu3XC.css +0 -1
  136. package/kits/blank/.castle/agent/children.json +0 -1
  137. package/kits/blank/.castle/agent/messages.json +0 -9
  138. package/kits/blank/.castle/agent/pending-sends.json +0 -1
  139. package/kits/blank/.castle/agent/tasks/index.md +0 -2
  140. package/kits/blank/.castle/docs/platform.md +0 -36
  141. package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
  142. package/kits/blank/node_modules/.vite/deps/package.json +0 -3
@@ -40,6 +40,7 @@ export interface TaskPlanOpts {
40
40
  item?: string;
41
41
  finishedWork?: PlanFinishedWork[];
42
42
  }
43
+ export declare const PLAYTEST_ROUTER_RULE = "- Task agents have a playtest tool: it loads the running deck headless, drives taps and keys, and returns screenshots and console output. When the user asks you to check, verify, or confirm whether something works, or reports something broken, end that task's prompt with this exact line: \"Before you report, verify this with the playtest tool: drive the thing in question, look at what came back, and say plainly what you saw.\". Do not add it to build asks -- the user tests those themselves.";
43
44
  export declare function truncateToBytes(line: string, budget: number): string;
44
45
  export type PlanOpVerb = "decide" | "open" | "tried" | "now" | "identity";
45
46
  export interface PlanOpSource {
@@ -82,6 +83,7 @@ export declare function buildRouterPrompt(opts: {
82
83
  messages: PromptMessage[];
83
84
  tasks: PromptTask[];
84
85
  plan?: RouterPlanOpts;
86
+ playtest?: boolean;
85
87
  instruction: string;
86
88
  }): string;
87
89
  export declare function userTurnInstruction(opts: {
@@ -104,5 +106,6 @@ export declare function buildTaskPrompt(opts: {
104
106
  quickReference?: string;
105
107
  siblings?: PromptSibling[];
106
108
  plan?: TaskPlanOpts;
109
+ playtest?: boolean;
107
110
  }): string;
108
111
  export declare const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";
@@ -20,7 +20,13 @@ const TRANSCRIPT_LIMIT = 40;
20
20
  // deck contents (ROUTER_DECK_CONTENTS_BUDGET, 40KB), the task board, and this
21
21
  // turn's instruction.
22
22
  const TRANSCRIPT_BYTE_BUDGET = 32 * 1024;
23
- const BASE_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.
23
+ // The playtest steering's router half, measured as one added bullet on the t1
24
+ // router ladder (memo 26-09-03-14-01): 15/18 written when asked, 6/6 withheld on
25
+ // build asks. The quoted line is what the task prompt's carve-out answers to;
26
+ // change either only as a new measured arm.
27
+ export const PLAYTEST_ROUTER_RULE = '- Task agents have a playtest tool: it loads the running deck headless, drives taps and keys, and returns screenshots and console output. When the user asks you to check, verify, or confirm whether something works, or reports something broken, end that task\'s prompt with this exact line: "Before you report, verify this with the playtest tool: drive the thing in question, look at what came back, and say plainly what you saw.". Do not add it to build asks -- the user tests those themselves.';
28
+ function baseRouterRules(playtest) {
29
+ return `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.
24
30
 
25
31
  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.
26
32
 
@@ -28,7 +34,7 @@ Hard rules:
28
34
  - You NEVER edit files or run state-changing commands. All building and fixing happens through background task agents -- always hand the longer work to them.
29
35
  - 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.
30
36
  - 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.
31
- - 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.
37
+ - 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}` : ""}
32
38
  - 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.
33
39
  - 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.
34
40
  - 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.
@@ -83,6 +89,7 @@ Conversation style:
83
89
  - The user sees a live task board above the chat -- never re-announce task status yourself.
84
90
  - 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.
85
91
  - The user playtests in the pane beside this chat; finished work shows up there after a reload.`;
92
+ }
86
93
  // Appended to the rules above for a deck with the plan doc on -- see
87
94
  // planSession in agent.ts for which decks those are. One self-contained block,
88
95
  // so a deck without it gets the pre-plan prompt byte for byte.
@@ -138,8 +145,9 @@ now- food-hauling
138
145
  Promotion. Finished tasks leave notes worth keeping, listed above with the id of the task that left each. Promote the keepers by quoting the note itself and citing its task; let the rest go -- they are offered once.
139
146
 
140
147
  If the user asks you to ease off the questions or the plan upkeep, record that with a \`decide+\` quoting the ask, and honor it -- keep \`## Now\` current, quietly.`;
141
- function routerRules(plan) {
142
- return plan ? `${BASE_ROUTER_RULES}\n\n${PLAN_RULES}` : BASE_ROUTER_RULES;
148
+ function routerRules(plan, playtest) {
149
+ const base = baseRouterRules(playtest);
150
+ return plan ? `${base}\n\n${PLAN_RULES}` : base;
143
151
  }
144
152
  function renderTranscriptLine(m) {
145
153
  if (m.role === "user")
@@ -821,7 +829,7 @@ export function buildRouterPrompt(opts) {
821
829
  // identity never change within a serve, the transcript is append-only, and
822
830
  // the churning state (file tree, task board, instruction) rides at the tail
823
831
  // so a task creating a file doesn't invalidate the cached transcript prefix.
824
- return `${routerRules(opts.plan !== undefined)}
832
+ return `${routerRules(opts.plan !== undefined, opts.playtest === true)}
825
833
 
826
834
  == deck ==
827
835
  ${opts.deckLabel}${quickReference}
@@ -917,7 +925,7 @@ ${opts.prompt}${deps}${siblings}${planSlice}
917
925
  Operating rules:
918
926
  - The file snapshot above is for orientation. Prefer going straight to the files this task touches, but if this is an investigation or debugging task, survey what you need to understand the failure.
919
927
  - Speed is of the essence -- go for the quickest viable, testable change, unless this prompt explicitly tells you to take longer and dive deep. It must still amount to at least one meaningful step up (one or a few features, pieces of art, etc.), never a token gesture.
920
- - The USER is the verifier -- the whole tasks system exists so the user playtests every change themselves. Your first priority is to finish as soon as possible with the change genuinely in place and reachable in the running deck, so the user can test it right away. Do NOT run verification (screenshots especially) unless you are really sure it will catch something a re-read of your own change cannot -- and even then at most one cheap check, never a retry loop. Time spent verifying is time the user is left waiting.
928
+ - The USER is the verifier -- the whole tasks system exists so the user playtests every change themselves. Your first priority is to finish as soon as possible with the change genuinely in place and reachable in the running deck, so the user can test it right away. Do NOT run verification (screenshots especially) unless ${opts.playtest ? "this task's brief asks for it or " : ""}you are really sure it will catch something a re-read of your own change cannot -- and even then at most one cheap check, never a retry loop. Time spent verifying is time the user is left waiting.
921
929
  - The moment implementation is complete and you switch to verifying, write 90 to the progress file -- verification time must not read as stalled progress.
922
930
  - Do this one task completely, then stop. Do not expand scope.${planRules}
923
931
  - SAVE A VERSION when your change is done, so the user can see and undo it: \`castle-web save-version -m "<short description of what you changed>" <each path you touched>\`. Name those paths explicitly -- a bare \`save-version\` with no paths records the WHOLE deck, including files a sibling agent is still working on. One version for the whole task, at the end; not one per file.
package/dist/agent.js CHANGED
@@ -23,7 +23,7 @@ import * as os from 'os';
23
23
  import * as path from 'path';
24
24
  import { nanoid } from 'nanoid';
25
25
  import { WebSocketServer } from 'ws';
26
- import { rawDataToString } from './ide.js';
26
+ import { rawDataToString } from './rawData.js';
27
27
  import { PLAN_FILE } from './localPaths.js';
28
28
  import { applyPlanOps, buildRouterPrompt, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
29
29
  import { readCastleJson } from './castleJson.js';
@@ -740,6 +740,16 @@ const planSessions = new Map();
740
740
  function planDefault() {
741
741
  return process.env.CASTLE_AGENT_PLAN !== 'off';
742
742
  }
743
+ // The playtest steering: one router rule plus the task prompt's carve-out
744
+ // (PLAYTEST_ROUTER_RULE in agent-prompts.ts). On unless the serve was told
745
+ // `CASTLE_AGENT_PLAYTEST=off` (the only env value that does anything; no
746
+ // per-deck switch), and never for cursor tasks, which are the one backend
747
+ // spawned without a playtest tool.
748
+ function playtestSteering(tasksBackend) {
749
+ if (tasksBackend === 'cursor')
750
+ return false;
751
+ return process.env.CASTLE_AGENT_PLAYTEST !== 'off';
752
+ }
743
753
  function planSession(deckDir) {
744
754
  const existing = planSessions.get(deckDir);
745
755
  if (existing)
@@ -2499,6 +2509,7 @@ async function runTaskAgentIn(ctx, task) {
2499
2509
  handoffPath: path.join(relDir, 'handoff'),
2500
2510
  depsSummary: ctx.depsSummary,
2501
2511
  backend: ctx.backend,
2512
+ playtest: playtestSteering(ctx.backend),
2502
2513
  // Slimmed once contents are inlined -- see DECK_TREE_SLIM_* above.
2503
2514
  deckTree: buildDeckTree(ctx.deckDir, isSmith
2504
2515
  ? { maxEntries: DECK_TREE_SLIM_MAX_ENTRIES, perDir: DECK_TREE_SLIM_PER_DIR }
@@ -3242,6 +3253,7 @@ function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
3242
3253
  ? { maxEntries: DECK_TREE_SLIM_MAX_ENTRIES, perDir: DECK_TREE_SLIM_PER_DIR }
3243
3254
  : undefined),
3244
3255
  deckContents: isSmith ? buildDeckContents(ctx.deckDir, ROUTER_DECK_CONTENTS_BUDGET) : undefined,
3256
+ playtest: playtestSteering(ctx.tasksBackend()),
3245
3257
  messages: ctx.log.messages
3246
3258
  .filter((m) => m.role !== 'log' && m.id !== selfMessageId && m.status !== 'streaming')
3247
3259
  .map((m) => ({
@@ -3883,6 +3895,7 @@ function startRouterTurn(ctx, instruction, attachments = []) {
3883
3895
  messageThinking: ctx.messageThinking,
3884
3896
  currentEpoch: () => ctx.state.userEpoch,
3885
3897
  backend: () => ctx.settings.router,
3898
+ tasksBackend: () => ctx.settings.tasks,
3886
3899
  claudeModel: () => ctx.settings.routerClaudeModel,
3887
3900
  openrouterModel: () => ctx.settings.routerOpenrouterModel,
3888
3901
  openrouterTuning: () => ({
@@ -31,6 +31,14 @@ const COMMAND_NAMES = [
31
31
  "portal.prefetch",
32
32
  "haptics.play",
33
33
  "multiplayer.getSession",
34
+ "cauldronStorage.get",
35
+ "cauldronStorage.set",
36
+ "cauldronStorage.delete",
37
+ "cauldronStorage.increment",
38
+ "cauldronStorage.list",
39
+ "cauldronStorage.boardSubmit",
40
+ "cauldronStorage.boardTop",
41
+ "cauldronStorage.boardGet",
34
42
  ];
35
43
  // Platform/capability commands: NOT serviced by graphqlFetch. They're dispatched
36
44
  // to the host's optional platformHandler (mobile renders native UI; web shows an
@@ -116,6 +124,22 @@ function runCommand(ctx, command, params, caps) {
116
124
  return passHas(ctx, params, caps);
117
125
  case "multiplayer.getSession":
118
126
  return multiplayerGetSession(ctx, params, caps);
127
+ case "cauldronStorage.get":
128
+ return cauldronStorageGet(ctx, params, gql);
129
+ case "cauldronStorage.set":
130
+ return cauldronStorageSet(ctx, params, gql);
131
+ case "cauldronStorage.delete":
132
+ return cauldronStorageDelete(ctx, params, gql);
133
+ case "cauldronStorage.increment":
134
+ return cauldronStorageIncrement(ctx, params, gql);
135
+ case "cauldronStorage.list":
136
+ return cauldronStorageList(ctx, params, gql);
137
+ case "cauldronStorage.boardSubmit":
138
+ return cauldronStorageBoardSubmit(ctx, params, gql);
139
+ case "cauldronStorage.boardTop":
140
+ return cauldronStorageBoardTop(ctx, params, gql);
141
+ case "cauldronStorage.boardGet":
142
+ return cauldronStorageBoardGet(ctx, params, gql);
119
143
  // Platform commands are handled above; listed here to keep the switch
120
144
  // exhaustive over CommandName.
121
145
  case "pass.offer":
@@ -699,6 +723,122 @@ function asNumberish(value) {
699
723
  const parsed = Number.parseFloat(value);
700
724
  return Number.isFinite(parsed) ? parsed : null;
701
725
  }
726
+ // ---------------------------------------------------------------------------
727
+ // Cauldron deck storage.
728
+ //
729
+ // Each of these maps to exactly one bounded server-side operation. The deck
730
+ // names a scope and keys; it never names the deck, and it never names a user for
731
+ // anything the server treats as identity. `subject` is meaningful only on
732
+ // user-scope reads (whose public data to read) and, for a session server, on
733
+ // writes; ghost pins private scope to the caller regardless of what is sent.
734
+ function asStoreScope(value, command) {
735
+ if (value === "deck" || value === "user" || value === "private") {
736
+ return value;
737
+ }
738
+ throw new HostCommandError("CASTLE_STORAGE_INVALID_SCOPE", `Storage scope must be "deck", "user" or "private".`, command);
739
+ }
740
+ // The GraphQL enum is upper-case; the deck-facing scope names are not.
741
+ function storeScopeEnum(scope) {
742
+ return scope.toUpperCase();
743
+ }
744
+ function asStoreEntries(value, command) {
745
+ if (!Array.isArray(value)) {
746
+ throw new HostCommandError("CASTLE_STORAGE_INVALID_ENTRIES", "Storage entries must be an array.", command);
747
+ }
748
+ return value.map((entry) => {
749
+ const row = entry;
750
+ return {
751
+ key: asString(row.key, "key", command),
752
+ value: asString(row.value, "value", command),
753
+ };
754
+ });
755
+ }
756
+ async function cauldronStorageGet(ctx, params, gql) {
757
+ const deckId = requireDeckId(ctx, "cauldronStorage.get");
758
+ const data = await graphql(gql, CAULDRON_STORAGE_GET_QUERY, {
759
+ deckId,
760
+ scope: storeScopeEnum(asStoreScope(params.scope, "cauldronStorage.get")),
761
+ subject: asOptionalString(params.subject),
762
+ keys: asKeys(params.keys),
763
+ }, "cauldronStorage.get");
764
+ return { entries: data.cauldronStorageGet ?? [] };
765
+ }
766
+ async function cauldronStorageList(ctx, params, gql) {
767
+ const deckId = requireDeckId(ctx, "cauldronStorage.list");
768
+ const data = await graphql(gql, CAULDRON_STORAGE_LIST_QUERY, {
769
+ deckId,
770
+ scope: storeScopeEnum(asStoreScope(params.scope, "cauldronStorage.list")),
771
+ subject: asOptionalString(params.subject),
772
+ prefix: asOptionalString(params.prefix),
773
+ limit: asOptionalNumber(params.limit),
774
+ cursor: asOptionalString(params.cursor),
775
+ }, "cauldronStorage.list");
776
+ const page = data.cauldronStorageList;
777
+ return { entries: page?.entries ?? [], cursor: page?.cursor ?? null };
778
+ }
779
+ async function cauldronStorageSet(ctx, params, gql) {
780
+ const deckId = requireDeckId(ctx, "cauldronStorage.set");
781
+ const data = await graphql(gql, CAULDRON_STORAGE_SET_MUTATION, {
782
+ deckId,
783
+ scope: storeScopeEnum(asStoreScope(params.scope, "cauldronStorage.set")),
784
+ subject: asOptionalString(params.subject),
785
+ entries: asStoreEntries(params.entries, "cauldronStorage.set"),
786
+ asServer: params.asServer === true,
787
+ }, "cauldronStorage.set", params.unload === true ? { unload: true } : undefined);
788
+ return { usage: data.cauldronStorageSet };
789
+ }
790
+ async function cauldronStorageDelete(ctx, params, gql) {
791
+ const deckId = requireDeckId(ctx, "cauldronStorage.delete");
792
+ const data = await graphql(gql, CAULDRON_STORAGE_DELETE_MUTATION, {
793
+ deckId,
794
+ scope: storeScopeEnum(asStoreScope(params.scope, "cauldronStorage.delete")),
795
+ subject: asOptionalString(params.subject),
796
+ keys: asKeys(params.keys),
797
+ asServer: params.asServer === true,
798
+ }, "cauldronStorage.delete", params.unload === true ? { unload: true } : undefined);
799
+ return { usage: data.cauldronStorageDelete };
800
+ }
801
+ async function cauldronStorageIncrement(ctx, params, gql) {
802
+ const deckId = requireDeckId(ctx, "cauldronStorage.increment");
803
+ const data = await graphql(gql, CAULDRON_STORAGE_INCREMENT_MUTATION, {
804
+ deckId,
805
+ scope: storeScopeEnum(asStoreScope(params.scope, "cauldronStorage.increment")),
806
+ subject: asOptionalString(params.subject),
807
+ key: asString(params.key, "key", "cauldronStorage.increment"),
808
+ delta: asNumber(params.delta, "delta", "cauldronStorage.increment"),
809
+ asServer: params.asServer === true,
810
+ }, "cauldronStorage.increment");
811
+ return { value: data.cauldronStorageIncrement };
812
+ }
813
+ async function cauldronStorageBoardSubmit(ctx, params, gql) {
814
+ const deckId = requireDeckId(ctx, "cauldronStorage.boardSubmit");
815
+ const data = await graphql(gql, CAULDRON_STORAGE_BOARD_SUBMIT_MUTATION, {
816
+ deckId,
817
+ board: asString(params.board, "board", "cauldronStorage.boardSubmit"),
818
+ subject: asOptionalString(params.subject),
819
+ score: asNumber(params.score, "score", "cauldronStorage.boardSubmit"),
820
+ asServer: params.asServer === true,
821
+ }, "cauldronStorage.boardSubmit");
822
+ return { entry: data.cauldronStorageBoardSubmit };
823
+ }
824
+ async function cauldronStorageBoardTop(ctx, params, gql) {
825
+ const deckId = requireDeckId(ctx, "cauldronStorage.boardTop");
826
+ const data = await graphql(gql, CAULDRON_STORAGE_BOARD_TOP_QUERY, {
827
+ deckId,
828
+ board: asString(params.board, "board", "cauldronStorage.boardTop"),
829
+ limit: asOptionalNumber(params.limit),
830
+ }, "cauldronStorage.boardTop");
831
+ return { entries: data.cauldronStorageBoardTop ?? [] };
832
+ }
833
+ async function cauldronStorageBoardGet(ctx, params, gql) {
834
+ const deckId = requireDeckId(ctx, "cauldronStorage.boardGet");
835
+ const data = await graphql(gql, CAULDRON_STORAGE_BOARD_GET_QUERY, {
836
+ deckId,
837
+ board: asString(params.board, "board", "cauldronStorage.boardGet"),
838
+ subject: asOptionalString(params.subject),
839
+ }, "cauldronStorage.boardGet");
840
+ return { entry: data.cauldronStorageBoardGet ?? null };
841
+ }
702
842
  const DECK_STORAGE_QUERY = `
703
843
  query CastleDeckStorage($deckId: ID!, $sessionId: ID) {
704
844
  deckStorage(deckId: $deckId, sessionId: $sessionId)
@@ -955,3 +1095,139 @@ const CAULDRON_MULTIPLAYER_SESSION_QUERY = `
955
1095
  }
956
1096
  }
957
1097
  `;
1098
+ const CAULDRON_STORAGE_GET_QUERY = `
1099
+ query CastleCauldronStorageGet(
1100
+ $deckId: ID!
1101
+ $scope: CauldronStorageScope!
1102
+ $subject: ID
1103
+ $keys: [String!]!
1104
+ ) {
1105
+ cauldronStorageGet(deckId: $deckId, scope: $scope, subject: $subject, keys: $keys) {
1106
+ key
1107
+ value
1108
+ }
1109
+ }
1110
+ `;
1111
+ const CAULDRON_STORAGE_LIST_QUERY = `
1112
+ query CastleCauldronStorageList(
1113
+ $deckId: ID!
1114
+ $scope: CauldronStorageScope!
1115
+ $subject: ID
1116
+ $prefix: String
1117
+ $limit: Int
1118
+ $cursor: String
1119
+ ) {
1120
+ cauldronStorageList(
1121
+ deckId: $deckId
1122
+ scope: $scope
1123
+ subject: $subject
1124
+ prefix: $prefix
1125
+ limit: $limit
1126
+ cursor: $cursor
1127
+ ) {
1128
+ entries {
1129
+ key
1130
+ value
1131
+ }
1132
+ cursor
1133
+ }
1134
+ }
1135
+ `;
1136
+ const CAULDRON_STORAGE_SET_MUTATION = `
1137
+ mutation CastleCauldronStorageSet(
1138
+ $deckId: ID!
1139
+ $scope: CauldronStorageScope!
1140
+ $subject: ID
1141
+ $entries: [CauldronStorageEntryInput!]!
1142
+ $asServer: Boolean
1143
+ ) {
1144
+ cauldronStorageSet(
1145
+ deckId: $deckId
1146
+ scope: $scope
1147
+ subject: $subject
1148
+ entries: $entries
1149
+ asServer: $asServer
1150
+ ) {
1151
+ rowCount
1152
+ byteCount
1153
+ }
1154
+ }
1155
+ `;
1156
+ const CAULDRON_STORAGE_DELETE_MUTATION = `
1157
+ mutation CastleCauldronStorageDelete(
1158
+ $deckId: ID!
1159
+ $scope: CauldronStorageScope!
1160
+ $subject: ID
1161
+ $keys: [String!]!
1162
+ $asServer: Boolean
1163
+ ) {
1164
+ cauldronStorageDelete(
1165
+ deckId: $deckId
1166
+ scope: $scope
1167
+ subject: $subject
1168
+ keys: $keys
1169
+ asServer: $asServer
1170
+ ) {
1171
+ rowCount
1172
+ byteCount
1173
+ }
1174
+ }
1175
+ `;
1176
+ const CAULDRON_STORAGE_INCREMENT_MUTATION = `
1177
+ mutation CastleCauldronStorageIncrement(
1178
+ $deckId: ID!
1179
+ $scope: CauldronStorageScope!
1180
+ $subject: ID
1181
+ $key: String!
1182
+ $delta: Float!
1183
+ $asServer: Boolean
1184
+ ) {
1185
+ cauldronStorageIncrement(
1186
+ deckId: $deckId
1187
+ scope: $scope
1188
+ subject: $subject
1189
+ key: $key
1190
+ delta: $delta
1191
+ asServer: $asServer
1192
+ )
1193
+ }
1194
+ `;
1195
+ const CAULDRON_STORAGE_BOARD_SUBMIT_MUTATION = `
1196
+ mutation CastleCauldronStorageBoardSubmit(
1197
+ $deckId: ID!
1198
+ $board: String!
1199
+ $subject: ID
1200
+ $score: Float!
1201
+ $asServer: Boolean
1202
+ ) {
1203
+ cauldronStorageBoardSubmit(
1204
+ deckId: $deckId
1205
+ board: $board
1206
+ subject: $subject
1207
+ score: $score
1208
+ asServer: $asServer
1209
+ ) {
1210
+ subject
1211
+ score
1212
+ updatedAt
1213
+ }
1214
+ }
1215
+ `;
1216
+ const CAULDRON_STORAGE_BOARD_TOP_QUERY = `
1217
+ query CastleCauldronStorageBoardTop($deckId: ID!, $board: String!, $limit: Int) {
1218
+ cauldronStorageBoardTop(deckId: $deckId, board: $board, limit: $limit) {
1219
+ subject
1220
+ score
1221
+ updatedAt
1222
+ }
1223
+ }
1224
+ `;
1225
+ const CAULDRON_STORAGE_BOARD_GET_QUERY = `
1226
+ query CastleCauldronStorageBoardGet($deckId: ID!, $board: String!, $subject: ID) {
1227
+ cauldronStorageBoardGet(deckId: $deckId, board: $board, subject: $subject) {
1228
+ subject
1229
+ score
1230
+ updatedAt
1231
+ }
1232
+ }
1233
+ `;
@@ -1,5 +1,6 @@
1
1
  import { pathToFileURL } from 'url';
2
2
  import WebSocket from 'ws';
3
+ import { rawDataToString } from './rawData.js';
3
4
  const PROTOCOL_VERSION = 1;
4
5
  class PlatformEvents {
5
6
  callbacks = new Map();
@@ -22,18 +23,75 @@ let initialized = false;
22
23
  let shuttingDown = false;
23
24
  let messageQueue = Promise.resolve();
24
25
  socket.on('message', (data, isBinary) => {
26
+ // A storage reply jumps the queue for the same reason it does in production: it is
27
+ // not an event, it settles a promise something already queued is awaiting. Behind
28
+ // the queue, a save inside `onShutdown` would deadlock against the shutdown it is
29
+ // blocking.
30
+ if (!isBinary && settleStorageMessage(rawDataToString(data)))
31
+ return;
25
32
  messageQueue = messageQueue.then(() => handleMessage(data, isBinary));
26
33
  void messageQueue.catch(fail);
27
34
  });
28
35
  socket.on('error', (error) => console.error(`platform channel error: ${error.message}`));
29
36
  socket.on('close', () => {
37
+ failPendingStorage('the platform channel closed');
30
38
  if (!shuttingDown)
31
39
  process.exit(1);
32
40
  });
41
+ const pendingStorage = new Map();
42
+ let nextStorageRequestId = 1;
43
+ function requestStorage(op, argsJson) {
44
+ const reqId = String(nextStorageRequestId++);
45
+ return new Promise((resolve, reject) => {
46
+ pendingStorage.set(reqId, { resolve, reject });
47
+ send({
48
+ protocolVersion: PROTOCOL_VERSION,
49
+ t: 'storageRequest',
50
+ reqId,
51
+ op,
52
+ args: JSON.parse(argsJson),
53
+ });
54
+ });
55
+ }
56
+ function settleStorageMessage(text) {
57
+ let value;
58
+ try {
59
+ value = JSON.parse(text);
60
+ }
61
+ catch {
62
+ return false;
63
+ }
64
+ const frame = value;
65
+ if (!frame || frame.t !== 'storageResult' || typeof frame.reqId !== 'string')
66
+ return false;
67
+ const pending = pendingStorage.get(frame.reqId);
68
+ if (!pending)
69
+ return true;
70
+ pendingStorage.delete(frame.reqId);
71
+ if (frame.ok === true) {
72
+ pending.resolve(JSON.stringify(frame.value ?? null));
73
+ }
74
+ else {
75
+ const error = asRecord(frame.error);
76
+ pending.reject(storageFailure(asText(error.code, 'CAULDRON_STORAGE_UNAVAILABLE'), asText(error.message, 'storage request failed')));
77
+ }
78
+ return true;
79
+ }
80
+ function failPendingStorage(message) {
81
+ for (const pending of pendingStorage.values()) {
82
+ pending.reject(storageFailure('CAULDRON_STORAGE_UNAVAILABLE', message));
83
+ }
84
+ pendingStorage.clear();
85
+ }
86
+ function storageFailure(code, message) {
87
+ const error = new Error(message);
88
+ error.code = code;
89
+ return error;
90
+ }
33
91
  async function handleMessage(data, isBinary) {
34
92
  if (isBinary)
35
93
  throw new Error('platform channel sent a binary frame');
36
- const frame = parseFrame(data.toString());
94
+ const frame = parseFrame(rawDataToString(data));
37
95
  if (!initialized) {
38
96
  if (frame.t !== 'init')
39
97
  throw new Error('expected init as the first platform frame');
@@ -77,6 +135,10 @@ function createPlatformHandle(init, platformEvents) {
77
135
  on(event, callback) {
78
136
  platformEvents.on(event, callback);
79
137
  },
138
+ storage: requestStorage,
139
+ // Always on in dev: the serve services these itself, with the signed-in author's
140
+ // own credentials, against the real deck.
141
+ storageEnabled: true,
80
142
  config: Object.freeze({
81
143
  sessionId: String(init.sessionId),
82
144
  deckId: String(init.deckId),
@@ -134,6 +196,9 @@ function binaryBase64(bytes) {
134
196
  : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
135
197
  return buffer.toString('base64');
136
198
  }
199
+ function asText(value, fallback) {
200
+ return typeof value === 'string' ? value : fallback;
201
+ }
137
202
  function asRecord(value) {
138
203
  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
139
204
  throw new Error('platform channel sent an invalid frame');
@@ -7,6 +7,8 @@ import * as path from 'path';
7
7
  import { fileURLToPath } from 'url';
8
8
  import { WebSocketServer, WebSocket } from 'ws';
9
9
  import { readCastleJson, resolveServerConfig } from './castleJson.js';
10
+ import { runDevStorageOperation } from './devSessionStorage.js';
11
+ import { rawDataToString } from './rawData.js';
10
12
  import { bundleServerModule } from './serverBundle.js';
11
13
  const PROTOCOL_VERSION = 1;
12
14
  const MAX_CLIENT_FRAME_BYTES = 16 * 1024;
@@ -253,7 +255,7 @@ class DevSessionServerImpl {
253
255
  }
254
256
  let frame;
255
257
  try {
256
- frame = asRecord(JSON.parse(data.toString()));
258
+ frame = asRecord(JSON.parse(rawDataToString(data)));
257
259
  }
258
260
  catch {
259
261
  socket.close(1007, 'invalid JSON');
@@ -310,7 +312,7 @@ class DevSessionServerImpl {
310
312
  }
311
313
  let frame;
312
314
  try {
313
- frame = asRecord(JSON.parse(data.toString()));
315
+ frame = asRecord(JSON.parse(rawDataToString(data)));
314
316
  }
315
317
  catch {
316
318
  this.platformSocket?.close(1007, 'invalid JSON');
@@ -357,6 +359,23 @@ class DevSessionServerImpl {
357
359
  else if (frame.t === 'kick' && typeof frame.playerId === 'string') {
358
360
  this.kick(frame.playerId, typeof frame.reason === 'string' ? frame.reason : undefined);
359
361
  }
362
+ else if (frame.t === 'storageRequest' &&
363
+ typeof frame.reqId === 'string' &&
364
+ typeof frame.op === 'string') {
365
+ void this.handleStorageRequest(frame.reqId, frame.op, asRecord(frame.args));
366
+ }
367
+ }
368
+ async handleStorageRequest(reqId, op, args) {
369
+ const deckId = readCastleJson(this.projectDir)?.deckId;
370
+ const result = await runDevStorageOperation(deckId, op, args);
371
+ // The child may have restarted while this was out; its replacement never asked, so
372
+ // there is nobody to tell.
373
+ this.sendPlatform({
374
+ protocolVersion: PROTOCOL_VERSION,
375
+ t: 'storageResult',
376
+ reqId,
377
+ ...result,
378
+ });
360
379
  }
361
380
  runtimeClosed(socket) {
362
381
  if (this.platformSocket !== socket)
@@ -0,0 +1,9 @@
1
+ export interface DevStorageResult {
2
+ ok: boolean;
3
+ value?: unknown;
4
+ error?: {
5
+ code: string;
6
+ message: string;
7
+ };
8
+ }
9
+ export declare function runDevStorageOperation(deckId: string | undefined, op: string, args: Record<string, unknown>): Promise<DevStorageResult>;