groundcrew 0.1.0__py3-none-any.whl

groundcrew/__init__.py

@@ -0,0 +1,22 @@
+"""groundcrew — Deterministic state oracle and semantic action codec for computer-use agents."""
+
+from __future__ import annotations
+
+from importlib.metadata import version as _version
+
+from groundcrew.codec import ActionReceipt, ActionSpec
+from groundcrew.oracle import Oracle, ReceiptStore
+from groundcrew.snapshot import FileState, SnapshotDiff, StateSnapshot
+
+__version__ = _version("groundcrew")
+
+__all__ = [
+    "ActionReceipt",
+    "ActionSpec",
+    "FileState",
+    "Oracle",
+    "ReceiptStore",
+    "SnapshotDiff",
+    "StateSnapshot",
+    "__version__",
+]

groundcrew/api.py

@@ -0,0 +1,110 @@
+"""FastAPI REST wrapper for groundcrew.
+
+Start:   uvicorn groundcrew.api:app --reload
+Install: pip install "groundcrew[api]"
+Docs:    http://localhost:8000/docs
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from typing import Any
+
+try:
+    from fastapi import FastAPI, HTTPException
+    from pydantic import BaseModel, Field
+except ImportError as exc:
+    raise ImportError("API server requires: pip install 'groundcrew[api]'") from exc
+
+from groundcrew import __version__
+from groundcrew.codec import ActionSpec
+from groundcrew.oracle import Oracle, ReceiptStore
+
+_DEFAULT_DB = ".groundcrew/receipts.db"
+
+
+def _db_path() -> str:
+    return os.environ.get("GROUNDCREW_DB", _DEFAULT_DB)
+
+
+app = FastAPI(
+    title="groundcrew API",
+    description="Deterministic state oracle and semantic action codec for computer-use agents",
+    version=__version__,
+    license_info={
+        "name": "MIT",
+        "url": "https://github.com/sandeep-alluru/groundcrew/blob/main/LICENSE",
+    },
+)
+
+
+class CaptureRequest(BaseModel):
+    """Request body for POST /capture."""
+
+    root: str = Field(".", description="Directory to snapshot.")
+    verb: str = Field(..., description="Semantic verb for the action.")
+    target: str = Field(..., description="Target the action acts upon.")
+    params: dict = Field(default_factory=dict)
+    run_cmd: str | None = Field(None, description="Optional shell command to execute.")
+
+
+class HealthResponse(BaseModel):
+    """Response body for GET /health."""
+
+    status: str
+    version: str
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health() -> dict[str, str]:
+    """Liveness probe."""
+    return {"status": "ok", "version": __version__}
+
+
+@app.post("/capture")
+async def capture(request: CaptureRequest) -> Any:
+    """Capture before/after state around an action and persist a receipt."""
+    spec = ActionSpec(verb=request.verb, target=request.target, params=request.params)
+    with Oracle(request.root, spec) as oracle:
+        if request.run_cmd:
+            result = subprocess.run(shlex.split(request.run_cmd), cwd=request.root, check=False)  # noqa: S603
+            if result.returncode != 0:
+                oracle._success = False
+    receipt = oracle.record(spec)
+    store = ReceiptStore(_db_path())
+    store.save(receipt)
+    store.close()
+    return receipt.to_dict()
+
+
+@app.get("/receipt/{receipt_id}")
+async def get_receipt(receipt_id: str) -> Any:
+    """Return a single receipt by ID."""
+    store = ReceiptStore(_db_path())
+    receipt = store.get(receipt_id)
+    store.close()
+    if receipt is None:
+        raise HTTPException(status_code=404, detail=f"Receipt not found: {receipt_id}")
+    return receipt.to_dict()
+
+
+@app.get("/receipts")
+async def list_receipts() -> Any:
+    """Return all stored receipts."""
+    store = ReceiptStore(_db_path())
+    receipts = store.list_receipts()
+    store.close()
+    return {"receipts": [r.to_dict() for r in receipts]}
+
+
+@app.get("/diff/{receipt_id}")
+async def get_diff(receipt_id: str) -> Any:
+    """Return the snapshot diff for a stored receipt."""
+    store = ReceiptStore(_db_path())
+    receipt = store.get(receipt_id)
+    store.close()
+    if receipt is None:
+        raise HTTPException(status_code=404, detail=f"Receipt not found: {receipt_id}")
+    return receipt.diff.to_dict()

groundcrew/cli.py

@@ -0,0 +1,113 @@
+"""Command-line interface for groundcrew."""
+
+from __future__ import annotations
+
+import subprocess
+
+import click
+
+from groundcrew.codec import ActionSpec
+from groundcrew.oracle import Oracle, ReceiptStore
+from groundcrew.report import print_diff, print_receipt, to_markdown
+
+_DEFAULT_DB = ".groundcrew/receipts.db"
+
+
+@click.group()
+@click.version_option(package_name="groundcrew")
+@click.option(
+    "--db",
+    default=_DEFAULT_DB,
+    show_default=True,
+    help="Path to the groundcrew receipt store.",
+    envvar="GROUNDCREW_DB",
+)
+@click.pass_context
+def main(ctx: click.Context, db: str) -> None:
+    """Deterministic state oracle and semantic action codec for computer-use agents.
+
+    groundcrew captures the filesystem state before and after an action,
+    and emits a verifiable, content-addressed receipt of what changed.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["db"] = db
+
+
+@main.command()
+@click.option("--root", default=".", show_default=True, help="Directory to snapshot.")
+@click.option("--verb", required=True, help="Semantic verb for the action.")
+@click.option("--target", required=True, help="Target the action acts upon.")
+@click.option("--run", "run_cmd", default=None, help="Shell command to execute and capture.")
+@click.pass_context
+def capture(ctx: click.Context, root: str, verb: str, target: str, run_cmd: str | None) -> None:
+    """Capture before/after state around an action and store a receipt.
+
+    \b
+    Examples:
+      groundcrew capture --root . --verb write --target out.txt --run "echo hi > out.txt"
+    """
+    spec = ActionSpec(verb=verb, target=target, params={"run": run_cmd} if run_cmd else {})
+    with Oracle(root, spec) as oracle:
+        if run_cmd:
+            result = subprocess.run(run_cmd, shell=True, cwd=root)  # noqa: S602
+            if result.returncode != 0:
+                oracle._success = False
+    receipt = oracle.record(spec)
+    store = ReceiptStore(ctx.obj["db"])
+    store.save(receipt)
+    store.close()
+    click.echo(f"Captured receipt {receipt.id}  {verb} -> {target}")
+    print_receipt(receipt)
+
+
+@main.command()
+@click.argument("receipt_id")
+@click.pass_context
+def diff(ctx: click.Context, receipt_id: str) -> None:
+    """Show the diff for a stored receipt.
+
+    \b
+    Examples:
+      groundcrew diff abc123def456
+    """
+    store = ReceiptStore(ctx.obj["db"])
+    receipt = store.get(receipt_id)
+    store.close()
+    if receipt is None:
+        raise click.ClickException(f"Receipt not found: {receipt_id}")
+    print_diff(receipt.diff)
+
+
+@main.command()
+@click.pass_context
+def log(ctx: click.Context) -> None:
+    """List all stored receipts.
+
+    \b
+    Examples:
+      groundcrew log
+    """
+    store = ReceiptStore(ctx.obj["db"])
+    receipts = store.list_receipts()
+    store.close()
+    click.echo(to_markdown(receipts))
+
+
+@main.command()
+@click.option("--root", default=".", show_default=True, help="Directory to inspect.")
+@click.pass_context
+def status(ctx: click.Context, root: str) -> None:
+    """Show the current staging state (a live snapshot of the root)."""
+    from groundcrew.snapshot import StateSnapshot
+
+    snap = StateSnapshot.capture(root)
+    store = ReceiptStore(ctx.obj["db"])
+    count = len(store.list_receipts())
+    store.close()
+    click.echo(f"Root      {snap.root}")
+    click.echo(f"Snapshot  {snap.id}  ({len(snap.files)} files)")
+    click.echo(f"Receipts  {count} stored")
+
+
+if __name__ == "__main__":
+    main()

