castle-web-cli 0.4.10 → 0.4.12

package/dist/agent-prompts.d.ts

@@ -0,0 +1,31 @@
+export interface PromptMessage {
+    role: 'user' | 'assistant';
+    text: string;
+}
+export interface PromptTask {
+    id: string;
+    title: string;
+    status: string;
+    progress: number;
+    notes: string;
+}
+export declare function buildRouterPrompt(opts: {
+    deckLabel: string;
+    messages: PromptMessage[];
+    tasks: PromptTask[];
+    instruction: string;
+}): string;
+export declare function userTurnInstruction(opts: {
+    text: string;
+    interruptedDraft?: string;
+    attachments?: string[];
+}): string;
+export declare function buildTaskPrompt(opts: {
+    deckLabel: string;
+    taskId: string;
+    title: string;
+    prompt: string;
+    progressPath: string;
+    notesPath: string;
+    depsSummary?: string;
+}): string;

package/dist/agent-prompts.js

@@ -0,0 +1,100 @@
+// Prompt builders for the agent panel: the conversational "router" that chats
+// with the user and spawns background tasks, and the task agents that do the
+// actual deck edits. Kept separate from agent.ts so the orchestration code
+// stays readable.
+// How many trailing conversation messages get replayed into each router call.
+// Router calls are stateless (a fresh cursor-agent print run each time) so the
+// transcript is the only memory.
+const TRANSCRIPT_LIMIT = 40;
+const 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.
+
+Hard rules:
+- 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.
+- 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.
+- Decompose with judgment -- parallel tasks are powerful but add overhead. Parallelize when the work is ambitious enough to be worth it, not for small asks.
+- For a new game (or a substantial new part of one): make sure the FIRST task delivers a small coherent playable demo on its own, so the user is not waiting on several tasks before playing anything. Then fan out in parallel to take it further.
+- Work on ART and MECHANICS simultaneously as separate tasks, with a later task (\`after:\` both) that combines them.
+- Parallel tasks must each be separately testable and must not step on each other's files.
+- To spawn a background task, include a fenced block in your reply:
+
+\`\`\`castle-task
+short imperative title on the first line
+after: comma-separated titles or ids this task must wait for (optional line)
+supersedes: comma-separated titles or ids this task replaces (optional line)
+Then a detailed, self-contained prompt for the implementing agent:
+what to build or fix, which files matter, and what "done" looks like.
+\`\`\`
+
+- Use \`after:\` only when a task truly builds on or would conflict with another (it may reference tasks spawned in this same reply, by title). Independent tasks must NOT wait on each other.
+- Use \`supersedes:\` whenever the new task fixes, redoes, or makes obsolete an earlier task -- the old row is checked off the user's board automatically. Keep the board meaning "what to look at right now".
+- Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task rather than reopening the old one.
+- Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
+
+Conversation style:
+- As short and focused as possible -- a few tight sentences. Concrete, energetic. Ask at most one question per reply.
+- Do not narrate before tool calls ("Checking the deck...") -- that reads as noise in the chat. Read silently, then give one reply after your final tool call.
+- The user sees a live task board above the chat -- never re-announce task status yourself.
+- The user playtests in the pane beside this chat; finished work shows up there after a reload.`;
+function renderTranscript(messages) {
+    const recent = messages.slice(-TRANSCRIPT_LIMIT);
+    if (recent.length === 0)
+        return '(no conversation yet)';
+    return recent
+        .map((m) => `${m.role === 'user' ? 'user' : 'you'}: ${m.text}`)
+        .join('\n\n');
+}
+function renderTasks(tasks) {
+    if (tasks.length === 0)
+        return '(none yet)';
+    return tasks
+        .map((t) => {
+        const notes = t.notes.trim() ? ` -- notes: ${t.notes.trim()}` : '';
+        return `- [${t.status} ${t.progress}%] ${t.title} (${t.id})${notes}`;
+    })
+        .join('\n');
+}
+export function buildRouterPrompt(opts) {
+    return `${ROUTER_RULES}
+
+== deck ==
+${opts.deckLabel}
+
+== background tasks ==
+${renderTasks(opts.tasks)}
+
+== conversation so far ==
+${renderTranscript(opts.messages)}
+
+== now ==
+${opts.instruction}
+
+Reply now, as "you" in the conversation. Plain reply text only -- no role prefix.`;
+}
+export function userTurnInstruction(opts) {
+    const parts = [];
+    if (opts.interruptedDraft?.trim()) {
+        parts.push(`Your previous reply was interrupted mid-stream by the user's new message. Its draft so far (already shown to the user; NO tasks were spawned from it):\n\n${opts.interruptedDraft.trim()}\n\nContinue that line of work AND address the new message -- do both in this one reply, spawning whatever tasks are needed for either.`);
+    }
+    parts.push(`The user just said:\n\n${opts.text}`);
+    if (opts.attachments && opts.attachments.length > 0) {
+        parts.push(`The user attached image file(s), saved in the deck at: ${opts.attachments.join(', ')}. Open them with your read tool and take them into account; pass the paths along to task agents that need them.`);
+    }
+    return parts.join('\n\n');
+}
+export function buildTaskPrompt(opts) {
+    const deps = opts.depsSummary
+        ? `\n\nThis task waited on earlier tasks:\n${opts.depsSummary}\n`
+        : '';
+    return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Read the deck's CLAUDE.md / AGENTS.md first and follow its workflow (including reloading the served deck after changes, e.g. \`npm run restart\`).
+
+Your task (id ${opts.taskId}): ${opts.title}
+
+${opts.prompt}${deps}
+
+Operating rules:
+- Do this one task completely, then stop. Do not expand scope.
+- Update your progress VERY frequently: write a bare integer 0-100 to ${opts.progressPath} (e.g. \`echo 30 > ${opts.progressPath}\`) every time you advance -- at least every 10 points, or every 20 for properly small tasks. Start near 10, write 90 just before wrapping up. Never let it sit stale while you work.
+- Before finishing, write ${opts.notesPath}: a SHORT test guide for the user -- 2-4 brief sentences. Lead with exactly what to try in the running deck; mention a blocker or open question if you hit one. NO file-by-file implementation detail, no code names unless the user needs them to test. The user reads this verbatim when checking your work off.
+- If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
+- Never touch files under .castle/ other than those two paths.`;
+}

package/dist/agent.d.ts

@@ -0,0 +1,17 @@
+import * as http from 'http';
+import { Duplex } from 'stream';
+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';
+export interface AgentServer {
+    /** Attach the agent WebSocket if the upgrade targets the agent path. */
+    handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): boolean;
+    /** Serve attachment images. Returns true if it handled the request. */
+    handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse, reqPath: string): boolean;
+    shutdown(): void;
+}
+export declare function createAgentServer(opts: {
+    deckDir: string;
+    deckLabel: string;
+}): AgentServer;