spriteforge 0.1.1__py3-none-any.whl

spriteforge/agents/workflow.py

@@ -0,0 +1,389 @@
+"""Offline agent-runtime acceptance workflow, resumed entirely from local artifacts and gates."""
+
+import asyncio
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from spriteforge.config import BudgetConfig, RouterConfig, load_config
+from spriteforge.core.cost import Budget
+from spriteforge.core.gates import Gates, new_gate
+from spriteforge.core.state import Store
+from spriteforge.memory.okf.git import write_lock
+from spriteforge.memory.okf.seed import seed
+from spriteforge.memory.okf.store import KnowledgeStore
+from spriteforge.providers.base import ChatResult
+from spriteforge.providers.mock import MockImageProvider, MockLLMProvider
+
+from .assets import AssetResult, Assets, GenerateAsset
+from .director import Director
+from .models import Changes, RoleOutput, StageNode, StagePlan
+from .roles import Role, load_roles
+from .runtime import AgentRuntime, AgentTask, Tool
+
+WORKFLOW = "agent-runtime-mock-v1"
+
+
+class Flow(BaseModel):
+    roles: dict[str, Role]
+    plan: StagePlan | None = None
+    outputs: dict[str, str] = Field(default_factory=dict)
+    completed: list[str] = Field(default_factory=list)
+    handled: list[str] = Field(default_factory=list)
+    changes: Changes | None = None
+    change_artifact: str | None = None
+    rework: StagePlan | None = None
+    rework_done: list[str] = Field(default_factory=list)
+    revisions: dict[str, int] = Field(default_factory=dict)
+    source_gate: str | None = None
+
+
+def start_run(
+    store: Store,
+    goal: str,
+    budget: BudgetConfig,
+    roles_directory: Path | None = None,
+    router: RouterConfig | None = None,
+):
+    # Snapshot user edits for this run; subsequent runs reload the Markdown files.
+    roles = load_roles(roles_directory)
+    required = {
+        "Director",
+        "Game Designer",
+        "Art Director",
+        "Pixel Artist",
+        "Level/Tile Designer",
+        "Programmer",
+        "QA Playtester",
+        "Librarian",
+    }
+    if required - roles.keys():
+        raise ValueError("Missing required roles")
+    run = store.create_run(
+        {
+            "workflow": WORKFLOW,
+            "goal": goal,
+            "budget": budget.model_dump(),
+            "router": (router or load_config().router).model_dump(),
+            "roles": {name: role.model_dump() for name, role in roles.items()},
+        }
+    )
+    Gates(store)
+    return run
+
+
+def mock_plan() -> StagePlan:
+    definitions = [
+        ("brief", None, "G1 Brief"),
+        ("design", "Game Designer", None),
+        ("art", "Art Director", None),
+        ("concept", None, "G2 Concept preview"),
+        ("assets", "Pixel Artist", None),
+        ("contact", None, "G3 Asset contact sheet"),
+        ("level", "Level/Tile Designer", None),
+        ("code", "Programmer", None),
+        ("qa", "QA Playtester", None),
+        ("playtest", None, "G4 Playtest"),
+        ("memory", "Librarian", None),
+        ("final", None, "G5 Final review"),
+    ]
+    return StagePlan(
+        stages=[
+            StageNode(
+                id=ident,
+                role=role,
+                gate=gate,
+                goal=gate or f"Produce mock {role} artifact",
+                depends_on=[definitions[i - 1][0]] if i else [],
+            )
+            for i, (ident, role, gate) in enumerate(definitions)
+        ]
+    )
+
+
+def mock_changes(text: str, records: dict[str, AssetResult]) -> Changes:
+    """Scripted offline Director behavior; unrecognized feedback stays conservative."""
+    lowered = text.casefold()
+    named = [ident for ident in records if ident.casefold() in lowered]
+    if named:
+        target, regen = named, True
+    elif "style" in lowered or "palette" in lowered:
+        target, regen = "style", False
+    elif "level" in lowered or "room" in lowered:
+        target, regen = "level", False
+    else:
+        target, regen = "mechanic", False
+    return Changes(
+        requests=[
+            {
+                "target": target,
+                "instruction": text,
+                "severity": "minor",
+                "scope": "Only the listed targets",
+                "needs_regen": regen,
+            }
+        ]
+    )
+
+
+def mock_replan(changes: Changes) -> StagePlan:
+    stages = []
+    for i, change in enumerate(changes.requests):
+        role = (
+            "Pixel Artist"
+            if change.needs_regen
+            else {
+                "style": "Art Director",
+                "level": "Level/Tile Designer",
+                "mechanic": "Game Designer",
+            }.get(str(change.target), "Art Director")
+        )
+        stages.append(
+            StageNode(
+                id=f"revision-{i}",
+                role=role,
+                goal=change.instruction,
+                depends_on=[f"revision-{i - 1}"] if i else [],
+            )
+        )
+    return StagePlan(stages=stages)
+
+
+def workflow_step(store: Store, run_id: str) -> bool:
+    from spriteforge.mcp.service import ConfirmationRequired
+
+    with write_lock(store.path.parent / f".{run_id}.runtime.lock"):
+        try:
+            return asyncio.run(_step(store, run_id))
+        except ConfirmationRequired:
+            return False
+
+
+async def _step(store: Store, run_id: str) -> bool:
+    run = store.get_run(run_id)
+    if run.config.get("workflow") != WORKFLOW:
+        raise ValueError("Unknown runtime workflow")
+    if run.status in {"completed", "aborted"}:
+        return False
+    gates = Gates(store)
+    if gates.pending(run_id):
+        return False
+    with store.connect() as db:
+        db.execute("CREATE TABLE IF NOT EXISTS agent_flows (run_id TEXT PRIMARY KEY, body TEXT)")
+        row = db.execute("SELECT body FROM agent_flows WHERE run_id=?", (run_id,)).fetchone()
+    flow = (
+        Flow.model_validate_json(row[0])
+        if row
+        else Flow(roles={n: Role.model_validate(r) for n, r in run.config["roles"].items()})
+    )
+    budget = Budget(store, run_id, BudgetConfig.model_validate(run.config["budget"]))
+    assets = Assets(store, run_id, MockImageProvider(budget))
+    memory = KnowledgeStore(store.path.parent / "memory", store, run_id)
+    seed(memory)
+
+    def runtime(role: Role, responses: list, tools=None) -> AgentRuntime:
+        if role.model != "mock":
+            raise ValueError(
+                "The offline workflow requires model: mock; inject a provider in AgentRuntime"
+            )
+        return AgentRuntime(store, run_id, memory, MockLLMProvider(budget, responses), tools)
+
+    def director(responses):
+        return Director(
+            runtime(flow.roles["Director"], responses), flow.roles["Director"], flow.roles
+        )
+
+    def save(kind="workflow.progress", final=False):
+        with store.connect() as db:
+            db.execute(
+                "INSERT OR REPLACE INTO agent_flows VALUES(?,?)", (run_id, flow.model_dump_json())
+            )
+            db.execute(
+                "UPDATE runs SET cursor=cursor+1,status=? WHERE id=?",
+                ("completed" if final else "running", run_id),
+            )
+            store._event(db, run_id, "Director", kind, {"completed": flow.completed})
+
+    if flow.plan is None:
+        flow.plan, ident = await director([mock_plan().model_dump()]).plan(
+            AgentTask(id="initial-plan", goal=run.config["goal"])
+        )
+        flow.outputs["plan"] = ident
+        save("director.planned")
+        return True
+
+    async def execute(stage: StageNode, task_id: str, inputs: list[str], rework=False):
+        role = flow.roles[stage.role]
+        tools, responses = {}, []
+        expected_assets = set(assets.records())
+        if stage.role == "Pixel Artist":
+            allowed = set(flow.revisions) if rework else {"hero", "tile"}
+            expected_assets.update(allowed)
+            for index, ident in enumerate(sorted(allowed)):
+                responses.append(
+                    ChatResult(
+                        tool_calls=[
+                            {
+                                "id": f"image-{index}",
+                                "name": "generate_asset",
+                                "arguments": {
+                                    "asset_id": ident,
+                                    "instruction": stage.goal + " " + ident,
+                                },
+                            }
+                        ]
+                    )
+                )
+            tools["generate_asset"] = Tool(
+                GenerateAsset,
+                AssetResult,
+                lambda request: assets.generate(
+                    request, allowed=allowed, revisions=flow.revisions if rework else None
+                ),
+            )
+        responses.append(
+            RoleOutput(
+                summary=stage.goal + " (offline mock)", asset_ids=sorted(expected_assets)
+            ).model_dump()
+        )
+        result = await Director(
+            runtime(role, responses, tools), flow.roles["Director"], flow.roles
+        ).dispatch(stage, AgentTask(id=task_id, goal=stage.goal, inputs=inputs), RoleOutput)
+        return result.id
+
+    # Handle answered gates before dispatching another stage. All interpretation and
+    # re-planning results are persisted artifacts, and replay has deterministic task ids.
+    answered = next(
+        (g for g in gates.all(run_id) if g.status != "pending" and g.id not in flow.handled), None
+    )
+    if answered:
+        if answered.status == "aborted":
+            return False
+        feedback_artifact = next(
+            a.id for a in store.artifacts(run_id) if a.name == f"feedback/{answered.id}.json"
+        )
+        if answered.status == "changes_requested":
+            changes = mock_changes(answered.response.text, assets.records())
+            flow.changes, flow.change_artifact = await director([changes.model_dump()]).feedback(
+                AgentTask(
+                    id=f"interpret-{answered.id}",
+                    goal=answered.response.text,
+                    inputs=[feedback_artifact],
+                ),
+                set(assets.records()),
+            )
+            flow.source_gate = answered.id
+            flow.handled.append(answered.id)
+            save("director.changes_proposed")
+            gates.open(
+                run_id,
+                new_gate(
+                    answered.stage,
+                    "Confirm parsed change requests",
+                    [flow.change_artifact],
+                    kind="confirm_changes",
+                    parent_id=answered.id,
+                    changes=flow.changes,
+                ),
+            )
+            return True
+        if answered.kind == "confirm_changes":
+            flow.rework, plan_id = await director([mock_replan(flow.changes).model_dump()]).replan(
+                AgentTask(
+                    id=f"replan-{answered.id}",
+                    goal="Re-plan only the confirmed changes",
+                    inputs=[flow.change_artifact, feedback_artifact],
+                ),
+                flow.changes,
+            )
+            flow.outputs[f"replan-{answered.id}"] = plan_id
+            flow.rework_done = []
+            flow.revisions = {
+                ident: assets.records()[ident].version + 1
+                for change in flow.changes.requests
+                if change.needs_regen
+                for ident in change.target
+            }
+            flow.handled.append(answered.id)
+            save("director.replanned")
+            return True
+        flow.completed.append(answered.stage)
+        flow.outputs[f"gate-{answered.stage}"] = feedback_artifact
+        flow.handled.append(answered.id)
+        save()
+        return True
+
+    if flow.rework:
+        stage = Director.ready(flow.rework, set(flow.rework_done))
+        if stage:
+            if stage.gate:
+                raise ValueError("Revision plan must route roles only")
+            ident = await execute(
+                stage, f"rework-{flow.source_gate}-{stage.id}", [flow.change_artifact], rework=True
+            )
+            flow.outputs[f"rework-{flow.source_gate}-{stage.id}"] = ident
+            flow.rework_done.append(stage.id)
+            save()
+            return True
+        original = next(g for g in gates.all(run_id) if g.id == flow.source_gate)
+        flow.rework = None
+        flow.changes = None
+        save("changes.applied")
+        images = [r.artifact_id for r in assets.records().values()]
+        sheet = assets.contact_sheet()
+        gates.open(
+            run_id, new_gate(original.stage, original.title, images + ([sheet] if sheet else []))
+        )
+        return True
+
+    stage = Director.ready(flow.plan, set(flow.completed))
+    if stage is None:
+        save("run.completed", final=True)
+        return False
+    if stage.gate:
+        previous = [g for g in gates.all(run_id) if g.stage == stage.id]
+        # Crash recovery: a proposal saved immediately before opening its confirmation.
+        if flow.source_gate and flow.changes and not flow.rework and previous:
+            gates.open(
+                run_id,
+                new_gate(
+                    stage.id,
+                    "Confirm parsed change requests",
+                    [flow.change_artifact],
+                    kind="confirm_changes",
+                    parent_id=flow.source_gate,
+                    changes=flow.changes,
+                ),
+            )
+        else:
+            images = [r.artifact_id for r in assets.records().values()]
+            sheet = assets.contact_sheet()
+            kwargs = {}
+            if stage.id == "brief":
+                kwargs["form_schema"] = {
+                    "type": "object",
+                    "properties": {"brief": {"type": "string", "title": "Game brief"}},
+                }
+            gates.open(
+                run_id,
+                new_gate(
+                    stage.id,
+                    stage.gate,
+                    images + ([sheet] if sheet else []) + list(flow.outputs.values())[-2:],
+                    **kwargs,
+                ),
+            )
+        return True
+    # Include approved feedback and upstream role outputs explicitly, including
+    # artifacts across intervening gates and confirmed revision artifacts.
+    inputs = list(dict.fromkeys(flow.outputs.values()))
+    flow.outputs[stage.id] = await execute(stage, f"stage-{stage.id}", inputs)
+    flow.completed.append(stage.id)
+    save()
+    return True
+
+
+def advance_until_gate(store: Store, run_id: str) -> None:
+    while workflow_step(store, run_id):
+        if store.get_run(run_id).status == "paused":
+            break

