spriteforge 0.1.1__py3-none-any.whl

spriteforge/cli.py

@@ -0,0 +1,241 @@
+import json
+import threading
+import webbrowser
+from pathlib import Path
+
+import typer
+import uvicorn
+
+from spriteforge.app.server import create_app
+from spriteforge.config import init_workspace, load_config
+from spriteforge.core.credentials import load_credentials
+from spriteforge.core.state import Store
+from spriteforge.game.cli import app as game_app
+from spriteforge.library.cli import app as library_app
+from spriteforge.mcp.cli import app as mcp_app
+from spriteforge.memory.cli import app as memory_app
+from spriteforge.skills.cli import app as skills_app
+
+app = typer.Typer()
+app.add_typer(memory_app, name="memory")
+app.add_typer(skills_app, name="skills")
+app.add_typer(mcp_app, name="mcp")
+app.add_typer(library_app, name="library")
+app.add_typer(game_app, name="game")
+
+
+def setup(config: Path | None, workspace: Path | None):
+    load_credentials()
+    cfg = load_config(config)
+    root = init_workspace(workspace or cfg.workspace)
+    return cfg, Store(root / "state.sqlite3")
+
+
+def serve(store, run_id, port, open_browser, cfg=None):
+    url = f"http://127.0.0.1:{port}"
+    typer.echo(f"SpriteForge Studio · {url}" + (f" · run {run_id}" if run_id else ""))
+    if open_browser:
+        timer = threading.Timer(1.5, webbrowser.open, args=(url,))
+        timer.daemon = True
+        timer.start()
+    app = create_app(store, run_id, cfg=cfg)
+    uvicorn.run(app, host="127.0.0.1", port=port, access_log=False)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context):
+    """SpriteForge. With no command, opens the studio in the browser."""
+    if ctx.invoked_subcommand is None:
+        studio()
+
+
+@app.command()
+def studio(
+    config: Path | None = None,
+    workspace: Path | None = None,
+    port: int = 8765,
+    open_browser: bool = True,
+):
+    """Open the studio: every project in the workspace, chat-first (the default command)."""
+    cfg, store = setup(config, workspace)
+    serve(store, None, port, open_browser, cfg)
+
+
+@app.command()
+def start(
+    mock: bool = False,
+    agents: bool = False,
+    intake: bool = False,
+    assets: bool = False,
+    legacy: bool = False,
+    goal: str = "",
+    config: Path | None = None,
+    workspace: Path | None = None,
+    port: int = 8765,
+    open_browser: bool = True,
+):
+    """Start a local UI; --agents uses the Phaser gameplay preview and human gates."""
+    cfg, store = setup(config, workspace)
+    if legacy:
+        typer.echo("DEPRECATED: --legacy enables the old concept/demo preview.", err=True)
+    if intake or assets or (agents and not legacy):
+        from spriteforge.stages.workflow import start_run
+
+        run = start_run(
+            store,
+            cfg,
+            mock=mock,
+            assets=assets,
+            gameplay_preview=not legacy,
+            legacy=legacy,
+            goal=goal,
+        )
+        serve(store, run.id, port, open_browser, cfg)
+        return
+    if agents and not mock:
+        raise typer.BadParameter("The agent acceptance workflow requires --mock")
+    if agents:
+        from spriteforge.agents.workflow import start_run
+
+        run = start_run(
+            store,
+            goal or "A top-down dungeon crawler with a hero and stone rooms",
+            cfg.budget,
+            router=cfg.router,
+        )
+        store.append_event(run.id, "Director", "preview.deprecated", {"legacy": True})
+        serve(store, run.id, port, open_browser, cfg)
+        return
+    run = (
+        store.create_run({"workflow": "mock-demo-v1", "budget": cfg.budget.model_dump()})
+        if mock
+        else None
+    )
+    serve(store, run.id if run else None, port, open_browser, cfg)
+
+
+@app.command()
+def router_eval(
+    live: bool = False,
+    max_calls: int = typer.Option(5, min=1, max=20),
+    offset: int = typer.Option(0, min=0),
+    cases: Path = Path("tests/router_cases.yaml"),
+    config: Path | None = None,
+    workspace: Path | None = None,
+):
+    """Report router precision/recall; --live makes at most --max-calls Spark requests."""
+    from uuid import uuid4
+
+    from spriteforge.agents.router_eval import evaluate, read_cases
+    from spriteforge.core.cost import Budget
+    from spriteforge.core.state import Artifact
+    from spriteforge.providers.mock import MockLLMProvider
+    from spriteforge.providers.muse_spark import MuseSparkProvider
+
+    cfg, store = setup(config, workspace)
+    suite = read_cases(cases)[offset:]
+    limits = (
+        cfg.budget.model_copy(
+            update={
+                "max_total_calls": min(
+                    cfg.budget.max_total_calls
+                    if cfg.budget.max_total_calls is not None
+                    else max_calls,
+                    max_calls,
+                )
+            }
+        )
+        if live
+        else cfg.budget
+    )
+    run = store.create_run(
+        {
+            "workflow": "router-eval",
+            "budget": limits.model_dump(),
+            "settings": cfg.model_dump(mode="json"),
+        }
+    )
+    budget = Budget(store, run.id, limits)
+    provider = MuseSparkProvider(cfg.llm, budget) if live else MockLLMProvider(budget)
+    try:
+        report = evaluate(
+            provider, suite, cfg.router, store.path.parent, live=live, max_calls=max_calls
+        )
+    finally:
+        if live:
+            provider.close()
+    store.save_artifact(
+        Artifact(
+            id=uuid4().hex,
+            run_id=run.id,
+            name="router-eval.json",
+            mime="application/json",
+            data=report.model_dump_json(indent=2).encode(),
+        ),
+        "Router",
+        "router.eval",
+    )
+    with store.connect() as db:
+        db.execute("UPDATE runs SET status='completed' WHERE id=?", (run.id,))
+    typer.echo(f"{report.mode}: {report.evaluated} cases, {report.skipped} skipped")
+    typer.echo(f"Spark calls attempted: {report.evaluated if live else 0} (cap {max_calls})")
+    typer.echo(f"Precision: {report.precision:.3f}  Recall: {report.recall:.3f}")
+    typer.echo(f"Failures: {len(report.failures)}")
+    for failure in report.failures:
+        typer.echo(failure.model_dump_json())
+    typer.echo(f"Run: {run.id} (router-eval.json contains all results)")
+
+
+@app.command()
+def report(id: str, config: Path | None = None, workspace: Path | None = None):
+    """Report successful image/Spark usage and failed attempts from the durable ledger."""
+    from spriteforge.core.usage import usage_report
+
+    _, store = setup(config, workspace)
+    typer.echo(usage_report(store, id).model_dump_json(indent=2))
+
+
+@app.command()
+def runs(config: Path | None = None, workspace: Path | None = None):
+    """List runs persisted in the workspace database."""
+    _, store = setup(config, workspace)
+    for run in store.runs():
+        typer.echo(f"{run.id}  {run.status:10}  checkpoint={run.cursor}")
+
+
+@app.command()
+def resume(
+    id: str,
+    config: Path | None = None,
+    workspace: Path | None = None,
+    port: int = 8765,
+    open_browser: bool = True,
+    assets: bool = False,
+    legacy: bool = False,
+):
+    """Resume from the database checkpoint and show its timeline."""
+    cfg, store = setup(config, workspace)
+    try:
+        run = store.get_run(id)
+    except KeyError:
+        raise typer.BadParameter(f"Run {id} does not exist") from None
+    old_preview = run.config.get("workflow") == "agent-runtime-mock-v1" or (
+        run.config.get("workflow") == "intake-concept-v1" and not run.config.get("gameplay_preview")
+    )
+    if old_preview:
+        if not legacy:
+            raise typer.BadParameter("This deprecated preview requires explicit --legacy")
+        typer.echo("DEPRECATED: --legacy enables the old concept/demo preview.", err=True)
+        with store.connect() as db:
+            db.execute(
+                "UPDATE runs SET config=? WHERE id=?",
+                (json.dumps({**run.config, "legacy_preview": True}), id),
+            )
+            store._event(db, id, "Director", "preview.deprecated", {"legacy": True})
+    if assets:
+        from spriteforge.stages.production import enable_production
+
+        enable_production(store, id)
+    if run.status == "failed" and run.config.get("workflow") == "intake-concept-v1":
+        store.retry_failed(id)
+    serve(store, id, port, open_browser, cfg)

