Initial commit: AI Dungeon clone (FastAPI backend + React frontend)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KFsGHju9szibJJa2YJcdbg

backend/app/scripting/__init__.py

@@ -0,0 +1,4 @@
+from .engine import HookResult, run_hook
+from .pipeline import ScriptPipeline
+
+__all__ = ["HookResult", "ScriptPipeline", "run_hook"]

backend/app/scripting/engine.py

@@ -0,0 +1,143 @@
+"""AI Dungeon-compatible script execution in an embedded QuickJS sandbox.
+
+Each hook run is fully isolated (fresh Context), capped at 16 MB memory and
+2 seconds CPU, with no filesystem/network/process access (QuickJS has none by
+default). Scripts follow the AI Dungeon contract: define a `modifier(text)`
+and call it as the last line; its return value `{ text, stop }` is the result.
+"""
+
+import json
+from dataclasses import dataclass, field
+
+import quickjs
+
+MEMORY_LIMIT = 16 * 1024 * 1024
+TIME_LIMIT_SECONDS = 2
+HISTORY_WINDOW = 100  # recent actions exposed as `history`
+
+# Globals per the official docs: text, state, history, storyCards, info,
+# log/console.log, story card functions, plus legacy worldInfo aliases.
+PRELUDE = """
+"use strict";
+var __logs = [];
+var state = __DATA__.state;
+var text = __DATA__.text;
+var history = __DATA__.history;
+var storyCards = __DATA__.storyCards;
+var info = __DATA__.info;
+
+function log(msg) {
+  __logs.push(typeof msg === "string" ? msg : JSON.stringify(msg));
+}
+var console = { log: log };
+
+function addStoryCard(keys, entry, type) {
+  for (var i = 0; i < storyCards.length; i++) {
+    if (storyCards[i].keys === keys) return false;
+  }
+  storyCards.push({ id: null, keys: keys || "", entry: entry || "", type: type || "" });
+  return storyCards.length - 1;
+}
+function updateStoryCard(index, keys, entry, type) {
+  var card = storyCards[index];
+  if (!card) throw new Error("Story card not found");
+  card.keys = keys;
+  card.entry = entry;
+  card.type = type;
+}
+function removeStoryCard(index) {
+  if (!storyCards[index]) throw new Error("Story card not found");
+  storyCards.splice(index, 1);
+}
+
+// Legacy aliases used by older AI Dungeon scripts.
+var worldInfo = storyCards;
+var worldEntries = storyCards;
+function addWorldEntry(keys, entry) { return addStoryCard(keys, entry, ""); }
+function updateWorldEntry(index, keys, entry) {
+  var card = storyCards[index];
+  if (!card) throw new Error("World entry not found");
+  card.keys = keys;
+  card.entry = entry;
+}
+function removeWorldEntry(index) { return removeStoryCard(index); }
+"""
+
+COLLECT = """
+JSON.stringify({
+  result: (typeof __result === "undefined" || __result === null) ? null : __result,
+  state: state,
+  storyCards: storyCards,
+  logs: __logs
+})
+"""
+
+
+@dataclass
+class HookResult:
+    text: str
+    stop: bool = False
+    state: dict = field(default_factory=dict)
+    story_cards: list = field(default_factory=list)
+    logs: list = field(default_factory=list)
+    error: str | None = None
+
+
+def run_hook(
+    library_js: str,
+    hook_js: str,
+    text: str,
+    state: dict,
+    history: list[dict],
+    story_cards: list[dict],
+    info: dict,
+) -> HookResult:
+    """Run one modifier hook. Never raises: failures come back as .error with
+    text/state/cards unchanged, so a bad script can't break a turn."""
+    unchanged = HookResult(text=text, state=state, story_cards=story_cards)
+    source = f"{library_js}\n;\n{hook_js}" if library_js.strip() else hook_js
+    if not source.strip():
+        return unchanged
+
+    data = {
+        "state": state,
+        "text": text,
+        "history": history[-HISTORY_WINDOW:],
+        "storyCards": story_cards,
+        "info": info,
+    }
+    try:
+        ctx = quickjs.Context()
+        ctx.set_memory_limit(MEMORY_LIMIT)
+        ctx.set_time_limit(TIME_LIMIT_SECONDS)
+        ctx.eval(f"var __DATA__ = {json.dumps(data)};")
+        ctx.eval(PRELUDE)
+        ctx.eval(f"var __SRC__ = {json.dumps(source)};")
+        # Indirect eval keeps the script in global scope, so `modifier(text)` as the
+        # script's final expression statement becomes the completion value.
+        ctx.eval("var __result = (0, eval)(__SRC__);")
+        collected = json.loads(ctx.eval(COLLECT))
+    except quickjs.JSException as exc:
+        unchanged.error = f"Script error: {exc}"
+        return unchanged
+    except Exception as exc:  # memory limit, invalid JSON state, engine faults
+        unchanged.error = f"Script execution failed: {exc}"
+        return unchanged
+
+    result = collected.get("result")
+    new_text, stop = text, False
+    if isinstance(result, dict):
+        if isinstance(result.get("text"), str):
+            new_text = result["text"]
+        stop = bool(result.get("stop"))
+    elif isinstance(result, str):
+        new_text = result
+
+    new_state = collected.get("state")
+    return HookResult(
+        text=new_text,
+        stop=stop,
+        state=new_state if isinstance(new_state, dict) else {},
+        story_cards=collected.get("storyCards") or [],
+        logs=collected.get("logs") or [],
+    )

