spriteforge 0.1.1__py3-none-any.whl

spriteforge/mcp/service.py

@@ -0,0 +1,224 @@
+"""Durable one-shot tool confirmations and role-enforced invocation."""
+
+import hashlib
+import json
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from spriteforge.agents.cancellation import check_active
+from spriteforge.core.security import redact
+
+from .client import MCPClient
+from .registry import Registry
+
+
+class ConfirmationRequired(Exception):
+    def __init__(self, ident):
+        self.ident = ident
+        super().__init__(f"Human confirmation required: {ident}")
+
+
+class CallIntent(BaseModel):
+    id: str
+    role: str
+    tool: str
+    arguments: dict = Field(default_factory=dict)
+    fingerprint: str
+    prior_status: str
+
+
+class MCPService:
+    def __init__(self, store, client=None):
+        self.store = store
+        self.registry = Registry(store.path.parent)
+        self.client = client or MCPClient()
+        with store.connect() as db:
+            db.execute("""CREATE TABLE IF NOT EXISTS mcp_calls (
+                run_id TEXT, id TEXT, intent TEXT, status TEXT, result TEXT,
+                PRIMARY KEY(run_id,id))""")
+
+    async def discover(self, name):
+        server = self.registry.read().mcpServers[name]
+        tools = await self.client.discover(server)
+        self.registry.discovered(name, server.fingerprint(), tools)
+        return tools
+
+    def pending(self, run_id):
+        with self.store.connect() as db:
+            return [
+                {**json.loads(r["intent"]), "status": r["status"]}
+                for r in db.execute(
+                    "SELECT intent,status FROM mcp_calls WHERE run_id=? AND status='pending'",
+                    (run_id,),
+                )
+            ]
+
+    def row(self, run_id, ident):
+        with self.store.connect() as db:
+            row = db.execute(
+                "SELECT * FROM mcp_calls WHERE run_id=? AND id=?", (run_id, ident)
+            ).fetchone()
+        return dict(row) if row else None
+
+    def authorize(self, role, tool):
+        allowed = self.registry.allowed(role)
+        if tool not in allowed:
+            raise PermissionError(f"MCP tool not enabled for {role.name}: {tool}")
+        return allowed[tool]
+
+    async def call(self, run_id, role, tool, arguments, ident=None):
+        ident = ident or uuid4().hex
+        check_active()
+        self.store.append_event(
+            run_id, role.name, "mcp.attempted", {"id": ident, "tool": tool, "arguments": arguments}
+        )
+        try:
+            server, definition = self.authorize(role, tool)
+        except PermissionError:
+            self.store.append_event(
+                run_id, role.name, "mcp.denied", {"tool": tool, "arguments": arguments}
+            )
+            raise
+        # Persist only secret-free intent. Credentials are supplied via server env/header bindings.
+        if redact(arguments) != arguments:
+            raise ValueError("MCP arguments contain secrets; use server environment bindings")
+        from jsonschema import Draft202012Validator
+        from referencing import Registry as SchemaRegistry
+
+        Draft202012Validator(definition.get("inputSchema", {}), registry=SchemaRegistry()).validate(
+            arguments
+        )
+        fingerprint = hashlib.sha256(
+            (server.fingerprint() + json.dumps(definition, sort_keys=True)).encode()
+        ).hexdigest()
+        row = self.row(run_id, ident)
+        if row:
+            intent = CallIntent.model_validate_json(row["intent"])
+            if (intent.role, intent.tool, intent.arguments, intent.fingerprint) != (
+                role.name,
+                tool,
+                arguments,
+                fingerprint,
+            ):
+                raise PermissionError("MCP call changed since confirmation")
+            if row["status"] == "succeeded":
+                return json.loads(row["result"])
+            if row["status"] == "denied":
+                return {
+                    "isError": True,
+                    "content": [{"type": "text", "text": "Human denied this tool call."}],
+                }
+            if row["status"] == "pending":
+                raise ConfirmationRequired(ident)
+            raise PermissionError(f"MCP call cannot replay from {row['status']}")
+        run = self.store.get_run(run_id)
+        if run.status in {"completed", "aborted", "failed"}:
+            raise ValueError("Run is not active")
+        intent = CallIntent(
+            id=ident,
+            role=role.name,
+            tool=tool,
+            arguments=arguments,
+            fingerprint=fingerprint,
+            prior_status=run.status,
+        )
+        confirm = server.confirmation.get(definition["name"], True)
+        with self.store.connect() as db:
+            db.execute(
+                "INSERT INTO mcp_calls VALUES(?,?,?,?,NULL)",
+                (run_id, ident, intent.model_dump_json(), "pending" if confirm else "approved"),
+            )
+            self.store._event(db, run_id, role.name, "mcp.requested", intent.model_dump())
+            if confirm:
+                db.execute("UPDATE runs SET status='paused' WHERE id=?", (run_id,))
+        if confirm:
+            raise ConfirmationRequired(ident)
+        return await self.execute(run_id, ident, role)
+
+    async def respond(self, run_id, ident, approve, role):
+        with self.store.connect() as db:
+            changed = db.execute(
+                "UPDATE mcp_calls SET status=? WHERE run_id=? AND id=? AND status='pending'",
+                ("approved" if approve else "denied", run_id, ident),
+            )
+            if not changed.rowcount:
+                raise ValueError("Confirmation already answered or missing")
+            self.store._event(
+                db, run_id, "Human", "mcp.confirmed" if approve else "mcp.rejected", {"id": ident}
+            )
+        if not approve:
+            self.restore(run_id, ident)
+            return {"denied": True}
+        try:
+            return await self.execute(run_id, ident, role)
+        finally:
+            self.restore(run_id, ident)
+
+    def restore(self, run_id, ident):
+        intent = CallIntent.model_validate_json(self.row(run_id, ident)["intent"])
+        if not self.pending(run_id):
+            with self.store.connect() as db:
+                db.execute(
+                    "UPDATE runs SET status=? WHERE id=? AND status='paused'",
+                    (intent.prior_status, run_id),
+                )
+
+    async def execute(self, run_id, ident, role):
+        if self.store.get_run(run_id).status in {"completed", "aborted", "failed"}:
+            raise PermissionError("Run is no longer active")
+        intent = CallIntent.model_validate_json(self.row(run_id, ident)["intent"])
+        server, definition = self.authorize(role, intent.tool)
+        fingerprint = hashlib.sha256(
+            (server.fingerprint() + json.dumps(definition, sort_keys=True)).encode()
+        ).hexdigest()
+        if intent.role != role.name or intent.fingerprint != fingerprint:
+            raise PermissionError("Server, role or tool changed after confirmation")
+        check_active()
+        with self.store.connect() as db:
+            changed = db.execute(
+                "UPDATE mcp_calls SET status='running' WHERE run_id=? AND id=? AND status='approved'",
+                (run_id, ident),
+            )
+            if not changed.rowcount:
+                raise PermissionError("Confirmation already consumed")
+            self.store._event(
+                db,
+                run_id,
+                role.name,
+                "mcp.called",
+                {"id": ident, "tool": intent.tool, "arguments": intent.arguments},
+            )
+        try:
+            from spriteforge.config import BudgetConfig
+            from spriteforge.core.cost import Budget
+
+            config = BudgetConfig.model_validate(
+                self.store.get_run(run_id).config.get("budget", {})
+            )
+            with Budget(self.store, run_id, config).attempt("mcp", intent.tool.split(".", 1)[0]):
+                result = redact(
+                    await self.client.call(server, definition["name"], intent.arguments)
+                )
+        except BaseException as exc:
+            with self.store.connect() as db:
+                db.execute(
+                    "UPDATE mcp_calls SET status='failed' WHERE run_id=? AND id=?", (run_id, ident)
+                )
+                self.store._event(
+                    db, run_id, role.name, "mcp.failed", {"id": ident, "error": type(exc).__name__}
+                )
+            raise
+        with self.store.connect() as db:
+            db.execute(
+                "UPDATE mcp_calls SET status='succeeded',result=? WHERE run_id=? AND id=?",
+                (json.dumps(result), run_id, ident),
+            )
+            self.store._event(
+                db,
+                run_id,
+                role.name,
+                "mcp.completed",
+                {"id": ident, "tool": intent.tool, "isError": result.get("isError", False)},
+            )
+        return result

