castle-web-cli 0.4.213 → 0.4.215

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.
@@ -13,6 +13,12 @@ export interface PromptTask {
13
13
  error?: string;
14
14
  blockedBy?: string[];
15
15
  }
16
+ export interface PromptStop {
17
+ title: string;
18
+ id: string;
19
+ progress: number;
20
+ repliesAgo: number;
21
+ }
16
22
  export interface PromptSibling {
17
23
  title: string;
18
24
  status: string;
@@ -41,6 +47,10 @@ export interface TaskPlanOpts {
41
47
  finishedWork?: PlanFinishedWork[];
42
48
  }
43
49
  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.";
50
+ export declare const PLAYTEST_OFF_FENCE_RULE = "- If the user asks for no playtest checks or frames, turn them off for this deck: emit this fence, confirm in one line, and never add the verify line again:\n```castle-pref\nplaytest: off\n```";
51
+ export declare const PLAYTEST_ON_FENCE_RULE = "- The user turned playtest checks off for this deck: never ask a task to verify with the playtest tool. If they ask for them back, emit this fence and confirm in one line:\n```castle-pref\nplaytest: on\n```";
52
+ export declare const TASK_FENCE_PROMPT_EXAMPLE = "Then a SHORT self-contained prompt -- one tight paragraph (aim under 100\nwords): what to build or fix and what \"done\" looks like. Task agents read\nthe deck's own docs for framework/API detail, so never restate recipes,\nfile layouts, or implementation steps.";
53
+ export declare const PLAYTEST_TASK_UNDRIVEN_RULE = "- The playtest tool is a headless preview, not the user's device. If you could not make the behavior in question happen there, or checking it needs something the preview did not give you (a microphone, a camera, a second player, a native app command, the phone's on-screen keyboard), your result says exactly that -- \"I could not drive X in the headless preview because Y; unverified\" -- instead of reporting what the code implies. Never write \"verified\" for something you did not observe, and when you did observe it, say it was verified in the headless preview.";
44
54
  export declare function truncateToBytes(line: string, budget: number): string;
45
55
  export type PlanOpVerb = "decide" | "open" | "tried" | "now" | "identity";
46
56
  export interface PlanOpSource {
@@ -75,6 +85,7 @@ export declare function renderPlanDigest(plan: RouterPlanOpts, tasks: PromptTask
75
85
  export declare function planOpenQuestionLines(fileText: string): string[];
76
86
  export declare function renderTaskPlanSlice(fileText: string, item: string | undefined, finishedWork?: PlanFinishedWork[]): string;
77
87
  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.).";
88
+ export declare const STOPPED_TASKS_HEADER = "Tasks you stopped with castle-stop. They started and you cancelled them; none finished. What the user saw: the task appeared on their board and then vanished. So if the user says a task never started, or asks where it went, say plainly that you stopped it (not that it never started), then re-send it if they still want it";
78
89
  export interface RouterPromptParts {
79
90
  system: string;
80
91
  user: string;
@@ -85,8 +96,10 @@ export interface RouterPromptOpts {
85
96
  deckTree?: string;
86
97
  messages: PromptMessage[];
87
98
  tasks: PromptTask[];
99
+ stopped?: PromptStop[];
88
100
  plan?: RouterPlanOpts;
89
101
  playtest?: boolean;
102
+ playtestPref?: 'on' | 'off';
90
103
  askCalls?: boolean;
91
104
  editorTabs?: string[];
92
105
  kits?: string[];
@@ -123,6 +136,7 @@ export declare function buildTaskPrompt(opts: {
123
136
  siblings?: PromptSibling[];
124
137
  plan?: TaskPlanOpts;
125
138
  playtest?: boolean;
139
+ git?: boolean;
126
140
  }): string;
127
141
  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.";
128
142
  export declare const MUSE_TASK_ADDENDUM = "Kit code rules for this deck. The kit guide documents every API you need; use exactly the names and signatures it gives and nothing else. Do not guess at APIs: no typeof checks on methods, no ?. or ?? fallbacks on documented objects, no try/catch around ordinary calls, no alternate spellings of a callback. One mechanism per feature, chosen for what the task asks (a tap on the actor is its onTap; a tap anywhere on the card is the pointer checked in update; a contact is onCollisionEnter): use that one and never also scan for the same event another way. Props come from defaultProps, so never repeat a default with ?? value. Find actors by the behavior or id the task names; never sniff ids like 'player' or 'ball' as fallbacks. Read the guide's gotchas for every API you use and follow them. Reference only files that exist in the deck tree or that you create in this task. Build everything the task names and only that: no extra input methods, actors, or polish it did not mention.";
@@ -24,7 +24,23 @@ const TRANSCRIPT_BYTE_BUDGET = 32 * 1024;
24
24
  // build asks. The quoted line is what the task prompt's carve-out answers to;
25
25
  // change either only as a new measured arm.
26
26
  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.';
27
- function baseRouterRules(playtest) {
27
+ export const PLAYTEST_OFF_FENCE_RULE = '- If the user asks for no playtest checks or frames, turn them off for this deck: emit this fence, confirm in one line, and never add the verify line again:\n```castle-pref\nplaytest: off\n```';
28
+ export const PLAYTEST_ON_FENCE_RULE = '- The user turned playtest checks off for this deck: never ask a task to verify with the playtest tool. If they ask for them back, emit this fence and confirm in one line:\n```castle-pref\nplaytest: on\n```';
29
+ export const TASK_FENCE_PROMPT_EXAMPLE = `Then a SHORT self-contained prompt -- one tight paragraph (aim under 100
30
+ words): what to build or fix and what "done" looks like. Task agents read
31
+ the deck's own docs for framework/API detail, so never restate recipes,
32
+ file layouts, or implementation steps.`;
33
+ // Directive v2, the task half: added beside the v1 verify line rather than as an
34
+ // edit of it (memo 26-09-03-13-27), so v1's measured wording stands.
35
+ export const PLAYTEST_TASK_UNDRIVEN_RULE = '- The playtest tool is a headless preview, not the user\'s device. If you could not make the behavior in question happen there, or checking it needs something the preview did not give you (a microphone, a camera, a second player, a native app command, the phone\'s on-screen keyboard), your result says exactly that -- "I could not drive X in the headless preview because Y; unverified" -- instead of reporting what the code implies. Never write "verified" for something you did not observe, and when you did observe it, say it was verified in the headless preview.';
36
+ function baseRouterRules(playtest, playtestPref) {
37
+ const playtestRules = playtestPref === 'off'
38
+ ? `\n${PLAYTEST_ON_FENCE_RULE}`
39
+ : playtestPref === 'on'
40
+ ? `\n${PLAYTEST_ROUTER_RULE}\n${PLAYTEST_OFF_FENCE_RULE}`
41
+ : playtest
42
+ ? `\n${PLAYTEST_ROUTER_RULE}`
43
+ : '';
28
44
  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.
29
45
 
30
46
  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.
@@ -32,12 +48,12 @@ What a deck is: a normal web project served by vite -- index.html plus plain JS/
32
48
  What the user sees beside this chat: Castle's own panels -- Play, Files, Parameters, Terminal, and this chat -- plus a tab for each file they open. Those panels belong to Castle, and nothing in the deck can change them. The Parameters panel is where the deck's tunable values live: everything any file exposes as \`PARAMS\`. A file's tab is different: unless it is the plain code view, it is an EDITOR, an ordinary module that comes from the deck or its kit (this deck's are listed under == editor tabs ==). Users name one by its label ("the <label> tab") or just say "this tab", and they mean that editor, not Castle. When they ask whether a tab can do something it doesn't do yet, or whether it can be changed at all, the answer is yes: a task forks the kit's editor into the deck and changes that copy (see the imports rule below), or gives a new file type an editor of its own. Never tell the user a file's tab is part of Castle.
33
49
 
34
50
  Hard rules:
35
- - 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.
36
- - 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.
51
+ - You NEVER edit files or run state-changing commands, with two exceptions: imports (next rule) and restoring a version the user asked to go back to (the version-history rule). All building and fixing happens through background task agents -- always hand the longer work to them.
52
+ - IMPORTS ARE YOURS, and they are an 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.
37
53
  - A deck can lack what a kit provides. == kits this deck can import == (present only on a deck that runs no kit) lists each kit this platform ships: what it is for and the file types its editors open. When the user asks for one of those things -- a file type, an editor, a way of working the listing names -- and this deck's guide says it has no such thing, they are asking for that kit, whether they phrase it as a request or as a how-to question. Do not explain the absence, do not paste code that imitates it, and do not spawn a task to build a substitute: import the kit yourself in that same turn with the exact command the listing gives, and read its output. "This deck now runs" in the output means the deck switched over -- its starter content and editors are in place -- so say in one line what the deck now has, tell them to reload the Play panel (its Restart button) to see it, since it keeps running the old code until then, and handle the rest of their ask the way you would on any deck built on that kit. Any other output means the deck kept its own code: the kit is imported but not running, and switching over replaces what they built -- say that and ask which they want before anything else; on a yes, a task repoints the entry point the output names. When the deck's own guide already covers what they asked for, this rule is not in play.
38
54
  - 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 (an editor tab included), 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.
39
55
  - 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. That brief carries the SYMPTOM, not a cause: the user's own words for what they saw, quoted, plus where the behavior lives when the docs or the conversation name it. You have not read the code, so a mechanism you name is a guess, and a task given a guess implements the guess instead of investigating. A QUESTION is not a fix request: "why is X happening?" gets a task told explicitly to diagnose and CHANGE NOTHING, and your reply says that it will only look and report back.
40
- - 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}` : ""}
56
+ - 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.${playtestRules}
41
57
  - 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.
42
58
  - When the user asks what they can tune, what controls something, or where to change a value, first see whether that value is already tunable: a key in that file's \`PARAMS\` object, or one of the \`knobs:\` a \`## Built\` line lists. If it is, do not spawn a task to move it -- link that one value with \`#params:key\`. If they asked for it to change, make that change the way any tweak is made, with a task that sets it, and say they can keep adjusting it in the Parameters panel; otherwise tell them they can change it there now. If it is not -- a plain constant or expression in code -- spawn the task that moves it into that file's \`PARAMS\` object, keeping its current value as the default and adding a \`PARAMS_META\` range where one is obvious, and say in your plain-text line that it is going into the Parameters panel, linking that file's \`#params\` where it will land. If they also asked for a new value, the same task sets it. If they asked where it is set, link the file too (the line, if you have read it) -- the move does not replace the answer. Do not just point them at the line. Three different things get called a parameter: an argument a function takes (plain code, nothing to do with the panel); a setting each placed thing carries for itself, so two of them can differ -- the deck's own guide says what those are called and where they are set, and they never go in \`PARAMS\`; and one value for the whole deck that someone tunes while playing, which is the only kind the panel holds. The deciding question is scope: does each one need its own value, or is there one value for everyone? Read that from what they are trying to do; when it is genuinely unclear, ask.
43
59
  - 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.
@@ -50,10 +66,7 @@ Hard rules:
50
66
  \`\`\`castle-task
51
67
  short imperative title on the first line
52
68
  after: comma-separated titles or ids this task must wait for (optional line)
53
- Then a SHORT self-contained prompt -- one tight paragraph (aim under 100
54
- words): what to build or fix and what "done" looks like. Task agents read
55
- the deck's own docs for framework/API detail, so never restate recipes,
56
- file layouts, or implementation steps.
69
+ ${TASK_FENCE_PROMPT_EXAMPLE}
57
70
  \`\`\`
58
71
 
59
72
  - Use \`after:\` only for the fallback case above -- a task that genuinely needs another's produced output (it may reference tasks spawned in this same reply, by title). Never for file-contention; independent tasks must NOT wait on each other.
@@ -68,14 +81,15 @@ comma-separated active-task titles or ids, or \`all\`
68
81
  \`\`\`
69
82
 
70
83
  - \`castle-done\` removes FINISHED rows (done/failed). Use it when the user confirms a task works, or to clear a finished task that has become obsolete (replaced by newer work). \`all\` clears every finished row.
71
- - \`castle-stop\` stops AND removes ACTIVE rows (running/waiting/blocked) -- a running task's agent is killed. Use it when the user asks to stop something, or when you spawn a fix/replacement that makes an in-flight task obsolete. \`all\` stops everything active.
72
- - When you spawn a task that fixes, redoes, or replaces an earlier one, remove the earlier one in the SAME reply: \`castle-done\` if it already finished, \`castle-stop\` if it is still running, waiting, or blocked. Keep the board meaning "what to look at right now".
84
+ - \`castle-stop\` stops AND removes ACTIVE rows (running/waiting/blocked) -- a running task's agent is killed. Its unfinished work is thrown away. Use it when the user asks to stop something, or under the rule below. \`all\` stops everything active.
85
+ - When you spawn a task that fixes or redoes a FINISHED one, \`castle-done\` the earlier row in the SAME reply. Keep the board meaning "what to look at right now".
86
+ - Stop a running or waiting task only when the new message makes its work unwanted: the user said to stop or drop it, took back or reversed what it is building, or corrected it -- it has the wrong idea, or they picked a different option than the one it is building -- so its result would have to be undone. When that change comes with new work, stop it in the SAME reply that spawns the replacement. When the new ask adds to a running task, extends it, or is about something else, leave it running and spawn the new work as its own task: in parallel, or with \`after:\` naming it only when the new work needs that task's actual output. Nothing reaches a running task, so leaving it running never covers the new ask by itself. Never stop a task because a new one restates it or covers it more broadly.
73
87
  - A \`failed\` row carries an \`error:\` line -- why it failed. A \`blocked\` row waited on a dep that failed or was stopped, so its output never arrived and it will never start on its own -- \`blocked by:\` names that dep. When you see one, decide for the user: usually spawn a replacement task (or pipeline) that redoes the failed work, and in the SAME reply \`castle-stop\` the blocked row and \`castle-done\` the failed one, so the board stays clean.
74
88
  - Do not mark a task done to imply YOU verified its quality -- the user playtests and confirms that. But DO keep the board tidy: clear finished work the user blessed, and remove anything clearly obsolete. When genuinely unsure, leave the row.
75
89
  - Never claim the board is cleared without actually emitting the fence.
76
- - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it.
90
+ - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it -- unless their words ask to go back to an earlier state, which is the version-history rule below.
77
91
  - Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
78
- - The deck keeps its own version history, and you may READ it: \`castle-web list-versions\` shows the versions newest first, and \`castle-web show-version <id>\` shows what one changed, as diffs of just those files. Use them to answer "what changed" or to ground a claim about recent work. You NEVER run \`save-version\` -- you did not make the changes, so a version of yours would not correspond to a unit of work -- and you NEVER run \`restore-version\`: going back is the user's own decision, not something you do on their behalf. For the same reason, no task you spawn may ever revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit or starter content -- a fix is always a targeted edit, and every task prompt you write has to be readable that way.
92
+ - The deck keeps its own version history, and you may READ it: \`castle-web list-versions\` shows the versions newest first, and \`castle-web show-version <id>\` shows what one changed, as diffs of just those files. Use them to answer "what changed" or to ground a claim about recent work. You NEVER run \`save-version\` -- you did not make the changes, so a version of yours would not correspond to a unit of work -- and you run \`restore-version\` only when the user's own words ask to put the whole deck back to an earlier state ("go back", "revert it", "undo all that"): that decision is theirs, and they have made it. Never restore on your own judgment, because a fix looks wrong, or on "that looks worse" alone; bringing back or undoing one thing inside newer work ("put the leaderboard back", "undo that color") is a targeted fix, as a task, since a restore would take out the rest. While any task is running, do not restore: its edits would land on top of the old version, so say it has to wait until they finish, or offer to stop them first. To restore, read \`list-versions\` (and \`show-version\` where it helps) for the version that matches what they described; when more than one could match, ask which, naming each as a choice, instead of guessing. Then run \`castle-web restore-version <id>\` yourself -- never with \`--force\`, never through a task -- and say which version you restored and which later changes it took out of the deck (they stay in the version history, so the restore can itself be undone). If it refuses or restores nothing (unsaved changes, tasks still running, already at that version), tell them what it said rather than forcing it. No task you spawn may ever revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit or starter content -- a fix is always a targeted edit, and every task prompt you write has to be readable that way.
79
93
 
80
94
  Asking with options (the \`\`\`ask block). When you need the user to settle a few choices at once, emit ONE fenced block tagged \`ask\` containing JSON -- it renders inline in the chat as grouped options they tap and submit together (far better than stacking questions they can only half-answer). Reach for it to pin a direction when their ask is vague ("make me a game" -> ask what kind), NOT to interrogate.
81
95
 
@@ -165,8 +179,8 @@ Promotion. Finished tasks leave notes worth keeping, listed above with the id of
165
179
 
166
180
  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.`;
167
181
  }
168
- function routerRules(plan, playtest, askCalls) {
169
- const base = baseRouterRules(playtest);
182
+ function routerRules(plan, playtest, askCalls, playtestPref) {
183
+ const base = baseRouterRules(playtest, playtestPref);
170
184
  return plan ? `${base}\n\n${planRules(askCalls)}` : base;
171
185
  }
172
186
  function renderTranscriptLine(m) {
@@ -292,6 +306,17 @@ const LABELED_TEXT = /^([^\s:]+)\s*:\s*(.+)$/;
292
306
  // only a parenthetical that says `from:` or names a source is an annotation.
293
307
  // Dash and quote glyphs vary with whatever produced the line, so both are.
294
308
  const SOURCE_SUFFIX = /\s*\((from:)?\s*([^()]*?)\s*\)\s*$/i;
309
+ // Tried only when SOURCE_SUFFIX fails: a quote can itself hold parentheses --
310
+ // "(keep the temp ending buttons)" in seal deck 2Nb2qScDj6IS -- which
311
+ // SOURCE_SUFFIX cannot read past, and the verbatim decision was filed as a
312
+ // proposal. Each reads one kind of quoted run whole, the other kind staying a
313
+ // plain character, since a single quote inside a double-quoted run is usually
314
+ // an apostrophe. Their alternations are disjoint so a miss cannot backtrack
315
+ // exponentially.
316
+ const QUOTED_PAREN_SOURCE_SUFFIXES = [
317
+ /\s*\((from:)?\s*((?:["“”][^"“”]*["“”]|[^()"“”])*)\s*\)\s*$/i,
318
+ /\s*\((from:)?\s*((?:['‘’][^'‘’]*['‘’]|[^()'‘’])*)\s*\)\s*$/i,
319
+ ];
295
320
  // The same annotation with the brackets left off, which the model does now and
296
321
  // then (measured 26-08-15: 1 of 10 taste ops in a t1 run, quote and task id
297
322
  // both exact). A quote is REQUIRED in this form -- a bare `-- user` at the end
@@ -326,7 +351,9 @@ const TRAILING_QUOTE = new RegExp(`\\s*(?:[;,]\\s*)?(?:(?:--+|[–—])\\s*)?(${
326
351
  // treated as unsourced. So is a quoteless one -- a citation nobody can check is
327
352
  // the thing this grammar exists to stop being enough.
328
353
  function takeSource(text) {
329
- const match = SOURCE_SUFFIX.exec(text);
354
+ const match = SOURCE_SUFFIX.exec(text) ??
355
+ QUOTED_PAREN_SOURCE_SUFFIXES.map((suffix) => suffix.exec(text)).find(Boolean) ??
356
+ null;
330
357
  const bare = match ? null : BARE_SOURCE.exec(text);
331
358
  const annotation = match ?? bare;
332
359
  if (!annotation) {
@@ -501,7 +528,7 @@ function sourceLine(label, source, text) {
501
528
  function isTasteAdd(op) {
502
529
  return !op.remove && (op.verb === "decide" || op.verb === "tried");
503
530
  }
504
- function applyOne(sections, op, notices, sources) {
531
+ function applyOne(sections, op, notices, sources, retiredOpen) {
505
532
  // The one transform in the whole write path: taste the router cannot source
506
533
  // becomes a question instead of a decision. It is asked rather than dropped
507
534
  // -- the observation may well be right, it just isn't the router's to settle.
@@ -512,6 +539,10 @@ function applyOne(sections, op, notices, sources) {
512
539
  const section = sections.find((s) => s.key === key);
513
540
  const at = labelAt(section, op.label);
514
541
  if (!section || at < 0) {
542
+ // A decide+ retires its label's open question, and the router closes the
543
+ // same question with an open- in that fence more often than not.
544
+ if (op.verb === "open" && retiredOpen.has(op.label.toLowerCase()))
545
+ return false;
515
546
  notices.push(`\`${op.verb}- ${op.label}\` matched no line in ${PLAN_SECTION_HEADINGS[key]}`);
516
547
  return false;
517
548
  }
@@ -523,24 +554,36 @@ function applyOne(sections, op, notices, sources) {
523
554
  : `- ${op.label}: ${op.text}${routed ? " (proposed -- confirm?)" : ""}`;
524
555
  const section = sectionFor(sections, key);
525
556
  const at = labelAt(section, op.label);
557
+ let changed = false;
526
558
  if (at >= 0) {
527
- if (section.lines[at].trim() === line)
528
- return false;
529
- section.lines[at] = line;
559
+ if (section.lines[at].trim() !== line) {
560
+ section.lines[at] = line;
561
+ changed = true;
562
+ }
530
563
  }
531
564
  else {
532
565
  let end = section.lines.length;
533
566
  while (end > 0 && !section.lines[end - 1].trim())
534
567
  end -= 1;
535
568
  section.lines.splice(end, 0, line);
569
+ changed = true;
570
+ }
571
+ if (op.verb === "decide" && !routed) {
572
+ const open = sections.find((s) => s.key === "open questions");
573
+ const openAt = labelAt(open, op.label);
574
+ if (open && openAt >= 0) {
575
+ open.lines.splice(openAt, 1);
576
+ retiredOpen.add(op.label.toLowerCase());
577
+ changed = true;
578
+ }
536
579
  }
537
- if (routed) {
580
+ if (routed && changed) {
538
581
  const why = op.source?.quote
539
582
  ? `quoted words that are not in ${op.source.kind === "user" ? "anything the user said" : `anything task ${op.source.id} reported`}`
540
583
  : "carried no quote of its source";
541
584
  notices.push(`\`${op.verb}+ ${op.label}\` ${why}, so it is an open question now, not a decision -- promote it with a verbatim quote once you can point at one.`);
542
585
  }
543
- return true;
586
+ return changed;
544
587
  }
545
588
  // Re-emit the file from its sections: headings in order, one blank line before
546
589
  // each, no trailing whitespace. Only lines an op touched differ from what came
@@ -568,11 +611,12 @@ export function applyPlanOps(fileText, ops, sources) {
568
611
  const notices = [];
569
612
  const identity = [];
570
613
  const closed = [];
614
+ const retiredOpen = new Set();
571
615
  let applied = 0;
572
616
  for (const op of ops) {
573
617
  if (op.verb === "identity")
574
618
  identity.push(`- ${op.text}`);
575
- else if (applyOne(sections, op, notices, sources)) {
619
+ else if (applyOne(sections, op, notices, sources, retiredOpen)) {
576
620
  applied += 1;
577
621
  if (op.verb === "now" && op.remove)
578
622
  closed.push(op.label);
@@ -839,6 +883,11 @@ function renderTasks(tasks, showItems) {
839
883
  // not included" and burns its first turns hunting for CLAUDE.md. Exported so
840
884
  // the platform block (platformDoc.ts) can keep the sentence after itself.
841
885
  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.).";
886
+ // "What the user saw" is load-bearing: most router stops land 1-3 s after the
887
+ // same reply spawned the task, so the user says "you didn't start a task", and
888
+ // Muse agreed with them until told how it looked from their side (memo
889
+ // 26-09-25-20-55: 7/27 -> 17/27 true answers).
890
+ export const STOPPED_TASKS_HEADER = "Tasks you stopped with castle-stop. They started and you cancelled them; none finished. What the user saw: the task appeared on their board and then vanished. So if the user says a task never started, or asks where it went, say plainly that you stopped it (not that it never started), then re-send it if they still want it";
842
891
  export function buildRouterPromptParts(opts) {
843
892
  // Making the ABSENCE explicit, not just omitting the section, matters: a
844
893
  // router on a bare/greenfield deck otherwise has no way to tell "no docs
@@ -870,6 +919,14 @@ export function buildRouterPromptParts(opts) {
870
919
  const paramsWrites = opts.paramsWrites?.length
871
920
  ? `\n\n== parameters panel ==\nThe user set these from the Parameters panel since your last turn:\n${opts.paramsWrites.map((slot) => `- ${slot}`).join("\n")}`
872
921
  : "";
922
+ const stopped = opts.stopped?.length
923
+ ? `\n\n${STOPPED_TASKS_HEADER}:\n${opts.stopped
924
+ .map((stop) => {
925
+ const when = stop.repliesAgo === 1 ? "in your last reply" : `${stop.repliesAgo} replies ago`;
926
+ return `- "${stop.title}" (${stop.id}): you started it, then stopped it yourself at ${stop.progress}% ${when}. Not finished, not running.`;
927
+ })
928
+ .join("\n")}`
929
+ : "";
873
930
  // Two parts, split for prompt caching. `system` holds what is the same from
874
931
  // one turn to the next within a serve -- the rules, the deck identity and
875
932
  // the file tree -- and is sent as system text, which is the prefix the
@@ -877,7 +934,7 @@ export function buildRouterPromptParts(opts) {
877
934
  // does not. `user` holds what changes every turn: the transcript, the plan,
878
935
  // the board and this instruction.
879
936
  return {
880
- system: `${routerRules(opts.plan !== undefined, opts.playtest === true, opts.askCalls === true)}
937
+ system: `${routerRules(opts.plan !== undefined, opts.playtest === true, opts.askCalls === true, opts.playtestPref)}
881
938
 
882
939
  == deck ==
883
940
  ${opts.deckLabel}${quickReference}${editorTabs}${kits}${deckFiles}`,
@@ -885,7 +942,7 @@ ${opts.deckLabel}${quickReference}${editorTabs}${kits}${deckFiles}`,
885
942
  ${renderTranscript(opts.messages)}${plan}
886
943
 
887
944
  == background tasks ==
888
- ${renderTasks(opts.tasks, opts.plan !== undefined)}${paramsWrites}
945
+ ${renderTasks(opts.tasks, opts.plan !== undefined)}${stopped}${paramsWrites}
889
946
 
890
947
  == now ==
891
948
  ${opts.instruction}
@@ -934,6 +991,7 @@ export function userTurnInstruction(opts) {
934
991
  return parts.join("\n\n");
935
992
  }
936
993
  export function buildTaskPrompt(opts) {
994
+ const save = taskSaveWording(opts.git === true);
937
995
  const deps = opts.depsSummary
938
996
  ? `\n\nThis task waited on earlier tasks:\n${opts.depsSummary}\n`
939
997
  : "";
@@ -972,8 +1030,8 @@ export function buildTaskPrompt(opts) {
972
1030
  // -- blind whole-file rewrites made parallel agents clobber each other's
973
1031
  // edits. Read-then-edit is slower but safe; that is the right tradeoff.)
974
1032
  const wrapUpList = opts.plan
975
- ? "the 90-progress write, the `castle-web save-version` for your paths, writing the notes file, and the handoff lines"
976
- : "the 90-progress write, the `castle-web save-version` for your paths, and writing the notes file";
1033
+ ? `the 90-progress write, the \`castle-web ${save.command}\` for your paths, writing the notes file, and the handoff lines`
1034
+ : `the 90-progress write, the \`castle-web ${save.command}\` for your paths, and writing the notes file`;
977
1035
  const wrapUp = `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine ${wrapUpList} into a single shell command (\`;\`-separated so the notes land even if an earlier part hiccups). Then stop -- no extra turns after it.`;
978
1036
  return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions. Do not reload the served deck -- the person applies your changes when they are ready. \`npm run restart\` exists, but it is HIGHLY flow breaking: it reloads every panel they have open, including the one they are working in. Use it only when a change clearly requires restarting their whole experience.${quickReference}${layout}
979
1037
 
@@ -984,18 +1042,18 @@ ${opts.prompt}${deps}${siblings}${planSlice}
984
1042
  Operating rules:
985
1043
  - 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.
986
1044
  - 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.
987
- - 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.
1045
+ - 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.${opts.playtest ? `\n${PLAYTEST_TASK_UNDRIVEN_RULE}` : ""}
988
1046
  - The moment implementation is complete and you switch to verifying, write 90 to the progress file -- verification time must not read as stalled progress.
989
1047
  - Do this one task completely, then stop. Do not expand scope.
990
1048
  - A fix that comes down to choosing a new number for a value already in the code is a tune, and a tune is a guess the user will keep adjusting. Make that value a key in the file's \`PARAMS\` object as part of the same edit -- the new value as its default, read through \`PARAMS.key\` at the use site, a \`PARAMS_META\` range where one is obvious -- so it reaches the Parameters panel and your notes can link it. Move only the value you tuned, not the file's other constants, and only a value the whole deck shares: a setting each placed thing carries for itself, so two of them can differ, stays where the deck's guide puts it and never goes in \`PARAMS\`. A number the user stated goes in the same way, set exactly as they said it.
991
1049
  - If the task is to SHOW HOW something is done or to give an example, answer it -- in your streamed output and notes, with a standalone snippet if that helps -- and do NOT insert a demo behavior, blueprint, or actor into their scene; that only happens when the user asked for it in their game. Anything you did add to a scene must be named in your notes by file path and by the actor or blueprint it attached to, so they can find it and take it out.${planRules}
992
- - 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.
1050
+ ${save.rule}
993
1051
  - Overlap with the other agents working in this deck is fine and expected -- do not try to avoid it or wait for them. Saving only your own paths is all that is asked of you; nothing anyone has written is lost by your save.
994
1052
  - NEVER run \`restore-version\`. Going back to an earlier version is the user's decision alone -- not yours, not even to undo your own work. If your change is wrong, fix it forward.
995
1053
  - The deck's CLI is \`castle-web <command>\`, run in this directory. The commands that are yours:
996
1054
  - \`list-versions [version]\` -- the deck's version history, newest first (a version argument lists from there).
997
1055
  - \`show-version <version>\` -- what one version changed, as diffs of just those files. Reading history is free; use it when you need to know what recent work actually did.
998
- - \`save-version -m "<message>" <paths...>\` -- as above: your own paths, named explicitly, once at the end.
1056
+ - ${save.listing}
999
1057
  - \`install\` -- npm install for the deck, after you add a dependency to \`package.json\`.
1000
1058
  - \`fork-import-file <imports/...>\` and \`revert-import-file <imports/...>\` -- take or drop this deck's own version of one imported file (see below).
1001
1059
  - \`screenshot [--out FILE]\` -- one frame of the running deck. The verification rule above still holds: rarely worth the time it costs the user.
@@ -1008,7 +1066,7 @@ Operating rules:
1008
1066
  - A forked file exists on disk TWICE, and reading or grepping finds both copies. \`forks/<alias>/<path>\` is the live one -- edit that one. \`imports/<alias>/<path>\` is the version the fork was taken from; it is what the deck used to run, not what it runs now, and writing to it just fails.
1009
1067
  - Other task agents may be editing this same deck IN PARALLEL. When you change an existing file, READ it first and make a targeted edit to just the part you need -- never overwrite a whole file you have not read. A blind full-file rewrite clobbers other agents' in-flight changes. Being a bit slower and careful here is the right tradeoff.
1010
1068
  - NEVER revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit, starter, or imported content, and never delete or rewrite a whole scene as a way to diagnose a problem -- that file IS the person's game, and a rewrite destroys work no one asked you to touch. A brief that asks you to investigate, diagnose, or explain is READ-ONLY: report what you found and change nothing unless the user asked for a fix.
1011
- - Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, save a version first so they can restore: \`castle-web save-version -m "<what is about to change>" <those paths>\`. That is on top of the end-of-task version below, not instead of it.
1069
+ ${save.before}
1012
1070
  - How the code should read: decks get opened by strangers copying the pattern, so write for a first-time reader. Name things in words -- \`connection\`, not \`conn\`; \`runtime\`, not \`rt\`. A name that needs a comment to decode is the wrong name.
1013
1071
  - Order a file: data shapes first, then classes, then the functions over that data, so the reader meets the shape before the code that moves it.
1014
1072
  - Comments say what a thing IS and how the system works, declaratively. Not the case for a choice, not what the next line does -- and nothing at all when the code already says it.
@@ -1030,7 +1088,28 @@ phase: wiring the paddle to touch
1030
1088
  - 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.
1031
1089
  - Your final message -- the text after your wrap-up call -- is shown to the user under those notes once the task ends. It is the record of what you did for someone who did not watch the stream, so make it a short plain account: what changed and where (files as tappable links, the same forms as above), the mechanism you chose and why, and any call you made where the brief left a choice. A few sentences or a few short bullets. No signal block, no list of the steps you ran, and do not restate the notes.${wrapUp}
1032
1090
  - If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
1033
- - 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.)`;
1091
+ - Never touch files under .castle/ other than ${opts.plan ? "those three paths" : "those two paths"}. ${save.store}`;
1092
+ }
1093
+ // How a task agent records its work: a version in the deck's own store, or a
1094
+ // commit when the deck is on git. The version wording is the prompt's original
1095
+ // text, unchanged.
1096
+ function taskSaveWording(git) {
1097
+ if (!git) {
1098
+ return {
1099
+ command: "save-version",
1100
+ rule: '- 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.',
1101
+ listing: '`save-version -m "<message>" <paths...>` -- as above: your own paths, named explicitly, once at the end.',
1102
+ before: '- Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, save a version first so they can restore: `castle-web save-version -m "<what is about to change>" <those paths>`. That is on top of the end-of-task version below, not instead of it.',
1103
+ store: "(The version store lives there too, but you never edit it by hand -- `castle-web save-version` writes it for you.)",
1104
+ };
1105
+ }
1106
+ return {
1107
+ command: "commit",
1108
+ rule: '- COMMIT when your change is done, so the user can see and undo it: `castle-web commit --reason task -m "<short description of what you changed>" <each path you touched>`. Name those paths explicitly -- a bare `commit` with no paths records the WHOLE deck, including files a sibling agent is still working on. One commit for the whole task, at the end; not one per file. It is pushed to the deck\'s git remote for you: never run `git commit`, `git push`, `git reset`, `git rebase` or `git checkout` yourself.',
1109
+ listing: '`commit --reason task -m "<message>" <paths...>` -- as above: your own paths, named explicitly, once at the end.',
1110
+ before: '- Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, commit them first so they can restore: `castle-web commit --reason task -m "<what is about to change>" <those paths>`. That is on top of the end-of-task commit below, not instead of it.',
1111
+ store: "(The deck's history is git, in .git -- you never edit it by hand; `castle-web commit` writes it for you.)",
1112
+ };
1034
1113
  }
1035
1114
  // Appended to claude task agents' system prompt (portable replacement for the
1036
1115
  // machine-specific /goal slash command): commit to autonomous completion.
package/dist/agent.d.ts CHANGED
@@ -20,6 +20,11 @@ type SettingsWarnings = Partial<Record<OpenrouterSlugKey, {
20
20
  message: string;
21
21
  suggestion?: string;
22
22
  }>>;
23
+ export declare function taskPlaytestFor(deckDir: string): {
24
+ steering: boolean;
25
+ tool: boolean;
26
+ };
27
+ export declare function playtestToolArgs(tool: boolean, deckDir: string, taskId: string | undefined): string[];
23
28
  type TaskStatus = 'waiting' | 'running' | 'blocked' | 'done' | 'failed' | 'interrupted';
24
29
  interface TaskUsage {
25
30
  input?: number;
@@ -36,6 +41,10 @@ interface TaskRecord {
36
41
  prompt: string;
37
42
  after: string[];
38
43
  item?: string;
44
+ playtest?: {
45
+ steering: boolean;
46
+ tool: boolean;
47
+ };
39
48
  status: TaskStatus;
40
49
  progress: number;
41
50
  notes: string;
@@ -70,6 +79,9 @@ interface TaskRecord {
70
79
  usage?: TaskUsage;
71
80
  modelUsage?: Record<string, TaskModelUsage>;
72
81
  }
82
+ export declare function playtestEnabled(deckDir: string): boolean;
83
+ export declare function playtestPrefFor(deckDir: string): 'on' | 'off' | undefined;
84
+ export declare function setPlaytestPref(deckDir: string, value: 'on' | 'off'): boolean;
73
85
  export declare function askCallsEnabled(deckDir: string): boolean;
74
86
  export interface DepsState {
75
87
  kind: 'ready' | 'waiting' | 'blocked';