backend/app/scripting/pipeline.py

@@ -0,0 +1,95 @@
+"""Runs an adventure's enabled scripts through a turn's hook points, applying
+state and story-card mutations back to the database after each hook."""
+
+from sqlalchemy.orm import Session
+
+from .. import models
+from .engine import run_hook
+
+MAX_STORY_CARDS = 5000  # AI Dungeon's per-adventure sanity cap
+
+
+class ScriptPipeline:
+    def __init__(self, adventure: models.Adventure, db: Session):
+        self.adventure = adventure
+        self.db = db
+        self.logs: list[str] = []
+        self.errors: list[str] = []
+
+    @property
+    def message(self) -> str | None:
+        state = self.adventure.script_state
+        msg = state.get("message") if isinstance(state, dict) else None
+        return msg if isinstance(msg, str) and msg.strip() else None
+
+    def _history(self) -> list[dict]:
+        return [
+            {"text": a.text, "rawText": a.text, "type": a.type}
+            for a in self.adventure.actions
+        ]
+
+    def _cards(self) -> list[dict]:
+        return [
+            {"id": c.id, "keys": c.keys, "entry": c.entry, "type": c.type}
+            for c in self.adventure.story_cards
+        ]
+
+    def _info(self) -> dict:
+        return {
+            "actionCount": len(self.adventure.actions),
+            "characterNames": [],
+            "memoryLength": len(self.adventure.memory),
+            "maxChars": 0,
+        }
+
+    def _apply_cards(self, returned: list) -> None:
+        existing = {c.id: c for c in self.adventure.story_cards}
+        seen_ids = set()
+        for item in returned:
+            if not isinstance(item, dict):
+                continue
+            card_id = item.get("id")
+            keys = str(item.get("keys") or "")
+            entry = str(item.get("entry") or "")
+            card_type = str(item.get("type") or "")
+            if card_id in existing:
+                seen_ids.add(card_id)
+                card = existing[card_id]
+                card.keys, card.entry, card.type = keys, entry, card_type
+            elif len(existing) + len(seen_ids) < MAX_STORY_CARDS:
+                self.db.add(
+                    models.StoryCard(
+                        adventure_id=self.adventure.id,
+                        keys=keys, entry=entry, type=card_type,
+                    )
+                )
+        for card_id, card in existing.items():
+            if card_id not in seen_ids:
+                self.db.delete(card)
+
+    def run(self, hook: str, text: str) -> tuple[str, bool]:
+        """Chain `hook` across all enabled scripts. Returns (text, stop)."""
+        state = self.adventure.script_state if isinstance(self.adventure.script_state, dict) else {}
+        for script in self.adventure.scripts:
+            hook_js = getattr(script, f"{hook}_js")
+            if not script.enabled or not hook_js.strip():
+                continue
+            result = run_hook(
+                script.library_js, hook_js, text, state,
+                self._history(), self._cards(), self._info(),
+            )
+            if result.error:
+                self.errors.append(f"{script.name} ({hook}): {result.error}")
+                continue  # a broken script never breaks the turn
+            self.logs.extend(f"[{script.name}/{hook}] {line}" for line in result.logs)
+            self._apply_cards(result.story_cards)
+            state = result.state
+            self.adventure.script_state = state
+            self.db.commit()
+            text = result.text
+            if result.stop:
+                return text, True
+        return text, False
+
+    def report(self) -> dict:
+        return {"logs": self.logs, "errors": self.errors, "message": self.message}