@joeyshi12/casper 0.7.2 → 0.8.0

package/README.md

@@ -22,6 +22,9 @@ exactly what it missed.
   calls with their status, input and output.
 - **File browser** for the session's workspace, previewing text, images and PDFs.
   HTML renders as a live page, sandboxed, and either can go fullscreen.
+- **Widgets**: the agent calls a `show_widget` tool over MCP and the result renders
+  inline as a live page. Charts, simulations, animated diagrams. Sandboxed, and they
+  can send a message back.
 - **Observability** for credits spent, context-window usage and turn duration.
 - **PWA** that installs to a home screen and reconnects when the network returns.
 
@@ -53,11 +56,19 @@ systemd is optional. Without it, run `casper` from your own init system, under
 | `casper` | Run the server in the foreground |
 | `casper token` | Print the access token |
 | `casper reset-token [value]` | Set a new token and sign every device out |
-| `casper doctor` | Check kiro-cli, settings, data directory and web app |
+| `casper doctor` | Check kiro-cli, settings, data directory, web app and MCP server |
+| `casper mcp` | Run the widget MCP server on stdio (kiro spawns this for you) |
 | `casper service install` | Run as a systemd user service |
 | `casper service uninstall` | Remove the service, keeping settings and sessions |
 | `casper service status` | Show the service status |
 
+The `casper` agent gets the widget tools automatically. To give them to another
+agent, point it at the same server:
+
+```bash
+kiro-cli mcp add --name casper --agent <agent> --command casper --args mcp
+```
+
 To update, `npm install -g @joeyshi12/casper@latest`. Re-run
 `casper service install` afterwards if you use the service: the unit records
 absolute node and package paths, and both move on upgrade. Your token and sessions

package/dist/agents/casper.json

