castle-web-cli 0.4.76 → 0.4.78

package/dist/agent-prompts.d.ts

@@ -10,6 +10,13 @@ export interface PromptTask {
     progress: number;
     notes: string;
     files?: string[];
+    error?: string;
+    blockedBy?: string[];
+}
+export interface PromptSibling {
+    title: string;
+    status: string;
+    files?: string[];
 }
 export declare function buildRouterPrompt(opts: {
     deckLabel: string;
@@ -34,5 +41,7 @@ export declare function buildTaskPrompt(opts: {
     depsSummary?: string;
     backend?: "cursor" | "claude";
     deckTree?: string;
+    quickReference?: string;
+    siblings?: PromptSibling[];
 }): string;
 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.";

package/dist/agent-prompts.js

@@ -15,9 +15,9 @@ Hard rules:
 - 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.
 - Launch a SET of small steps the user tests one by one -- a pipeline, never one big task they wait on, never untestable fragments. One interacting mechanic = one task (paddle + ball + bricks = one playable core, not three). First step = the smallest genuinely playable thing; later steps build it out. Match breadth to ambition ("basic" = a few steps; "go wild" = many). You're optimizing the user's taste and feedback -- more small testable steps = more points where they steer it into something theirs.
 - The whole goal: every piece of work TESTABLE in actual gameplay ASAP. Start every task as early as possible and run them in PARALLEL. Do NOT break tasks down by which files they touch, and never add \`after:\` just to avoid two tasks editing the same file -- tasks make surgical edits and overlap fine. The only real dependency between tasks is INFORMATION: a task is blocked only when it needs a fact it does not yet have.
-- Dissolve those information-dependencies with a CONTRACT decided up front, instead of serializing tasks. Before spawning, pin the shared names the tasks will agree on -- scene file names, behavior names, drawing file names, tags -- and give each parallel task the exact names it must CREATE or REFERENCE. 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 a drawing name like drawings/ship 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.
+- 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.pxart\` 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.pxart\` 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.
 - Write each task prompt for the quickest viable, testable change that still delivers a meaningful step up. Dive deep only if the user asked.
-- Real, editable assets: drawing files under \`drawings/\` for game objects, characters, and scenery as real actors; data-driven UI (health/score/HUD) and effects stay code. The logic/scene task references the REAL drawing names immediately (e.g. \`drawings/paddle\`) -- a not-yet-created drawing auto-renders as a plain block, so the game is playable instantly AND the real art appears the moment the drawing task writes that file, with NO scene change. Ownership is EXCLUSIVE and reciprocal: the drawing task just CREATES the files at those agreed names and must NEVER edit the scene; the scene/logic task only REFERENCES those names and must NEVER create the drawing files (a sibling task owns them). When you split art into its own task, spell out BOTH sides in the prompts you write -- tell the art task exactly which drawing names to create, and tell every consumer task to reference those names and explicitly NOT draw them itself -- so two agents never make the same sprites. (The deck's CLAUDE.md / AGENTS.md gives the deck's drawing format, file extension, and how to make art.) Never say "greybox" or other dev jargon to the user.
+- Real, editable assets: drawing files under \`drawings/\` for game objects, characters, and scenery as real actors; data-driven UI (health/score/HUD) and effects stay code. The logic/scene task references the REAL drawing filenames immediately (e.g. \`drawings/paddle.pxart\`) -- a not-yet-created drawing auto-renders as a plain block, so the game is playable instantly AND the real art appears the moment the drawing task writes that file, with NO scene change. Ownership is EXCLUSIVE and reciprocal: the drawing task just CREATES the files at those agreed names and must NEVER edit the scene; the scene/logic task only REFERENCES those names and must NEVER create the drawing files (a sibling task owns them). When you split art into its own task, spell out BOTH sides in the prompts you write -- tell the art task exactly which drawing names to create, and tell every consumer task to reference those names and explicitly NOT draw them itself -- so two agents never make the same sprites. (The deck's CLAUDE.md / AGENTS.md gives the deck's drawing format, file extension, and how to make art.) Never say "greybox" or other dev jargon to the user.
 - To spawn a background task, include a fenced block in your reply:
 
 \`\`\`castle-task
@@ -41,8 +41,9 @@ comma-separated active-task titles or ids, or \`all\`
 \`\`\`
 
 - \`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.
-- \`castle-stop\` stops AND removes ACTIVE rows (running/waiting) -- 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.
-- 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 or waiting. Keep the board meaning "what to look at right now".
+- \`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.
+- 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".
+- 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.
 - 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.
 - Never claim the board is cleared without actually emitting the fence.
 - 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.
@@ -88,7 +89,11 @@ function renderTasks(tasks) {
         .map((t) => {
         const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : "";
         const files = t.files && t.files.length > 0 ? ` -- files: ${t.files.join(", ")}` : "";
-        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}${files}`;
+        const error = t.error ? ` -- error: ${t.error}` : "";
+        const blockedBy = t.blockedBy && t.blockedBy.length > 0
+            ? ` -- blocked by: ${t.blockedBy.join(", ")}`
+            : "";
+        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}${files}${error}${blockedBy}`;
     })
         .join("\n");
 }
@@ -99,13 +104,17 @@ export function buildRouterPrompt(opts) {
     const deckFiles = opts.deckTree?.trim()
         ? `\n\n== deck files ==\n${opts.deckTree.trim()}`
         : "";
+    // Section order is stable-to-volatile for prompt caching: rules + deck
+    // identity never change within a serve, the transcript is append-only, and
+    // the churning state (file tree, task board, instruction) rides at the tail
+    // so a task creating a file doesn't invalidate the cached transcript prefix.
     return `${ROUTER_RULES}
 
 == deck ==
-${opts.deckLabel}${quickReference}${deckFiles}
+${opts.deckLabel}${quickReference}
 
 == conversation so far ==
-${renderTranscript(opts.messages)}
+${renderTranscript(opts.messages)}${deckFiles}
 
 == background tasks ==
 ${renderTasks(opts.tasks)}
@@ -138,6 +147,15 @@ export function buildTaskPrompt(opts) {
     const deps = opts.depsSummary
         ? `\n\nThis task waited on earlier tasks:\n${opts.depsSummary}\n`
         : "";
+    const siblingRows = (opts.siblings ?? [])
+        .map((s) => `- [${s.status}] ${s.title}${s.files && s.files.length > 0 ? ` -- files: ${s.files.join(", ")}` : ""}`)
+        .join("\n");
+    const siblings = siblingRows
+        ? `\n\nOther tasks on this deck's board (snapshot at your start):\n${siblingRows}\nRunning and waiting rows are sibling agents working in this same directory. If a sibling plainly owns something your prompt only references (art, a scene, a behavior), leave it to them -- create only what YOUR prompt says to create. Finished rows' file lists show where recent work landed.\n`
+        : "";
+    const quickReference = opts.quickReference?.trim()
+        ? `\n\nHow this deck works (from its docs -- read the full CLAUDE.md / AGENTS.md only when you need detail beyond this):\n\n${opts.quickReference.trim()}\n`
+        : "";
     const layout = opts.deckTree?.trim()
         ? `\n\nDeck files (snapshot at task start; parallel sibling tasks may create files named in your prompt that are absent here):\n\n${opts.deckTree.trim()}\n`
         : "";
@@ -151,11 +169,11 @@ export function buildTaskPrompt(opts) {
     const wrapUp = opts.backend === "claude"
         ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the final \`npm run restart\`, and writing the notes file into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
         : "";
-    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, and reload the served deck after changes (\`npm run restart\`).${layout}
+    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, and reload the served deck after changes (\`npm run restart\`).${quickReference}${layout}
 
 Your task (id ${opts.taskId}): ${opts.title}
 
-${opts.prompt}${deps}
+${opts.prompt}${deps}${siblings}
 
 Operating rules:
 - 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.

package/dist/agent.d.ts

@@ -4,6 +4,34 @@ export declare const AGENT_WS_PATH = "/__castle/agent";
 export declare const AGENT_ATTACHMENT_PREFIX = "/__castle/agent/attachments/";
 export type AgentBackend = "cursor" | "claude";
 export type ClaudeModel = "sonnet" | "opus" | "fable";
+type TaskStatus = "waiting" | "running" | "blocked" | "done" | "failed" | "interrupted";
+interface TaskRecord {
+    id: string;
+    title: string;
+    prompt: string;
+    after: string[];
+    status: TaskStatus;
+    progress: number;
+    notes: string;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    pid?: number;
+    originMessageId?: string;
+    files?: string[];
+    resultSummary?: string;
+    avatar?: string;
+    phase?: string;
+    acknowledged?: boolean;
+    rejected?: boolean;
+    blockedBy?: string[];
+}
+export interface DepsState {
+    kind: "ready" | "waiting" | "blocked";
+    blockedBy?: string[];
+}
+export declare function classifyDeps(tasks: Map<string, TaskRecord>, task: TaskRecord): DepsState;
 export interface AgentServer {
     /** Attach the agent WebSocket if the upgrade targets the agent path. */
     handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
@@ -15,3 +43,4 @@ export declare function createAgentServer(opts: {
     deckDir: string;
     deckLabel: string;
 }): AgentServer;
+export {};