groundcrew/codec.py

@@ -0,0 +1,85 @@
+"""Semantic action codec: content-addressed action specs and verifiable receipts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+from groundcrew.snapshot import SnapshotDiff
+
+
+@dataclass
+class ActionSpec:
+    """A semantic description of an action: a verb applied to a target with params."""
+
+    verb: str
+    target: str
+    params: dict
+    id: str = field(init=False)
+
+    def __post_init__(self):
+        payload = f"{self.verb}|{self.target}|{json.dumps(self.params, sort_keys=True)}"
+        self.id = hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "verb": self.verb,
+            "target": self.target,
+            "params": self.params,
+        }
+
+    @classmethod
+    def from_dict(cls, d) -> ActionSpec:
+        return cls(verb=d["verb"], target=d["target"], params=d["params"])
+
+
+@dataclass
+class ActionReceipt:
+    """A verifiable record pairing an action spec with the state change it produced."""
+
+    spec: ActionSpec
+    before_id: str
+    after_id: str
+    diff: SnapshotDiff
+    success: bool
+    timestamp: float
+    id: str = field(init=False)
+
+    def __post_init__(self):
+        payload = json.dumps(
+            {
+                "spec_id": self.spec.id,
+                "before_id": self.before_id,
+                "after_id": self.after_id,
+                "success": self.success,
+                "timestamp": self.timestamp,
+            },
+            sort_keys=True,
+        )
+        self.id = hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "spec": self.spec.to_dict(),
+            "before_id": self.before_id,
+            "after_id": self.after_id,
+            "diff": self.diff.to_dict(),
+            "success": self.success,
+            "timestamp": self.timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, d) -> ActionReceipt:
+        spec = ActionSpec.from_dict(d["spec"])
+        diff = SnapshotDiff.from_dict(d["diff"])
+        return cls(
+            spec=spec,
+            before_id=d["before_id"],
+            after_id=d["after_id"],
+            diff=diff,
+            success=d["success"],
+            timestamp=d["timestamp"],
+        )

groundcrew/mcp_server.py

@@ -0,0 +1,154 @@
+"""MCP server for groundcrew.
+
+Start:  python -m groundcrew.mcp_server
+Or:     groundcrew-mcp
+
+Add to Claude Desktop (~/.config/claude/claude_desktop_config.json):
+    {
+        "mcpServers": {
+            "groundcrew": {
+                "command": "groundcrew-mcp"
+            }
+        }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+from typing import Any
+
+from groundcrew.codec import ActionSpec
+from groundcrew.oracle import Oracle, ReceiptStore
+
+_DEFAULT_DB = ".groundcrew/receipts.db"
+
+
+def _db_path() -> str:
+    return os.environ.get("GROUNDCREW_DB", _DEFAULT_DB)
+
+
+def _require_mcp() -> Any:
+    try:
+        import mcp.server.stdio
+        import mcp.types as types
+        from mcp.server import Server
+
+        return mcp, types, Server
+    except ImportError:
+        print(
+            "MCP server requires: pip install 'groundcrew[mcp]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _capture_state(arguments: str) -> str:
+    args = json.loads(arguments) if arguments else {}
+    root = args.get("root", ".")
+    verb = args.get("verb", "act")
+    target = args.get("target", "")
+    params = args.get("params", {})
+    run_cmd = args.get("run_cmd")
+    spec = ActionSpec(verb=verb, target=target, params=params)
+    with Oracle(root, spec) as oracle:
+        if run_cmd:
+            result = subprocess.run(shlex.split(run_cmd), cwd=root, check=False)  # noqa: S603
+            if result.returncode != 0:
+                oracle._success = False
+    receipt = oracle.record(spec)
+    store = ReceiptStore(_db_path())
+    store.save(receipt)
+    store.close()
+    return json.dumps(receipt.to_dict())
+
+
+def _get_receipt(arguments: str) -> str:
+    args = json.loads(arguments) if arguments else {}
+    receipt_id = args.get("receipt_id", "")
+    store = ReceiptStore(_db_path())
+    receipt = store.get(receipt_id)
+    store.close()
+    if receipt is None:
+        return json.dumps({"error": f"Receipt not found: {receipt_id}"})
+    return json.dumps(receipt.to_dict())
+
+
+def _list_receipts(arguments: str) -> str:
+    store = ReceiptStore(_db_path())
+    receipts = store.list_receipts()
+    store.close()
+    return json.dumps({"receipts": [r.to_dict() for r in receipts]})
+
+
+def run_server() -> None:
+    """Start the MCP server on stdio."""
+    mcp_mod, types, server_cls = _require_mcp()
+
+    server = server_cls("groundcrew")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name="capture_state",
+                description=(
+                    "Capture before/after filesystem state around an action and "
+                    "store a verifiable receipt. Argument is a JSON string with "
+                    "keys: root, verb, target, params, run_cmd."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {"arguments": {"type": "string"}},
+                    "required": ["arguments"],
+                },
+            ),
+            types.Tool(
+                name="get_receipt",
+                description=(
+                    "Fetch a stored receipt by ID. Argument is a JSON string with key: receipt_id."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {"arguments": {"type": "string"}},
+                    "required": ["arguments"],
+                },
+            ),
+            types.Tool(
+                name="list_receipts",
+                description="List all stored receipts. Argument is an (ignored) JSON string.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {"arguments": {"type": "string"}},
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+        raw = arguments.get("arguments", "{}")
+        if name == "capture_state":
+            result = _capture_state(raw)
+        elif name == "get_receipt":
+            result = _get_receipt(raw)
+        elif name == "list_receipts":
+            result = _list_receipts(raw)
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+        return [types.TextContent(type="text", text=result)]
+
+    import asyncio
+
+    async def _main() -> None:
+        async with mcp_mod.server.stdio.stdio_server() as (read_stream, write_stream):
+            await server.run(read_stream, write_stream, server.create_initialization_options())
+
+    asyncio.run(_main())
+
+
+if __name__ == "__main__":
+    run_server()

groundcrew/oracle.py

@@ -0,0 +1,92 @@
+"""The Oracle: captures before/after state around actions and persists receipts."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+from groundcrew.codec import ActionReceipt, ActionSpec
+from groundcrew.snapshot import StateSnapshot, diff_snapshots
+
+
+class Oracle:
+    """Context manager that snapshots a root before and after a block of work."""
+
+    def __init__(self, root, spec=None):
+        self.root = Path(root)
+        self.spec = spec
+        self._before: StateSnapshot | None = None
+        self._after: StateSnapshot | None = None
+        self._success = True
+
+    def __enter__(self):
+        self._before = StateSnapshot.capture(self.root)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._after = StateSnapshot.capture(self.root)
+        if exc_type is not None:
+            self._success = False
+        return False
+
+    def record(self, spec: ActionSpec) -> ActionReceipt:
+        """Build an ActionReceipt for ``spec`` from the captured before/after state."""
+        if self._after is None:
+            self._after = StateSnapshot.capture(self.root)
+        diff = diff_snapshots(self._before, self._after)
+        return ActionReceipt(
+            spec=spec,
+            before_id=self._before.id if self._before else "",
+            after_id=self._after.id,
+            diff=diff,
+            success=self._success,
+            timestamp=time.time(),
+        )
+
+
+@contextmanager
+def capture(root, spec):
+    """Convenience context manager wrapping :class:`Oracle`."""
+    oracle = Oracle(root, spec)
+    oracle.__enter__()
+    try:
+        yield oracle
+    except Exception:
+        oracle._success = False
+        raise
+    finally:
+        oracle.__exit__(None, None, None)
+
+
+class ReceiptStore:
+    """A SQLite-backed store for persisting and retrieving action receipts."""
+
+    def __init__(self, path):
+        self._path = Path(path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(self._path))
+        self._conn.execute("CREATE TABLE IF NOT EXISTS receipts (id TEXT PRIMARY KEY, data TEXT)")
+        self._conn.commit()
+
+    def save(self, receipt: ActionReceipt) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO receipts (id, data) VALUES (?, ?)",
+            (receipt.id, json.dumps(receipt.to_dict())),
+        )
+        self._conn.commit()
+
+    def get(self, receipt_id: str) -> ActionReceipt | None:
+        row = self._conn.execute("SELECT data FROM receipts WHERE id = ?", (receipt_id,)).fetchone()
+        if row is None:
+            return None
+        return ActionReceipt.from_dict(json.loads(row[0]))
+
+    def list_receipts(self) -> list:
+        rows = self._conn.execute("SELECT data FROM receipts").fetchall()
+        return [ActionReceipt.from_dict(json.loads(r[0])) for r in rows]
+
+    def close(self) -> None:
+        self._conn.close()

groundcrew/report.py

@@ -0,0 +1,67 @@
+"""Human- and machine-readable formatters for receipts and diffs."""
+
+from __future__ import annotations
+
+import json
+
+from groundcrew.codec import ActionReceipt
+from groundcrew.snapshot import SnapshotDiff
+
+
+def print_receipt(receipt: ActionReceipt, console=None) -> None:
+    """Pretty-print a receipt to the console (falls back to plain text)."""
+    try:
+        from rich.console import Console
+        from rich.table import Table
+
+        c = console or Console()
+        t = Table(title=f"Receipt {receipt.id}")
+        t.add_column("Field")
+        t.add_column("Value")
+        t.add_row("Action", f"{receipt.spec.verb} -> {receipt.spec.target}")
+        t.add_row("Before", receipt.before_id)
+        t.add_row("After", receipt.after_id)
+        t.add_row("Success", str(receipt.success))
+        t.add_row("Changes", str(len(receipt.diff.changed_paths)))
+        c.print(t)
+    except ImportError:
+        print(f"Receipt {receipt.id}: {receipt.spec.verb} -> {receipt.spec.target}")
+
+
+def print_diff(diff: SnapshotDiff, console=None) -> None:
+    """Pretty-print a snapshot diff to the console (falls back to plain text)."""
+    try:
+        from rich.console import Console
+
+        c = console or Console()
+        c.print(f"[bold]Diff[/bold] {diff.snapshot_a_id} -> {diff.snapshot_b_id}")
+        for f in diff.added:
+            c.print(f"  [green]+[/green] {f.path}")
+        for f in diff.removed:
+            c.print(f"  [red]-[/red] {f.path}")
+        for before, _after in diff.modified:
+            c.print(f"  [yellow]~[/yellow] {before.path}")
+    except ImportError:
+        print(f"Diff: +{len(diff.added)} -{len(diff.removed)} ~{len(diff.modified)}")
+
+
+def to_json(receipt: ActionReceipt | None, diff: SnapshotDiff | None = None) -> str:
+    """Serialize a receipt or diff to a JSON string."""
+    if receipt is not None:
+        return json.dumps(receipt.to_dict(), indent=2)
+    if diff is not None:
+        return json.dumps(diff.to_dict(), indent=2)
+    return "{}"
+
+
+def to_markdown(receipts: list) -> str:
+    """Render a list of receipts as a Markdown table."""
+    lines = ["# Groundcrew Action Log", ""]
+    lines.append("| ID | Verb | Target | Success | Changes |")
+    lines.append("|---|---|---|---|---|")
+    for r in receipts:
+        lines.append(
+            f"| `{r.id}` | {r.spec.verb} | {r.spec.target} | "
+            f"{r.success} | {len(r.diff.changed_paths)} |"
+        )
+    return "\n".join(lines)

groundcrew/snapshot.py

@@ -0,0 +1,131 @@
+"""Deterministic filesystem state snapshots and content-addressed diffs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class FileState:
+    """The recorded state of a single file: relative path, size, and digest."""
+
+    path: str  # relative to root
+    size: int
+    sha256: str  # full hex digest
+
+    def to_dict(self) -> dict:
+        return {"path": self.path, "size": self.size, "sha256": self.sha256}
+
+    @classmethod
+    def from_dict(cls, d) -> FileState:
+        return cls(path=d["path"], size=d["size"], sha256=d["sha256"])
+
+
+@dataclass
+class StateSnapshot:
+    """A content-addressed snapshot of every file beneath a root directory."""
+
+    id: str  # SHA-256[:16] of sorted file-state JSON
+    timestamp: float
+    root: str
+    files: dict  # path -> FileState
+
+    @classmethod
+    def capture(cls, root) -> StateSnapshot:
+        root = Path(root)
+        files = {}
+        for dirpath, _, filenames in os.walk(root):
+            for fname in filenames:
+                fpath = Path(dirpath) / fname
+                rel = str(fpath.relative_to(root))
+                try:
+                    data = fpath.read_bytes()
+                    h = hashlib.sha256(data).hexdigest()
+                    files[rel] = FileState(path=rel, size=len(data), sha256=h)
+                except PermissionError:
+                    pass
+        # content-address: SHA-256[:16] of sorted JSON of file states
+        payload = json.dumps({k: v.to_dict() for k, v in sorted(files.items())}, sort_keys=True)
+        snap_id = hashlib.sha256(payload.encode()).hexdigest()[:16]
+        return cls(id=snap_id, timestamp=time.time(), root=str(root), files=files)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "timestamp": self.timestamp,
+            "root": self.root,
+            "files": {k: v.to_dict() for k, v in self.files.items()},
+        }
+
+    @classmethod
+    def from_dict(cls, d) -> StateSnapshot:
+        files = {k: FileState.from_dict(v) for k, v in d["files"].items()}
+        return cls(id=d["id"], timestamp=d["timestamp"], root=d["root"], files=files)
+
+
+@dataclass
+class SnapshotDiff:
+    """The structural delta between two snapshots: added, removed, modified files."""
+
+    snapshot_a_id: str | None
+    snapshot_b_id: str
+    added: list  # list[FileState]
+    removed: list  # list[FileState]
+    modified: list  # list[tuple[FileState, FileState]]
+
+    @property
+    def changed_paths(self) -> set:
+        paths = set()
+        for f in self.added:
+            paths.add(f.path)
+        for f in self.removed:
+            paths.add(f.path)
+        for before, _after in self.modified:
+            paths.add(before.path)
+        return paths
+
+    def to_dict(self) -> dict:
+        return {
+            "snapshot_a_id": self.snapshot_a_id,
+            "snapshot_b_id": self.snapshot_b_id,
+            "added": [f.to_dict() for f in self.added],
+            "removed": [f.to_dict() for f in self.removed],
+            "modified": [[b.to_dict(), a.to_dict()] for b, a in self.modified],
+        }
+
+    @classmethod
+    def from_dict(cls, d) -> SnapshotDiff:
+        return cls(
+            snapshot_a_id=d["snapshot_a_id"],
+            snapshot_b_id=d["snapshot_b_id"],
+            added=[FileState.from_dict(f) for f in d["added"]],
+            removed=[FileState.from_dict(f) for f in d["removed"]],
+            modified=[(FileState.from_dict(b), FileState.from_dict(a)) for b, a in d["modified"]],
+        )
+
+
+def diff_snapshots(snap_a: StateSnapshot | None, snap_b: StateSnapshot) -> SnapshotDiff:
+    """Compute the added/removed/modified delta from ``snap_a`` to ``snap_b``."""
+    a_files = snap_a.files if snap_a else {}
+    b_files = snap_b.files
+    a_paths = set(a_files.keys())
+    b_paths = set(b_files.keys())
+    added = [b_files[p] for p in b_paths - a_paths]
+    removed = [a_files[p] for p in a_paths - b_paths]
+    modified = [
+        (a_files[p], b_files[p])
+        for p in a_paths & b_paths
+        if a_files[p].sha256 != b_files[p].sha256
+    ]
+    return SnapshotDiff(
+        snapshot_a_id=snap_a.id if snap_a else None,
+        snapshot_b_id=snap_b.id,
+        added=added,
+        removed=removed,
+        modified=modified,
+    )

groundcrew-0.1.0.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: groundcrew
+Version: 0.1.0
+Summary: Deterministic state oracle and semantic action codec for computer-use agents
+Project-URL: Homepage, https://github.com/sandeep-alluru/groundcrew
+Project-URL: Repository, https://github.com/sandeep-alluru/groundcrew
+Project-URL: Documentation, https://sandeep-alluru.github.io/groundcrew
+Project-URL: Changelog, https://github.com/sandeep-alluru/groundcrew/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/sandeep-alluru/groundcrew/issues
+Author-email: Sandeep Alluru <onepuncchh@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Sandeep Alluru
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: action-codec,agents,ai,computer-use,llm,llmops,mcp,observability,state-oracle,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == 'api'
+Requires-Dist: uvicorn>=0.29; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# groundcrew
+
+**Deterministic state oracle and semantic action codec for computer-use agents.**
+
+![groundcrew](assets/hero.png)
+
+[![CI](https://github.com/sandeep-alluru/groundcrew/actions/workflows/ci.yml/badge.svg)](https://github.com/sandeep-alluru/groundcrew/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/groundcrew.svg)](https://pypi.org/project/groundcrew/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/groundcrew.svg)](https://pypi.org/project/groundcrew/)
+[![Downloads](https://img.shields.io/pypi/dm/groundcrew.svg)](https://pypi.org/project/groundcrew/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![codecov](https://codecov.io/gh/sandeep-alluru/groundcrew/branch/main/graph/badge.svg)](https://codecov.io/gh/sandeep-alluru/groundcrew)
+[![Typed](https://img.shields.io/badge/types-mypy-blue)](https://mypy-lang.org/)
+
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [CLI Reference](#cli-reference) · [GitHub Action](#github-action) · [vs. Alternatives](#vs-alternatives) · [Contributing](CONTRIBUTING.md)
+
+---
+
+## Why
+
+Computer-use agents act on real software: they write files, call APIs, run scripts. But how do you know what they *actually* did vs. what they were *supposed* to do?
+
+Screenshot-based LLM judges give you a visual approximation at best. They miss side effects — the extra file written, the config silently overwritten, the database row changed. And they cannot replay, diff, or audit what happened.
+
+groundcrew inverts the architecture: instead of watching from the outside, it snapshots the filesystem **before and after every action** and produces a content-addressed **ActionReceipt** — a tamper-evident record of exactly what changed. No guessing. No LLM judge. Just a deterministic diff.
+
+```
+groundcrew capture --root . --verb write --target config.json --run "agent.py"
+# → ActionReceipt: 3 files added, 1 modified, diff stored in .groundcrew/receipts.db
+```
+
+---
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A[Agent declares\nActionSpec\nverb · target · params] --> B[Oracle captures\nStateSnapshot BEFORE\nSHA-256 of file tree]
+    B --> C[Agent runs\nthe action]
+    C --> D[Oracle captures\nStateSnapshot AFTER]
+    D --> E[SnapshotDiff\nadded · removed · modified]
+    E --> F[ActionReceipt\nspec + before_id + after_id + diff]
+    F --> G[ReceiptStore\nSQLite persistence]
+```
+
+**Core primitives:**
+
+- **FileState** — a content-addressed snapshot of a single file: path, size, SHA-256.
+- **StateSnapshot** — a content-addressed snapshot of a directory tree. ID = SHA-256[:16] of sorted file states.
+- **SnapshotDiff** — the structural delta between two snapshots: added, removed, modified files.
+- **ActionSpec** — a semantic, content-addressed action description: `(verb, target, params)`. ID = SHA-256[:16] of the spec. The same action on the same target always produces the same ID.
+- **ActionReceipt** — binds an ActionSpec to a before-snapshot ID, after-snapshot ID, and SnapshotDiff. Stored permanently as an audit trail.
+- **ReceiptStore** — SQLite-backed store. Save receipts, retrieve by ID, list history.
+
+Snapshots are computed by walking the directory tree with `os.walk`, hashing each file with SHA-256, and content-addressing the whole collection. This is purely Python standard-library code — no kernel hooks, no elevated privileges, no platform-specific APIs required.
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| Content-addressed snapshots | Same file tree always produces the same snapshot ID |
+| Deterministic diffs | Added, removed, and modified files — no approximation |
+| Semantic action codec | `ActionSpec` is portable, content-addressed, version-robust |
+| Tamper-evident receipts | `ActionReceipt` binds intent to effect, stored permanently |
+| SQLite receipt store | Single-file persistence, no server, works offline |
+| Rich terminal output | Color diff tables, receipt summaries |
+| JSON output | Machine-readable for downstream automation |
+| Markdown output | Ready-to-paste audit reports |
+| FastAPI REST server | `/capture`, `/receipt/{id}`, `/receipts`, `/diff/{id}` |
+| MCP server | Model Context Protocol integration for Claude and other agents |
+| 69 tests | Comprehensive test suite covering all layers |
+
+---
+
+## Quick Start
+
+```bash
+pip install groundcrew            # core library + CLI
+pip install "groundcrew[api]"     # + FastAPI REST server
+pip install "groundcrew[mcp]"     # + MCP server
+```
+
+```python
+from groundcrew import Oracle, ActionSpec, ReceiptStore
+
+# Declare what you're about to do
+spec = ActionSpec(verb="write", target="config.json", params={"key": "value"})
+
+# Capture before/after state around the action
+with Oracle(".", spec) as oracle:
+    import json, pathlib
+    pathlib.Path("config.json").write_text(json.dumps({"key": "value"}))
+
+receipt = oracle.record(spec)
+print(receipt.diff.changed_paths)   # {'config.json'}
+print(receipt.id)                   # content-addressed ID
+
+# Persist for auditing
+store = ReceiptStore(".groundcrew/receipts.db")
+store.save(receipt)
+```
+
+---
+
+## CLI Reference
+
+```bash
+groundcrew [--db PATH] COMMAND [OPTIONS]
+```
+
+| Command | Description | Key options |
+|---------|-------------|-------------|
+| `capture` | Snapshot before/after a shell command | `--root DIR`, `--verb VERB`, `--target TARGET`, `--run CMD` |
+| `diff RECEIPT_ID` | Show the SnapshotDiff for a stored receipt | — |
+| `log` | List all stored receipts | — |
+| `status` | Show database info | — |
+
+**Global options:**
+
+| Option | Default | Env var |
+|--------|---------|---------|
+| `--db PATH` | `.groundcrew/receipts.db` | `GROUNDCREW_DB` |
+
+**Examples:**
+
+```bash
+# Capture what an agent script does to the current directory
+groundcrew capture --root . --verb run --target agent.py --run "python agent.py"
+
+# Show what changed
+groundcrew diff abc123de
+
+# List all receipts
+groundcrew log
+
+# Status
+groundcrew status
+```
+
+---
+
+## GitHub Action
+
+Add groundcrew auditing to your CI pipeline:
+
+```yaml
+# .github/workflows/groundcrew.yml
+name: groundcrew audit
+on: [push, pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: sandeep-alluru/groundcrew@main
+        with:
+          root: .
+          db: .groundcrew/receipts.db
+```
+
+---
+
+## vs. Alternatives
+
+| | groundcrew | Screenshot judges | AgentSight | OSWorld verifiers |
+|---|---|---|---|---|
+| **Verification method** | Filesystem diff | Vision LLM | eBPF syscall trace | Per-task custom code |
+| **Deterministic** | Yes — content-addressed | No — probabilistic | Partial | Yes (per app) |
+| **No per-app code** | Yes | Yes | Yes | No — 33 apps manually |
+| **Production runtime** | Yes | Yes | Linux-only | VM/sandbox only |
+| **Audit trail** | SQLite receipts | None | Log files | None |
+| **Action codec** | Portable ActionSpec | None | None | None |
+| **Open source** | MIT | N/A | MIT | Research |
+| **Python package** | Yes | N/A | No | No |
+
+groundcrew is not a replacement for security-layer tools like AgentSight. It is specifically designed for agent developers who need a simple, deterministic record of what their agent changed on disk — suitable for testing, auditing, and CI/CD gating.
+
+---
+
+## Claude / MCP integration
+
+groundcrew ships a Model Context Protocol server that lets Claude and other MCP-compatible agents record and query action receipts directly:
+
+```bash
+# Start the MCP server
+python -m groundcrew.mcp_server
+
+# In your Claude Code project's .claude/settings.json:
+{
+  "mcpServers": {
+    "groundcrew": {
+      "command": "python",
+      "args": ["-m", "groundcrew.mcp_server"]
+    }
+  }
+}
+```
+
+Once connected, Claude can call `groundcrew/capture_state`, `groundcrew/get_receipt`, and `groundcrew/list_receipts` as tools. See [docs/mcp.md](docs/mcp.md) for the full tool schema.
+
+---
+
+## OpenAI integration
+
+groundcrew exposes a FastAPI REST server compatible with OpenAI's function-calling format. The tool definitions are in [`tools/openai-tools.json`](tools/openai-tools.json) and the full API spec is in [`openapi.yaml`](openapi.yaml).
+
+```bash
+# Start the REST server
+uvicorn groundcrew.api:app --reload
+
+# Pass to Codex CLI or any OpenAI-compatible agent
+codex --tools tools/openai-tools.json "Capture what this script does to the filesystem"
+```
+
+Endpoints: `GET /health`, `POST /capture`, `GET /receipt/{id}`, `GET /receipts`, `GET /diff/{id}`. See [docs/openai.md](docs/openai.md) for details.
+
+---
+
+## Repository structure
+
+```
+groundcrew/
+├── src/
+│   └── groundcrew/
+│       ├── snapshot.py       # FileState, StateSnapshot, SnapshotDiff
+│       ├── codec.py          # ActionSpec, ActionReceipt (content-addressed)
+│       ├── oracle.py         # Oracle context manager, capture(), ReceiptStore
+│       ├── report.py         # print_receipt(), print_diff(), to_json(), to_markdown()
+│       ├── cli.py            # Click CLI (capture, diff, log, status)
+│       ├── api.py            # FastAPI REST server
+│       └── mcp_server.py     # MCP server
+├── tests/
+│   ├── test_snapshot.py      # StateSnapshot, SnapshotDiff unit tests
+│   ├── test_codec.py         # ActionSpec, ActionReceipt unit tests
+│   ├── test_oracle.py        # Oracle context manager, ReceiptStore tests
+│   ├── test_report.py        # Formatter tests
+│   ├── test_cli.py           # CLI subprocess integration tests
+│   ├── test_cli_runner.py    # Click CliRunner tests
+│   └── test_api.py           # FastAPI TestClient tests
+├── examples/
+│   └── demo.py               # Standalone demo script
+├── docs/                     # MkDocs documentation
+├── tools/
+│   └── openai-tools.json     # OpenAI function-calling tool definitions
+├── assets/
+│   ├── hero.png              # README hero image
+│   └── logo.png              # Project logo
+├── action.yml                # GitHub Action
+├── openapi.yaml              # OpenAPI 3.1 spec
+├── pyproject.toml            # Package metadata + dependencies
+└── CONTRIBUTING.md           # Contribution guide
+```
+
+---
+
+## GitHub Topics
+
+Suggested topics for discoverability:
+
+`ai-agents` `computer-use` `state-oracle` `action-codec` `filesystem-diff` `verification` `observability` `mcp` `openai` `llm-tools` `audit-trail` `ci-cd` `python`
+
+---
+
+[![Star History Chart](https://api.star-history.com/svg?repos=sandeep-alluru/groundcrew&type=Date)](https://star-history.com/#sandeep-alluru/groundcrew&Date)

groundcrew-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+groundcrew/__init__.py,sha256=CcAxNJcJ4q4j8k2DNbeJ6sVr_rbpN4FLQN3Emrkp6sE,568
+groundcrew/api.py,sha256=AbSyZt_bcsVdBc17wr245vplZzGD30AXTviPNJ6YoSg,3340
+groundcrew/cli.py,sha256=GKbS143lew__IhRwvrBOP9U_OLi-jkUrzEUHGY24dSA,3445
+groundcrew/codec.py,sha256=XjK78ZlBcwaFu6TDqypVOaE12kJHnR_CgvGx1Z1n_Zg,2333
+groundcrew/mcp_server.py,sha256=EY3FqUmdGVStVWc0Kts0CeWJFvf1-FF3lm0yvq259B0,4677
+groundcrew/oracle.py,sha256=oIxbMJYSFX1hqwsDMyM7ojoec8djOj34OUA0Ku2uTrU,2992
+groundcrew/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundcrew/report.py,sha256=oD7BXwfgKqzKEDySLBtwVmnF3hMxXFYfvIFezhrnbRw,2450
+groundcrew/snapshot.py,sha256=1fHL3kauVaZt3EoJwgZUjZ0ei6REgsf8LcND1lvvZo8,4335
+groundcrew-0.1.0.dist-info/METADATA,sha256=ohF4qhKVywamA5pMZTC8rfL1L8_AeA7LD62fxqlEqTs,13642
+groundcrew-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+groundcrew-0.1.0.dist-info/entry_points.txt,sha256=vbFGKnuLjB3oHcS-16cFUz3w1MLl-N7Vu3T4KR5NU5I,101
+groundcrew-0.1.0.dist-info/licenses/LICENSE,sha256=XwBxPnLzQtV19xccU-wMkDrInqQ90nvdsBtUYsJsuDM,1071
+groundcrew-0.1.0.dist-info/RECORD,,

groundcrew-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

groundcrew-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+groundcrew = groundcrew.cli:main
+groundcrew-mcp = groundcrew.mcp_server:run_server

groundcrew-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandeep Alluru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.