spriteforge/app/agents_view.py

@@ -0,0 +1,248 @@
+"""The studio's view of a run as a team of agents, derived from the append-only journal (events
+and gates): who works in which order, what each produced and cost, and each agent's thread."""
+
+import re
+
+from pydantic import BaseModel
+
+from spriteforge.core.cost import ALLOWANCE_EVENTS
+from spriteforge.core.gates import Gate, Gates
+from spriteforge.core.state import Event, Store
+from spriteforge.core.team import AGENTS
+from spriteforge.stages.chat_changes import changes
+
+# The agents whose work a gate reviews (the Director's chat shows every gate as well).
+GATE_OWNERS = {
+    "design": ["Game Designer"],
+    "concept": ["Art Director"],
+    "assets": ["Art Director", "Pixel Artist"],
+    "gameplay": ["Art Director", "Pixel Artist"],
+    "menus": ["Menu Designer"],
+    "playtest": ["Programmer", "QA Playtester"],
+    "final": ["Librarian"],
+}
+
+# The Director narrates steps that other agents do ("build v1: the Programmer is writing the
+# game"); the first matching pattern names the agent at work.
+NARRATION = [
+    (r"Art Reviewer|vision review", "Art Reviewer"),
+    (r"Programmer|attempt \d+", "Programmer"),
+    (r"menu", "Menu Designer"),
+    (r"art \(|blocking issue", "Pixel Artist"),
+    (r"playing the game|recording|QA|tests?\b", "QA Playtester"),
+]
+
+# Journal noise that is not an agent's own work (each memory read, the cost ledger).
+QUIET = {"memory.retrieved", "cost.reserved", "cost.succeeded", "cost.failed",
+         # Chat and its bookkeeping: talking about the work is not doing it.
+         "chat.user", "chat.agent", "chat.applied", "chat.unapplied", "rewind.declined",
+         "run.stop_requested", "run.stop_cleared", "round.superseded", "round.rewound",
+         "round.replanned",
+         # A plan or report is about the work (an agent's plan comes before it starts).
+         "agent.report"}
+RUN_EVENTS = {"run.created", "run.failed", "run.completed", "run.retry_requested", "game.built",
+              "run.paused"}
+
+
+def owners(gate: Gate) -> list[str]:
+    """The Director, the agents whose work the gate reviews and the agents asking for it."""
+    return list(dict.fromkeys(["Director", *GATE_OWNERS.get(gate.stage, []), *gate.agents]))
+
+
+def actor(event: Event) -> str | None:
+    """The agent whose work this event is, or None (the human, the ledger, memory reads)."""
+    if event.type == "cost.reserved":
+        return event.payload.get("agent")
+    if event.type in QUIET or event.agent not in AGENTS:
+        return None
+    if event.agent == "Director" and event.type == "game.progress":
+        message = str(event.payload.get("message", ""))
+        return next((a for p, a in NARRATION if re.search(p, message)), "Director")
+    return event.agent
+
+
+class AgentSummary(BaseModel):
+    name: str
+    status: str  # "waiting" | "working" | "needs_you" | "done"
+    needs_you: int  # open gates this agent's chat holds
+    artifacts: int
+    calls: int
+    images: int
+    cost: float
+    allowance: float  # what it spent since the human's last action (its cap: budget.max_agent_cost)
+    last: str | None  # its latest progress message
+
+
+def summarize(store: Store, run_id: str, busy: bool) -> list[AgentSummary]:
+    """`busy`: a worker is stepping this run now (so its latest actor is working)."""
+    stats = {
+        a: {"artifacts": 0, "calls": 0, "images": 0, "cost": 0.0, "allowance": 0.0, "last": None}
+        for a in AGENTS
+    }
+    seen, attempts, current = set(), {}, None
+    for event in store.events(run_id):
+        who = actor(event)
+        if event.type in ALLOWANCE_EVENTS:  # a human action: every agent's allowance restarts
+            for s in stats.values():
+                s["allowance"] = 0.0
+        if event.type == "cost.reserved":
+            # Calls booked before agents were recorded go to whoever was working then.
+            attempts[event.payload["attempt_id"]] = who or current or "Director"
+        elif event.type in {"cost.succeeded", "cost.failed"}:
+            usage = event.payload["usage"]
+            agent = attempts.get(event.payload["attempt_id"])
+            if agent in stats and event.type == "cost.succeeded":
+                stats[agent]["calls"] += 1
+                stats[agent]["images"] += bool(usage.get("image"))
+                stats[agent]["cost"] += usage.get("estimated_cost") or 0.0
+                stats[agent]["allowance"] += usage.get("estimated_cost") or 0.0
+        if who:
+            seen.add(who)
+            current = who
+            if event.type == "artifact.created":
+                stats[who]["artifacts"] += 1
+            elif event.type == "game.progress":
+                stats[who]["last"] = event.payload.get("message")
+    gate = Gates(store).pending(run_id)
+    waiting_on = set(owners(gate)) if gate else set()
+    result = []
+    for name in AGENTS:
+        if name in waiting_on:
+            status = "needs_you"
+        elif busy and not gate and name == current:
+            status = "working"
+        elif name in seen:
+            status = "done"
+        else:
+            status = "waiting"
+        result.append(
+            AgentSummary(
+                name=name,
+                status=status,
+                needs_you=int(name in waiting_on),
+                **{**stats[name], "cost": round(stats[name]["cost"], 6),
+                   "allowance": round(stats[name]["allowance"], 6)},
+            )
+        )
+    return result
+
+
+def item(event: Event, kind: str, **fields) -> dict:
+    return {"id": event.id, "at": event.timestamp, "agent": event.agent, "kind": kind, **fields}
+
+
+def thread(store: Store, run_id: str, agent: str, after: int = 0) -> list[dict]:
+    """The agent's chat as one timeline: its messages, progress, artifacts and the gates that
+    review its work. The Director's thread is the run's timeline: every agent's progress, every
+    gate and the run's milestones."""
+    director = agent == "Director"
+    gates = {g.id: g for g in Gates(store).all(run_id)}
+    metas = artifact_metas(store, run_id)
+    by_name = {m["name"]: m for m in metas.values()}
+
+    def readable(meta):  # a JSON record is shown as the Markdown its agent wrote with it
+        twin = by_name.get(meta["name"].removesuffix(".json") + ".md")
+        return twin if meta["mime"] == "application/json" and twin else meta
+
+    applied = {c["id"]: c["applied"] for c in changes(store, run_id)}
+    offers = go_back_states(store, run_id)
+    items = []
+    for event in store.events(run_id, after):
+        kind, payload = event.type, event.payload
+        if kind == "chat.user" and payload.get("to") == agent:
+            fields = chat_fields(payload)
+            if event.id in applied:  # a filed change: queued until a step takes it
+                fields["status"] = "applied" if applied[event.id] else "queued"
+            items.append(item(event, "chat", role="user", **fields))
+        elif kind == "chat.agent" and event.agent == agent:
+            fields = chat_fields(payload)
+            if "rewind" in payload:
+                fields["rewind"] = {**payload["rewind"], "state": offers.get(event.id, "open")}
+            items.append(item(event, "chat", role="agent", **fields))
+        elif kind == "agent.report" and event.agent == agent:
+            items.append(item(event, "report", report=payload))
+        elif kind == "reference.added" and payload.get("agent") in (agent, "Director"):
+            # The Director's references are every agent's: shown in every chat.
+            items.append(item(event, "reference", reference=payload))
+        elif kind == "round.rewound" and director:
+            items.append(item(event, "run", type=kind, message=payload.get("message")))
+        elif kind in {"gate.opened", "gate.responded"}:
+            gate = gates.get(payload.get("id"))
+            if gate is None or agent not in owners(gate):
+                continue
+            if kind == "gate.opened":
+                shown = [readable(metas[i]) for i in gate.artifacts_to_show if i in metas]
+                items.append(
+                    item(event, "gate", gate=gate.model_dump(mode="json"), artifacts=shown)
+                )
+            else:
+                response = Gate.model_validate(payload).response
+                items.append(
+                    item(
+                        event,
+                        "gate_response",
+                        gate_id=gate.id,
+                        title=gate.title,
+                        status=payload.get("status"),
+                        text=response.text if response else "",
+                        chat=len((response.form if response else {}).get("chat_changes") or []),
+                    )
+                )
+        elif kind == "agent.tool" and event.agent == agent:
+            items.append(item(event, "progress", text=tool_text(payload)))
+        elif kind == "game.progress" and (director or actor(event) == agent):
+            items.append(item(event, "progress", text=str(payload.get("message", ""))))
+        elif kind == "artifact.created" and event.agent == agent:
+            fields = {k: payload.get(k) for k in ("id", "name", "mime")}
+            items.append(item(event, "artifact", artifact=fields))
+        elif director and kind in RUN_EVENTS:
+            items.append(item(event, "run", type=kind, message=payload.get("message")))
+    return items
+
+
+def artifact_metas(store: Store, run_id: str) -> dict[str, dict]:
+    """id -> {id, name, mime} of every artifact of the run, without loading the data."""
+    with store.connect() as db:
+        rows = db.execute("SELECT id,name,mime FROM artifacts WHERE run_id=?", (run_id,))
+        return {r["id"]: dict(r) for r in rows}
+
+
+def go_back_states(store: Store, run_id: str) -> dict[int, str]:
+    """Each Go back card's state: "open", "going_back" (stop requested), "went_back" (the round
+    started again), "queued" (Queue for later) or "expired" (the round reached its gate or was
+    redone before an answer)."""
+    stops, declined, out, cards = {}, set(), {}, []
+    rewound, opened = [], []
+    for e in store.events(run_id):
+        if e.type == "chat.agent" and "rewind" in e.payload:
+            cards.append((e.id, e.payload["rewind"]["change"]))
+        elif e.type == "run.stop_requested":
+            stops.update(dict.fromkeys(e.payload.get("changes", []), e.id))
+        elif e.type == "rewind.declined":
+            declined.add(e.payload.get("change"))
+        elif e.type == "round.rewound":
+            rewound.append(e.id)
+        elif e.type == "gate.opened":
+            opened.append(e.id)
+    for card, change in cards:
+        if change in stops:
+            out[card] = "went_back" if any(r > stops[change] for r in rewound) else "going_back"
+        elif change in declined:
+            out[card] = "queued"
+        elif any(i > card for i in rewound + opened):
+            out[card] = "expired"
+    return out
+
+
+def tool_text(payload: dict) -> str:
+    """An agent's tool call as a line of its chat: 'Looked up with library.library_search
+    (query: slime)'."""
+    args = ", ".join(f"{k}: {v}" for k, v in (payload.get("arguments") or {}).items()
+                     if str(v).strip())[:120]  # fmt: skip
+    failed = "" if payload.get("ok", True) else " (it failed)"
+    return f"Looked up with {payload.get('tool', 'a tool')}" + (f" ({args})" if args else "") + failed
+
+
+def chat_fields(payload: dict) -> dict:
+    keys = ("text", "intent", "status", "error")
+    return {k: payload[k] for k in keys if k in payload}