spriteforge/config.py

@@ -0,0 +1,193 @@
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+
+
+class Schema(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ImageConfig(Schema):
+    base_url: HttpUrl
+    model: str
+    generate_path: str
+    edit_path: str
+    # Sizes Muse Image has accepted live; requests pick the one nearest the subject's aspect.
+    sizes: list[tuple[int, int]] = Field(default_factory=lambda: [(1024, 1024)], min_length=1)
+
+
+Effort = Literal["minimal", "low", "medium", "high", "xhigh", "max"]
+
+
+class LLMConfig(Schema):
+    base_url: HttpUrl
+    model: str
+    chat_path: str
+    # Spark `reasoning_effort` per task (intake, art_plan, revision, design, code); a task
+    # not listed sends none and the model picks its own effort.
+    reasoning: dict[str, Effort] = Field(default_factory=dict)
+
+
+class BudgetConfig(Schema):
+    max_image_calls: int = Field(default=150, ge=0)
+    max_calls_per_model: int = Field(default=200, ge=0)
+    max_total_calls: int | None = Field(default=None, ge=0)
+    image_cost: float = Field(default=0.01, ge=0)
+    # Meta standard Spark rates: https://dev.meta.ai/docs/pricing-rate-limits
+    spark_input_per_million: float = Field(default=1.25, ge=0)
+    spark_cached_input_per_million: float = Field(default=0.15, ge=0)
+    spark_output_per_million: float = Field(default=4.25, ge=0)
+    # Muse Spark web search: "$2.50 per 1,000 search queries, in addition to the request's
+    # token cost" (https://dev.meta.ai/docs/pricing-rate-limits, 2026-11-02).
+    web_search_cost: float = Field(default=0.0025, ge=0)
+    max_estimated_cost: float = Field(default=5, ge=0)
+    # True (config.yaml): each agent may spend `max_agent_cost` (USD, estimated) since the
+    # human's last action (a gate answer, Go back, Continue); the caps above do not apply. Its
+    # loops run until that is used up or a try brings no improvement (game.patience), and work
+    # the user asks for always starts. False: the caps above, per run (the legacy concept and
+    # production stages, budgets made in code).
+    per_request: bool = False
+    max_agent_cost: float = Field(default=10, ge=0)
+
+
+class ResearchConfig(Schema):
+    """Muse Spark web search for the Game Designer's research (L2.2), on the Responses API."""
+
+    path: str = "/v1/responses"
+    # Built-in tool calls per research (searches and page opens; `max_tool_calls`).
+    max_searches: int = Field(default=8, ge=1, le=20)
+    search_context_size: Literal["low", "medium", "high"] = "medium"
+
+
+class MemoryConfig(Schema):
+    min_score: float = Field(default=0, ge=0, allow_inf_nan=False)
+    relative_score: float = Field(default=0.5, ge=0, le=1)
+
+
+class PreviewConfig(Schema):
+    max_image_calls: int = Field(default=16, ge=0, le=150)
+    mood_board: bool = True
+    # game: after G1 Spark writes a design (G2 gate) and then the game's code (G4 playtest
+    # gate); art comes from the library first, Muse Image for the rest (`game` settings).
+    # muse: the original Muse Image building-block preview.
+    mode: Literal["game", "muse"] = "game"
+
+    @model_validator(mode="before")
+    @classmethod
+    def legacy_kit_settings(cls, data):
+        """Runs saved before kits were removed: mode 'kit' and preview.max_art_calls."""
+        if isinstance(data, dict):
+            data = {k: v for k, v in data.items() if k != "max_art_calls"}
+            if data.get("mode") == "kit":
+                data["mode"] = "game"
+        return data
+
+
+class GameConfig(Schema):
+    """Prompt-driven games: Spark writes the code, the harness checks and playtests it."""
+
+    # Agent loops (Programmer repairs, Muse redraws, QA check fixes, Menu and Level retries,
+    # Art Reviewer rounds) try again while they improve: they stop after `patience` tries in a
+    # row without improvement, or when the agent's allowance (budget.max_agent_cost) is used
+    # up. The counts below are optional fixed limits on top (None: no fixed limit).
+    patience: int = Field(default=2, ge=1, le=10)
+    max_repairs: int | None = Field(default=None, ge=0)  # Programmer fix rounds after failed checks
+    max_art_calls: int | None = Field(default=None, ge=0)  # Muse Image calls per build
+    image_workers: int = Field(default=4, ge=1, le=8)  # Muse Image calls in flight at once
+    image_cache: bool = True  # identical Muse requests reuse workspace/cache/muse-image
+    # The game's screen: 320x180 design pixels times screen_scale (6: 1920x1080, a laptop's
+    # full-HD screen). Every sprite, tile, text and distance is that many times bigger, so a
+    # sprite keeps more of the detail Muse drew and words stay readable.
+    screen_scale: int = Field(default=6, ge=1, le=8)
+    # The Level/Tile Designer studies the level design of similar platformers with web search
+    # (one search call per game, before the first level) and its level prompts read it.
+    level_research: bool = True
+    # Muse Image's strength for every first draw (the API has low and high; redraws and the
+    # Art Reviewer's fixes use high too).
+    image_reasoning: Literal["low", "high"] = "high"
+    art_retry: int | None = Field(default=None, ge=0)  # redraws of a Muse frame that fails checks
+    native_grid_confidence: float = Field(default=0.6, ge=0, le=1)  # big-pixel grid read-back
+    # Muse sprites as sheets: frames per animation row (1 = one image per sprite)
+    sheet_frames: int = Field(default=4, ge=1, le=6)
+    adapt_size: bool = True  # a Muse sprite's frame takes the drawn art's shape
+    # Art Reviewer (M10.3): one vision call after the playtest; blocking issues are fixed once
+    # (at most review_max_fixes Muse Image edits at review_image_reasoning) before G4.
+    review: bool = True
+    review_max_fixes: int | None = Field(default=None, ge=0)
+    review_image_reasoning: Literal["low", "high"] = "high"
+    # Review call plus fixes stay within this estimate: fewer fixes when the review costs more.
+    review_cost_cap: float | None = Field(default=None, ge=0)
+    # QA tests (M10.4): the QA Playtester writes tests from each design version; every build runs
+    # them (and earlier versions' tests) with real key presses after the bot playtest.
+    qa: bool = True
+    # Code checks (L2.8): after the Programmer's first answer the QA Playtester reads the design
+    # and the code and writes checks of this game's own rules as JavaScript run in the game.
+    qa_checks: bool = True
+    # The bot playtest also looks at the HUD: texts drawn over each other or off the screen
+    # fail the build and go to the Programmer.
+    hud_check: bool = True
+    motion: bool = True  # the Art Director's motion design: rows, forms, effects (L2.4)
+    # Menus and flow (L2.5): the Menu Designer's screens rendered by the SDK (title, pause,
+    # results, game over, victory, saved progress) and G3; title_art: Muse draws the title
+    # background and emblem (2 image calls; false or offline: code draws them).
+    menus: bool = True
+    title_art: bool = True
+    # Sounds (L2.7): the Sound Director's synthesised sounds (one Spark call per game), played by
+    # the SDK on the game's moments and edited in the build's sound editor or at G4.
+    sounds: bool = True
+    # Agent tools: in a live build each agent's Spark call may look things up with the tools its
+    # role grants (the built-in library and game-record MCP servers, its skills, and the user's
+    # MCP tools granted to it that need no confirmation), for up to `tool_rounds` rounds.
+    agent_tools: bool = True
+    tool_rounds: int = Field(default=3, ge=0, le=10)
+    max_code_kb: int = Field(default=200, ge=10, le=1000)
+    playtest_fps: int = Field(default=30, ge=10, le=60)
+    record_seconds: int = Field(default=20, ge=5, le=60)
+
+    @model_validator(mode="before")
+    @classmethod
+    def legacy_story_switch(cls, data):
+        """Runs saved before L2.1 had `game.story`; the G1 brief now decides (a story only
+        when the human asks for one)."""
+        if isinstance(data, dict):
+            data = {k: v for k, v in data.items() if k != "story"}
+        return data
+
+
+class RouterConfig(Schema):
+    enabled: bool = True
+    max_skills: int = Field(default=3, ge=0, le=100)
+    max_tools: int = Field(default=5, ge=0, le=100)
+    token_budget: int = Field(default=4096, ge=0)
+
+
+class Config(Schema):
+    workspace: Path
+    memory: MemoryConfig = Field(default_factory=MemoryConfig)
+    preview: PreviewConfig = Field(default_factory=PreviewConfig)
+    game: GameConfig = Field(default_factory=GameConfig)
+    router: RouterConfig = Field(default_factory=RouterConfig)
+    image: ImageConfig
+    llm: LLMConfig
+    research: ResearchConfig = Field(default_factory=ResearchConfig)
+    budget: BudgetConfig = Field(default_factory=BudgetConfig)
+
+
+def load_config(path: Path | None = None) -> Config:
+    return Config.model_validate(
+        yaml.safe_load(
+            (path or Path(__file__).with_name("config.yaml")).read_text(encoding="utf-8")
+        )
+    )
+
+
+def init_workspace(path: Path) -> Path:
+    root = path.expanduser().resolve()
+    for name in ("runs", "memory", "skills"):
+        (root / name).mkdir(parents=True, exist_ok=True)
+    mcp = root / "mcp.json"
+    if not mcp.exists():
+        mcp.write_text('{"mcpServers": {}}\n', encoding="utf-8")
+    return root

spriteforge/config.yaml

@@ -0,0 +1,157 @@
+workspace: ~/spriteforge-workspace
+router:
+  enabled: true
+  max_skills: 3
+  max_tools: 5
+  token_budget: 4096 # conservative UTF-8 byte bound for loaded skill context
+preview:
+  max_image_calls: 16
+  mood_board: true
+  mode: game # game = Spark writes the design and code (G2/G4 gates); muse = Muse blocks
+game:
+  # Agent loops (Programmer repairs, Muse redraws, QA check fixes, Menu and Level retries, Art
+  # Reviewer rounds) try again while they improve. A loop stops after `patience` tries in a
+  # row without improvement, or when the agent has spent its budget.max_agent_cost ($10)
+  # since your last action. max_repairs, max_art_calls, art_retry and review_max_fixes are
+  # optional fixed limits on top (unset: none).
+  patience: 2
+  # Muse jobs run in parallel (Meta allows 150 image requests/min). Call slots are handed out
+  # in priority order before dispatch, so the cap and the greybox choice stay deterministic.
+  image_workers: 4
+  # The game's screen: 320x180 design pixels times screen_scale. 6 = 1920x1080 (a laptop's
+  # full-HD screen; sprites keep 6x the pixels Muse drew, text is 6x bigger); 4 = 1280x720.
+  screen_scale: 6
+  # The Level/Tile Designer studies the level design of similar platformers with web search
+  # (one search call per game, before the first level); its level prompts read the findings.
+  level_research: true
+  # Muse Image's strength for every first draw: high (the API has low and high). Redraws and
+  # the Art Reviewer's fixes use high as well.
+  image_reasoning: high
+  # Identical requests (model, endpoint, prompt, size, reasoning strength, n, reference
+  # hashes) reuse workspace/cache/muse-image/<sha256>.png: no call, no cost.
+  image_cache: true
+  # A frame that fails check_frame is redrawn (reasoning_strength high) while redraws improve.
+  native_grid_confidence: 0.6 # below this, Muse art is fitted instead of read cell by cell
+  # Muse sprites are drawn as sheets (a row of frames per animation, up to 4 rows): each
+  # frame gets a slot of the image, so Muse draws it with fewer, bigger pixels, close to the
+  # requested grid, and the sprite animates. 1 = one image per sprite.
+  sheet_frames: 4
+  # A Muse sprite's frame takes the shape Muse drew (about the design's area) instead of
+  # squeezing it into the design box; the Programmer sees the real size in assets.json.
+  adapt_size: true
+  # Art Reviewer: after the playtest, Spark (vision) looks at all the art together and at 3
+  # screenshots of the running game; blocking issues are fixed before G4 with Muse Image
+  # edits at its highest setting (the API has low and high), then it reviews again while the
+  # blocking issues go down (patience, its $10 allowance); the rest are G4 suggestions.
+  review: true
+  review_image_reasoning: high
+  # QA Playtester: tests written from each design version (one Spark call), played with real
+  # key presses after the bot playtest; failures join the repairs; exported per build as
+  # build/tests/test_game_qa.py (pytest + Playwright).
+  qa: true
+  # Motion design (L2.4): the Art Director writes every entity's animation rows (what each
+  # frame shows, fps, loop), how the player looks in each form and the effects the SDK plays
+  # (sf.fx); Muse draws the rows, code checks and repairs them. false = the design's names.
+  motion: true
+  # Menus and flow (L2.5): the Menu Designer writes the menus as data (one Spark call per game;
+  # feedback revises them), the SDK renders them in the art's colours and runs the flow (title,
+  # pause, results, game over, victory, progress saved in the browser); G3 shows every screen
+  # before the playtest. title_art: Muse draws the title background and an emblem (2 image
+  # calls, locked once drawn; false: code draws them from the game's art).
+  menus: true
+  title_art: true
+  # Sounds (L2.7): the Sound Director picks a synthesised sound for every moment (one Spark
+  # call; no audio files, no image calls); the SDK plays them, the build's sounds.html edits them.
+  sounds: true
+  # Agent tools: in a live build each agent may look things up before it answers, with the
+  # tools its role grants (allowed_tools in agents/roles/*.md: the built-in library and game
+  # record MCP servers), its skills (load_skill) and your MCP tools granted to it that need no
+  # confirmation. Each round is one more Spark call; false: one call per answer, no tools.
+  agent_tools: true
+  tool_rounds: 3
+  # (No story switch: the G1 brief decides. A story bible is written only when the human asks
+  # for one; every game keeps its full record as an OKF bundle in runs/<id>/game/db.)
+  max_code_kb: 200
+  playtest_fps: 30
+  record_seconds: 20
+image:
+  # Live smoke 2026-10-28: both paths accept size=1024x1024, b64_json,
+  # output_format=png and reasoning_strength=low, but return 1600x1600 PNGs.
+  # One data-URL reference verified; the maximum reference count is unverified.
+  base_url: https://api.meta.ai
+  model: muse-image-1.0
+  generate_path: /v1/images/generations
+  edit_path: /v1/images/edits
+  # Request sizes (aspect ratio only). Art requests use the one nearest the subject's aspect.
+  # Live probe 2026-10-31, all accepted: 1024x1024 -> 1600x1600,
+  # 1792x1024 -> 2016x1152, 1024x1536 -> 1280x1920. With the grid wording Muse draws big
+  # square pixels but chooses its own cell count (16x16 asked: 21x27 cells, ~46 px each).
+  # Live probe 2026-10-31: 2048x512 (4:1) accepted -> 3200x800.
+  # Live probe 2026-10-31: 1536x512 (3:1) accepted -> 2736x912.
+  sizes: [[1024, 1024], [1792, 1024], [1024, 1536], [2048, 512], [1536, 512]]
+llm:
+  base_url: https://api.meta.ai
+  model: muse-spark-1.3
+  chat_path: /v1/chat/completions
+  # Live probe 2026-10-30: strict json_schema {files:[{path,content}]} returned a complete
+  # 375-line Phaser game (8578 completion tokens, finish_reason stop, 43 s); it ran without
+  # errors. One call per game file set is enough; no output-length setting was needed.
+  # Live probe 2026-10-31: top-level reasoning_effort is accepted and
+  # works (same question: low 113-119 reasoning tokens, max 366-455). Docs list minimal,
+  # low, medium, high, xhigh, max ("none" -> HTTP 400). Prefix caching is automatic: a
+  # repeated 1558-token prompt reported cached_tokens 1521 on a second run, also across
+  # different efforts (0 on back-to-back calls of the very first run: the cache fills
+  # shortly after a request). Prompts start with their stable part and send a
+  # prompt_cache_key per task.
+  reasoning:
+    intake: low # G1 genre pick, brief draft, follow-up questions, style options
+    art_plan: low # Art Director's library picks
+    revision: low # Director splitting G4 feedback
+    design: high # Game Designer's design doc and its revisions
+    code: high # Programmer: new game, repairs, changes
+    review: max # Art Reviewer (vision): the strongest setting Spark accepts
+    describe: low # Librarian describing library images (spriteforge library describe)
+    qa: high # QA Playtester writing tests from the design
+    story: high # Game Designer writing the story bible
+    research: medium # Game Designer studying similar games with web search (L2.2)
+    plan: high # Game Designer writing the game plan from the requirements and research
+    level: high # Level/Tile Designer writing each level as data (L2.3)
+    motion: medium # Art Director's motion design: rows, forms, effects (L2.4)
+    menus: medium # Menu Designer: the menus as data and their revisions (L2.5)
+    sounds: low # Sound Director: a preset and tweaks per moment, and their revisions (L2.7)
+    lessons: low # Librarian: lessons from a finished game, shown at G5 (L2.6)
+research:
+  # Live probe 2026-11-02: Chat Completions rejects {"type": "web_search"}
+  # (HTTP 400 "tools[0] did not match any supported type"); the Responses API accepts it.
+  # Citations: `url_citation` annotations on output_text (few), and with
+  # include ["web_search_call.action.sources"] every search lists the pages it returned
+  # (11-12 each). json_schema (text.format, strict) and web_search work in one call: the last
+  # `message` item holds the JSON (earlier ones are progress lines). A URL in the JSON is not
+  # always one a search returned, so code checks every reference URL against the sources.
+  # Searches are not in `usage`: each `web_search_call` item (search or open_page) is counted
+  # as one search (budget.web_search_cost). One probe research: 10.8k input + 2.1k output
+  # tokens (low effort) and 4 tool calls, about $0.03.
+  path: /v1/responses
+  max_searches: 8 # max_tool_calls per research
+  search_context_size: medium
+budget:
+  max_image_calls: 150
+  max_calls_per_model: 200
+  image_cost: 0.01
+  # Standard Spark USD / million tokens, verified 2026-10-29:
+  # https://dev.meta.ai/docs/pricing-rate-limits
+  spark_input_per_million: 1.25
+  spark_cached_input_per_million: 0.15
+  spark_output_per_million: 4.25
+  # https://dev.meta.ai/docs/pricing-rate-limits 2026-11-02: $2.50 per 1,000 search queries
+  web_search_cost: 0.0025
+  max_estimated_cost: 5.0 # per run, legacy stages only (per_request: false)
+  # Each agent may spend max_agent_cost (USD) since your last action (a gate answer, Go back,
+  # Continue); its loops run until that is used up or they stop improving (game.patience).
+  # Work you ask for always starts.
+  per_request: true
+  max_agent_cost: 10
+
+memory:
+  min_score: 0
+  relative_score: 0.5

spriteforge/core/acting.py

@@ -0,0 +1,16 @@
+"""Which agent is making the model call now: the cost ledger records it with each call, so the
+studio can show what every agent cost and which one is working."""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+acting_agent: ContextVar[str | None] = ContextVar("acting_agent", default=None)
+
+
+@contextmanager
+def acting(agent: str):
+    token = acting_agent.set(agent)
+    try:
+        yield
+    finally:
+        acting_agent.reset(token)