spriteforge/mcp/templates/context7.json

@@ -0,0 +1,6 @@
+{
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@upstash/context7-mcp"],
+  "enabled_roles": {}
+}

spriteforge/mcp/templates/fetch.json

@@ -0,0 +1,6 @@
+{
+  "transport": "stdio",
+  "command": "uvx",
+  "args": ["mcp-server-fetch", "--no-readability-js"],
+  "enabled_roles": {}
+}

spriteforge/mcp/templates/filesystem-read.json

@@ -0,0 +1,6 @@
+{
+  "transport": "stdio",
+  "command": "python",
+  "args": ["-m", "spriteforge.mcp.filesystem_read", "workspace/runs"],
+  "enabled_roles": {}
+}

spriteforge/mcp/templates/pixel-tools.json

@@ -0,0 +1,6 @@
+{
+  "transport": "stdio",
+  "command": "python",
+  "args": ["-m", "spriteforge.mcp.pixel_tools", "workspace"],
+  "enabled_roles": {}
+}

spriteforge/memory/README.md

@@ -0,0 +1,10 @@
+# Memory safety boundary
+
+Secret detection uses heuristics, not guarantees. Known environment credentials,
+bearer tokens, private-key headers, and credential-style assignments are rejected;
+arbitrary or unlabeled secrets may pass these checks.
+
+Redaction happens at the source before the Librarian sees run data. Producers must
+redact run events, tool results, and artifacts before including them in a Librarian
+request. The memory writer's detection is a second check, not a replacement for
+source redaction. Never submit API keys or secrets as knowledge.

spriteforge/memory/cli.py