@@ -1,8 +1,17 @@
 {
   "name": "casper",
   "description": "Casper \u2014 a coding agent for developing from the chat web interface.",
-  "prompt": "You are Casper, an AI coding agent. You help developers build, debug, and understand software directly from a chat-based web interface. Draw on your broad knowledge of programming languages, frameworks, and engineering practices to solve problems pragmatically and get real work done.\n\nCommunication\n- Be concise, direct, and friendly. Prioritize actionable guidance over narrating your work. Match detail to the task: brief for simple things, more context when it helps the user decide.\n- Ground every claim in the codebase, tool results, or reliable sources; never fabricate. State assumptions and label inferences.\n- Prioritize correctness over agreement. If something is wrong or risky, say so plainly and explain why.\n- Format responses in markdown: use backticks for file paths, commands, and code identifiers, and reference files by their project-relative path.\n\nTool use\n- Gather enough context before acting; do not guess file paths, arguments, or APIs. Read the relevant code before changing it.\n- Make independent tool calls in parallel and run dependent ones sequentially. Prefer the most direct tool for the job.\n- Do not re-read a file just to confirm a successful edit.\n\nTask execution\n- Keep working until the user's request is fully resolved before yielding. Resolve the task autonomously with the tools available rather than returning early.\n- Ask the user only when the information you need is genuinely unavailable from the project, or when an action is risky or irreversible.\n\nMaking code changes\n- Fix problems at the root cause; keep changes minimal, focused, and consistent with the existing style. Prefer dependencies and patterns already used in the project.\n- Update related tests, documentation, and call sites that are part of the change; mention unrelated issues rather than fixing them.\n- Do not commit or create branches unless asked. Never overwrite or revert work you did not make.\n\nValidation and safety\n- Verify with the project's own build, test, and lint commands. Never claim validation passed unless you ran it and saw it pass; otherwise report the failing command and the error.\n- Treat destructive or hard-to-reverse actions (data loss, production changes, force pushes) as requiring explicit confirmation. Never expose or hardcode secrets.\n\nFiles and previews\n- Attachments arrive as an \"Attached files:\" line listing absolute paths under ~/.casper/sessions/<id>/uploads. Read them from there; they are outside the project, so never assume a path relative to the working directory.\n- Do not write into ~/.casper. It is Casper's own state directory. Put files you create in the working directory, where the user can see and version them.\n- HTML files render in Casper's preview panel, interactively and fullscreen, with scripts and forms working. A self-contained .html file is therefore a good deliverable for anything visual: a slideshow, a chart, a diagram, a small tool. Images and PDFs preview too.\n- Write that HTML as one file. The preview is sandboxed with an opaque origin, so inline the CSS and JS, and don't reach for localStorage or sessionStorage - they throw there. Keep state in memory for the life of the page. Scripts from a CDN do load.\n- Say where you put a file the user is meant to look at, by path. Previews open from the file browser, so an unmentioned file is one they have to go hunting for.\n\nFinal response\n- Summarize what changed, reference the affected files by path, and state what you verified. Offer a sensible next step as a question rather than doing it unprompted.",
-  "mcpServers": {},
+  "prompt": "You are Casper, an AI coding agent. You help developers build, debug, and understand software directly from a chat-based web interface. Draw on your broad knowledge of programming languages, frameworks, and engineering practices to solve problems pragmatically and get real work done.\n\nCommunication\n- Be concise, direct, and friendly. Prioritize actionable guidance over narrating your work. Match detail to the task: brief for simple things, more context when it helps the user decide.\n- Ground every claim in the codebase, tool results, or reliable sources; never fabricate. State assumptions and label inferences.\n- Prioritize correctness over agreement. If something is wrong or risky, say so plainly and explain why.\n- Format responses in markdown: use backticks for file paths, commands, and code identifiers, and reference files by their project-relative path.\n\nTool use\n- Gather enough context before acting; do not guess file paths, arguments, or APIs. Read the relevant code before changing it.\n- Make independent tool calls in parallel and run dependent ones sequentially. Prefer the most direct tool for the job.\n- Do not re-read a file just to confirm a successful edit.\n\nTask execution\n- Keep working until the user's request is fully resolved before yielding. Resolve the task autonomously with the tools available rather than returning early.\n- Ask the user only when the information you need is genuinely unavailable from the project, or when an action is risky or irreversible.\n\nMaking code changes\n- Fix problems at the root cause; keep changes minimal, focused, and consistent with the existing style. Prefer dependencies and patterns already used in the project.\n- Update related tests, documentation, and call sites that are part of the change; mention unrelated issues rather than fixing them.\n- Do not commit or create branches unless asked. Never overwrite or revert work you did not make.\n\nValidation and safety\n- Verify with the project's own build, test, and lint commands. Never claim validation passed unless you ran it and saw it pass; otherwise report the failing command and the error.\n- Treat destructive or hard-to-reverse actions (data loss, production changes, force pushes) as requiring explicit confirmation. Never expose or hardcode secrets.\n\nFiles and previews\n- Attachments arrive as an \"Attached files:\" line listing absolute paths under ~/.casper/sessions/<id>/uploads. Read them from there; they are outside the project, so never assume a path relative to the working directory.\n- Do not write into ~/.casper. It is Casper's own state directory. Put files you create in the working directory, where the user can see and version them.\n- HTML files render in Casper's preview panel, interactively and fullscreen, with scripts and forms working. A self-contained .html file is therefore a good deliverable for anything visual: a slideshow, a chart, a diagram, a small tool. Images and PDFs preview too.\n- Write that HTML as one file. The preview is sandboxed with an opaque origin, so inline the CSS and JS, and don't reach for localStorage or sessionStorage - they throw there. Keep state in memory for the life of the page. Scripts from a CDN do load.\n- Say where you put a file the user is meant to look at, by path. Previews open from the file browser, so an unmentioned file is one they have to go hunting for.\n\nWidgets\n- Casper renders interactive widgets inline in the conversation. When something is\nclearer shown than described - a chart, a simulation with controls, a diagram - call\nread_me once with the modules you need, then show_widget. read_me carries the design\nrules, so don't guess them, and don't mention that call to the user.\n- show_choice asks the user to pick from a few options, which they tap rather than\ntype. Use it wherever you would otherwise end a message asking which way to go.\n- The widget is the explanation. Don't restate its content in prose afterwards.\n- Widgets aren't saved anywhere. When the user wants something to keep, write an\n.html file instead.\n\nFinal response\n- Summarize what changed, reference the affected files by path, and state what you verified. Offer a sensible next step as a question rather than doing it unprompted.",
+  "mcpServers": {
+    "casper": {
+      "command": "casper",
+      "args": [
+        "mcp"
+      ],
+      "env": {},
+      "timeout": 10000
+    }
+  },
   "tools": [
     "*"
   ],

package/dist/mcp.js

@@ -0,0 +1,412 @@
+// server/src/mcp/server.ts
+import { createInterface } from "node:readline";
+
+// server/src/mcp/guidelines.ts
+var MODULES = ["interactive", "chart", "diagram", "art"];
+var CORE = `# Widgets
+
+A widget is a self-contained HTML fragment rendered inline in the conversation. No
+doctype, html, head or body tag - just content. It is not a file and not a
+deliverable; it is part of what you are saying. Reach for one when a picture
+answers better than a paragraph.
+
+## Structure, in this order
+
+1. A short \`<style>\` block.
+2. The content markup.
+3. A single \`<script>\` at the end.
+
+Order matters. Content renders as it arrives, and scripts run only once the message
+is complete, so a widget whose script sits at the top looks inert until the end.
+
+## Hard rules
+
+- No gradients, drop shadows or blur. They flash while content is patched in.
+- No HTML comments. They cost tokens and buy nothing.
+- Two font weights only: 400 and 500. Never 600 or 700.
+- Sentence case for every label, heading and button. Never Title Case, never ALL CAPS.
+- Never hardcode a colour that has a variable below.
+- Size text in px, 11 to 15 for body and labels, up to 18 for a single heading.
+- Keep the whole widget under 600px tall unless the content genuinely needs more.
+
+## The sandbox
+
+The frame has an opaque origin. localStorage, sessionStorage, cookies and requests
+to Casper all throw or fail. Hold state in a variable for the life of the page.
+
+Libraries load from these hosts only: cdnjs.cloudflare.com, cdn.jsdelivr.net,
+unpkg.com, esm.sh. Anything else is refused by the content security policy, as is
+eval and new Function, so pick libraries that don't rely on them.
+
+## Theme
+
+The background is transparent and the app's own variables are set. Use them:
+
+--color-text-primary, --color-text-secondary
+--color-background-primary, --color-background-secondary
+--color-border
+--color-accent, --color-accent-alt
+--color-teal, --color-green, --color-yellow, --color-orange, --color-red
+--font-body, --font-mono
+
+Read them in script with getComputedStyle(document.documentElement).getPropertyValue.
+
+## Talking back
+
+casper.sendPrompt(text) sends a message as if the user typed it, indistinguishable
+in the transcript from one they wrote. Most widgets need no button at all. Add one
+only when the obvious next step is a question they would otherwise type out by hand,
+and never as decoration or to invite engagement. One at most.`;
+var COLOR = `## Colour
+
+Six accents are available: --color-accent (purple), --color-accent-alt (pink),
+--color-teal, --color-green, --color-yellow, --color-orange, --color-red.
+
+Colour encodes meaning, never sequence. If two series differ only by being
+different series, use one accent at two opacities rather than two hues. Two or
+three hues per widget is the ceiling.
+
+Semantics people already expect: green for success or growth, red for error or
+loss, orange for warning or pending, teal for neutral information, purple for the
+primary subject.
+
+For text on a filled background, use --color-background-primary as the text colour
+rather than black. For a tint, use the accent at 12 to 20 percent opacity with the
+accent itself as the border.`;
+var UI = `## Components
+
+Card: background --color-background-secondary, 1px --color-border, radius 10px,
+padding 12px 14px. No shadow.
+
+Metric: label 11px --color-text-secondary above a 20px 500-weight value. Group
+metrics in a grid with 12px gaps, never a table.
+
+Button: 12px text, background --color-background-secondary, 1px --color-border,
+radius 6px, padding 5px 10px. On hover, move the border to --color-accent. Never
+paint a button in an accent colour unless it is the single primary action.
+
+Input and range: set accent-color to var(--color-accent) and let the browser style
+the rest.
+
+Table: only for genuinely tabular data. 1px --color-border between rows, no
+vertical rules, 12px text, numbers right-aligned in --font-mono.
+
+Rows of key and value: a flex row with the label in --color-text-secondary and the
+value in --font-mono, separated by a border-bottom on all but the last.`;
+var CHARTS = `## Charts
+
+Chart.js from cdn.jsdelivr.net is the default choice. Load it with a script tag
+before your own script; it will have finished loading by the time your script runs,
+so there's no need to poll for it.
+
+Wrap every canvas in a div with position relative and an explicit height, and set
+maintainAspectRatio to false. Without both, the canvas grows without bound.
+
+Turn the built-in legend off (plugins.legend.display false) and write the legend as
+HTML if it's needed - the built-in one ignores the theme.
+
+Grid lines in --color-border at low opacity, ticks in --color-text-secondary, 11px.
+Datasets take an accent colour with borderWidth 2 and no point markers unless
+individual readings matter.
+
+Format numbers so the sign leads: -$5M, never $-5M. Abbreviate above four digits
+(12.4k, 3.1M). Percentages get one decimal at most.
+
+Pick the form from the question: trend over time is a line, comparison across
+categories is a horizontal bar when labels are words, composition is a stacked bar
+rather than a pie unless there are three slices or fewer.`;
+var SVG = `## SVG
+
+Set viewBox and leave width and height off, so the drawing scales to the frame.
+Compute the viewBox from the content bounds and add 8 units of padding on every
+side; anything drawn outside is invisible and reviewers will not see the mistake.
+
+Text width is the usual cause of overflow. At font-size 12 with the body font,
+budget 6.2px per character for lowercase and 7.4px for uppercase, then size boxes
+from the longest label rather than by eye.
+
+Connector paths need fill="none" explicitly. SVG fills paths black by default, so a
+curve without it renders as a filled blob.
+
+Define arrowheads once in defs with a marker whose fill is context-stroke, so the
+head inherits the line colour instead of needing one marker per colour.
+
+Stroke widths: 1.5 for connectors, 2 for emphasis, 1 for gridlines. Never below 1.`;
+var DIAGRAMS = `## Diagrams
+
+Two mistakes account for most bad diagrams. First, arrows that cross boxes they
+have nothing to do with: trace every arrow's straight path and if it passes through
+a box, route it around or move the box. Second, boxes sized by guess rather than by
+the longest label they contain.
+
+Route on the verb, not the noun. "How does a request flow" wants a sequence, "what
+are the parts" wants a structural diagram, "why is it slow" wants an annotated
+before and after.
+
+Budgets: at most four boxes across one tier, at most five words in a label, at most
+three tiers deep. Beyond that, split into two diagrams or drop detail.
+
+Label every arrow that isn't obvious, in 10px --color-text-secondary. An unlabelled
+arrow asserts a relationship without saying which.
+
+Lay out left to right for flow and top to bottom for hierarchy, and keep a single
+consistent gap between tiers.`;
+var ART = `## Illustration
+
+Build from geometry: circles, rounded rectangles, and paths with two or three
+control points. Detail beyond that reads as noise at conversation size.
+
+Use flat fills from the palette with no more than three colours plus a background.
+Depth comes from overlap and size, never from gradients or shadows.
+
+Animate with CSS on transform and opacity only, 0.3s or slower, and only where the
+motion carries meaning. Anything faster or busier is a distraction in a chat.
+
+For anything representational, prefer a diagram with labels. An unlabelled drawing
+of a concept is decoration.`;
+var MODULE_SECTIONS = {
+  interactive: [UI, COLOR],
+  chart: [UI, COLOR, CHARTS],
+  diagram: [COLOR, SVG, DIAGRAMS],
+  art: [COLOR, SVG, ART]
+};
+function getGuidelines(modules) {
+  const parts = [CORE];
+  const seen = /* @__PURE__ */ new Set();
+  for (const mod of modules) {
+    const sections = MODULE_SECTIONS[mod];
+    if (!sections) continue;
+    for (const section of sections) {
+      if (seen.has(section)) continue;
+      seen.add(section);
+      parts.push(section);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+// server/src/mcp/choice.ts
+var MAX_OPTIONS = 6;
+function validateChoice(data) {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return "arguments must be an object.";
+  }
+  const d = data;
+  if (typeof d.question !== "string" || !d.question.trim()) {
+    return "question is required: what you are asking the user to decide.";
+  }
+  if (!Array.isArray(d.options) || d.options.length < 2) {
+    return "at least two options are needed.";
+  }
+  if (d.options.length > MAX_OPTIONS) {
+    return `at most ${MAX_OPTIONS} options; ${d.options.length} is too many to tap through.`;
+  }
+  for (const [i, raw] of d.options.entries()) {
+    if (typeof raw !== "object" || raw === null) return `options[${i}] must be an object.`;
+    const o = raw;
+    if (typeof o.label !== "string" || !o.label.trim()) {
+      return `options[${i}].label is required and must be a short phrase.`;
+    }
+    if (o.prompt !== void 0 && typeof o.prompt !== "string") {
+      return `options[${i}].prompt must be a string when given.`;
+    }
+    if (o.detail !== void 0 && typeof o.detail !== "string") {
+      return `options[${i}].detail must be a string when given.`;
+    }
+  }
+  return null;
+}
+
+// server/src/mcp/protocol.ts
+var DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+var SERVER_NAME = "casper-generative-ui";
+var MAX_WIDGET_CHARS = 256 * 1024;
+var TOOLS = [
+  {
+    name: "read_me",
+    title: "Widget design guidelines",
+    description: "Read the widget design guidelines. Call this once, before your first show_widget call, with the modules relevant to what you are about to build. Do not mention this call to the user.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        modules: {
+          type: "array",
+          items: { type: "string", enum: [...MODULES] },
+          minItems: 1,
+          description: "interactive for controls, sketches and simulations, chart for data, diagram for structure and flow, art for illustration."
+        }
+      },
+      required: ["modules"]
+    }
+  },
+  {
+    name: "show_widget",
+    title: "Show widget",
+    description: "Render an interactive widget inline in the conversation. Pass an HTML fragment: no doctype, html or body tag. Style first, then content, then a single script last. Use this instead of describing something visual in prose.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        i_have_seen_read_me: {
+          type: "boolean",
+          description: "True only if you have already called read_me in this conversation."
+        },
+        title: {
+          type: "string",
+          description: "Short snake_case identifier, e.g. compound_interest."
+        },
+        widget_code: {
+          type: "string",
+          description: "The HTML fragment to render."
+        }
+      },
+      required: ["i_have_seen_read_me", "title", "widget_code"]
+    }
+  },
+  {
+    name: "show_choice",
+    title: "Ask the user to choose",
+    description: "Ask the user to pick from a few options, which they tap instead of typing. Use it wherever you would otherwise end a message asking which of several ways to proceed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        question: { type: "string", description: "What they are deciding." },
+        options: {
+          type: "array",
+          minItems: 2,
+          maxItems: MAX_OPTIONS,
+          items: {
+            type: "object",
+            properties: {
+              label: { type: "string", description: "Short, tappable phrase." },
+              detail: { type: "string", description: "One line of context." },
+              prompt: {
+                type: "string",
+                description: "Message sent when tapped. Defaults to the label."
+              }
+            },
+            required: ["label"]
+          }
+        }
+      },
+      required: ["question", "options"]
+    }
+  }
+];
+function ok(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+function text(body, isError = false) {
+  return { content: [{ type: "text", text: body }], isError };
+}
+function callError(id, message) {
+  return ok(id, text(message, true));
+}
+function asStringArray(value) {
+  return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function handleReadMe(id, args) {
+  const modules = asStringArray(args.modules);
+  const known = modules.filter((m) => MODULES.includes(m));
+  if (known.length === 0) {
+    return callError(id, `Name at least one module: ${MODULES.join(", ")}.`);
+  }
+  return ok(id, text(getGuidelines(known)));
+}
+function handleShowWidget(id, args) {
+  if (args.i_have_seen_read_me !== true) {
+    return callError(id, "Call read_me first, then set i_have_seen_read_me to true.");
+  }
+  const title = typeof args.title === "string" ? args.title.trim() : "";
+  if (!title) return callError(id, "title is required: a short snake_case identifier.");
+  const code = typeof args.widget_code === "string" ? args.widget_code : "";
+  if (!code.trim()) return callError(id, "widget_code is required.");
+  if (code.length > MAX_WIDGET_CHARS) {
+    return callError(
+      id,
+      `widget_code is ${Math.round(code.length / 1024)} KB, over the ${MAX_WIDGET_CHARS / 1024} KB limit. Simplify it.`
+    );
+  }
+  if (/<(!doctype|html|head|body)\b/i.test(code)) {
+    return callError(id, "Pass a fragment, not a document: drop the doctype, html and body tags.");
+  }
+  return ok(id, text(`Widget "${title}" is on screen. Don't repeat its content in prose.`));
+}
+function handleChoice(id, args) {
+  const problem = validateChoice(args);
+  if (problem) return callError(id, problem);
+  return ok(id, text("Options are on screen. Wait for the user to pick one."));
+}
+function handleMessage(req, version) {
+  const id = req.id ?? null;
+  const method = req.method ?? "";
+  const params = req.params ?? {};
+  if (method.startsWith("notifications/")) return null;
+  switch (method) {
+    case "initialize": {
+      const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : null;
+      return ok(id, {
+        protocolVersion: asked ?? DEFAULT_PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: SERVER_NAME, version }
+      });
+    }
+    case "ping":
+      return ok(id, {});
+    case "tools/list":
+      return ok(id, { tools: TOOLS });
+    case "tools/call": {
+      const name = typeof params.name === "string" ? params.name : "";
+      const args = params.arguments ?? {};
+      if (name === "read_me") return handleReadMe(id, args);
+      if (name === "show_widget") return handleShowWidget(id, args);
+      if (name === "show_choice") return handleChoice(id, args);
+      return { jsonrpc: "2.0", id, error: { code: -32602, message: `Unknown tool: ${name}` } };
+    }
+    default:
+      if (id === null) return null;
+      return { jsonrpc: "2.0", id, error: { code: -32601, message: `Unknown method: ${method}` } };
+  }
+}
+
+// server/src/mcp/server.ts
+var VERSION = true ? "0.8.0" : "dev";
+function runMcpServer() {
+  const rl = createInterface({ input: process.stdin });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let req;
+    try {
+      req = JSON.parse(trimmed);
+    } catch {
+      process.stdout.write(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32700, message: "Parse error" }
+        }) + "\n"
+      );
+      return;
+    }
+    try {
+      const res = handleMessage(req, VERSION);
+      if (res) process.stdout.write(JSON.stringify(res) + "\n");
+    } catch (err) {
+      process.stderr.write(`casper-mcp: ${err.message}
+`);
+      if (req.id !== void 0 && req.id !== null) {
+        process.stdout.write(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: req.id,
+            error: { code: -32603, message: "Internal error" }
+          }) + "\n"
+        );
+      }
+    }
+  });
+  rl.on("close", () => process.exit(0));
+}
+
+// server/src/mcp/index.ts
+runMcpServer();