@@ -0,0 +1,131 @@
+from pathlib import Path
+
+import typer
+
+from spriteforge.core.credentials import load_credentials
+
+from .okf.seed import seed
+from .okf.store import KnowledgeStore
+from .okf.validate import validate as validate_corpus
+
+app = typer.Typer(no_args_is_help=True, help="Local OKF knowledge and retrieval.")
+
+
+def open_store(workspace: Path) -> KnowledgeStore:
+    load_credentials()
+    store = KnowledgeStore(workspace / "memory")
+    if not store.scan()[1]:
+        seed(store)
+    return store
+
+
+@app.command("sync-catalog")
+def sync_catalog_command(workspace: Path = Path("workspace")):
+    """Mirror asset packs, tile sets and actors into memory under catalog/ (one commit)."""
+    from .okf.catalog import sync_catalog
+
+    result = sync_catalog(open_store(workspace))
+    typer.echo(
+        f"catalog: {result['total']} entries, {result['updated']} written, "
+        f"{result['deprecated']} deprecated"
+    )
+
+
+@app.command()
+def init(workspace: Path = Path("workspace")):
+    """Initialize the local Git corpus and seed library without overwriting entries."""
+    store = open_store(workspace)
+    typer.echo(f"Knowledge corpus: {store.root}")
+
+
+@app.command()
+def search(
+    query: str,
+    workspace: Path = Path("workspace"),
+    scope: list[str] | None = None,
+    token_budget: int = 1024,
+    min_score: float | None = None,
+    relative_score: float | None = None,
+    verbose: bool = False,
+):
+    """Return ranked snippets with trust tiers and path-derived IDs."""
+    store = open_store(workspace)
+    for snippet in store.retrieve(
+        query, scope, token_budget, min_score=min_score, relative_score=relative_score
+    ):
+        flags = "; bootstrap, unreviewed" if snippet.bootstrap_unreviewed else ""
+        flags += " STALE" if snippet.stale else ""
+        if snippet.status != "stable":
+            flags += " " + snippet.status.upper()
+        if verbose:
+            flags += f" score={snippet.score:.3f}"
+        typer.echo(f"[{snippet.trust_tier}{flags}] {snippet.id}: {snippet.title}\n{snippet.text}\n")
+
+
+@app.command("validate")
+def validate_command(workspace: Path = Path("workspace")):
+    """Validate local OKF and run the optional external `okf validate` tool."""
+    report = validate_corpus(open_store(workspace))
+    for issue in report.errors:
+        typer.echo(f"ERROR: {issue}")
+    for issue in report.warnings:
+        typer.echo(f"WARNING: {issue}")
+    typer.echo(f"External okf: {report.external}")
+    typer.echo("PASS" if not report.errors else "FAIL")
+    if report.errors:
+        raise typer.Exit(1)
+
+
+@app.command()
+def index(directory: str = "", workspace: Path = Path("workspace"), scope: list[str] | None = None):
+    """List summaries before selecting a full entry."""
+    typer.echo(open_store(workspace).index(directory, scope))
+
+
+@app.command()
+def show(id: str, workspace: Path = Path("workspace"), scope: list[str] | None = None):
+    """Load one full concept after search/index discovery."""
+    from .okf.codec import serialize
+
+    typer.echo(serialize(open_store(workspace).show(id, scope)))
+
+
+@app.command()
+def promote(id: str, by: str, workspace: Path = Path("workspace")):
+    """Explicit human sign-off; agent edits subsequently clear this verification."""
+    open_store(workspace).promote(id, by if by.startswith("human:") else "human:" + by)
+    typer.echo(f"Human verification recorded for {id}")
+
+
+@app.command()
+def export(destination: Path, workspace: Path = Path("workspace")):
+    """Export public concepts and fresh indexes, excluding private data and Git history."""
+    open_store(workspace).export_public(destination)
+    typer.echo(f"Public knowledge exported to {destination}")
+
+
+@app.command()
+def mcp(workspace: Path = Path("workspace"), allow_private: bool = False):
+    """Expose read-only corpus tools over MCP stdio; stdout is protocol-only."""
+    from spriteforge.mcp.memory import create_server
+
+    create_server(open_store(workspace), allow_private=allow_private).run(transport="stdio")
+
+
+@app.command()
+def review(
+    id: str | None = typer.Argument(None),
+    confirm: bool = False,
+    workspace: Path = Path("workspace"),
+):
+    """List bootstrap entries awaiting review, or explicitly confirm one."""
+    store = open_store(workspace)
+    if id:
+        if not confirm:
+            raise typer.BadParameter("Review requires --confirm")
+        store.review(id)
+        typer.echo(f"Review recorded for {id}")
+    else:
+        for entry in store.scan()[0]:
+            if entry.metadata.model_extra.get("x-spriteforge-review") == "unreviewed":
+                typer.echo(f"{entry.id}: {entry.title} [bootstrap, unreviewed]")

spriteforge/memory/okf/__init__.py

@@ -0,0 +1 @@
+"""Google OKF v0.2 Markdown knowledge with local search and auditable writes."""