gravity-cli 0.1.0__py3-none-any.whl

gravity_cli/__init__.py

@@ -0,0 +1,11 @@
+"""gravity — the CLI a builder actually touches."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+
+# Windows consoles default to cp1252, which can't print ✓/✖/→. Here so nothing prints first.
+for _stream in (sys.stdout, sys.stderr):
+    with contextlib.suppress(Exception):
+        _stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]

gravity_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

gravity_cli/_runner_script.py

@@ -0,0 +1,195 @@
+"""Runs the builder's agent in their own venv, as the production runner does. Stdlib only.
+
+argv: entry_file entry_object payload_file   a JSON file: {"inputs", "messages"?, "memory"?}
+out:  one JSON event per line (EVENT_PREFIX) for `gravity run` to draw."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import inspect
+import json
+import os
+import sys
+import time
+import warnings
+
+# A harmless langchain-openai warning that would print mid-timeline.
+warnings.filterwarnings("ignore", message=r"Pydantic serializer warnings")
+
+
+def _load_graph(entry_file: str, entry_object: str):
+    # src/ on sys.path, as in production, so a relative import fails here too.
+    file_path = os.path.abspath(entry_file)
+    pkg_root = os.path.dirname(file_path)
+    if pkg_root not in sys.path:
+        sys.path.insert(0, pkg_root)
+    spec = importlib.util.spec_from_file_location("gravity_agent", file_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"could not load {entry_file}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["gravity_agent"] = module
+    spec.loader.exec_module(module)
+    if not hasattr(module, entry_object):
+        raise AttributeError(
+            f"{entry_file} has no `{entry_object}` — check runtime.entrypoint in manifest.yaml"
+        )
+    return getattr(module, entry_object)
+
+
+async def _resolve(obj):
+    # Same rules as the production runner: await, or call a zero-arg factory, in this loop.
+    if inspect.isawaitable(obj):
+        return await obj
+    if callable(obj) and not hasattr(obj, "astream"):
+        obj = obj()
+        if inspect.isawaitable(obj):
+            obj = await obj
+    return obj
+
+
+EVENT_PREFIX = "@@gravity "
+ROLES = {"human": "user", "ai": "assistant", "system": "system"}
+
+
+# Same three helpers as agentcore-spike/runner/gravity_runner/__main__.py.
+def accepts_messages(graph) -> bool:
+    # A compiled graph's channels are its state keys; no schema build (raises on py<3.12).
+    channels = getattr(graph, "channels", None)
+    if isinstance(channels, dict):
+        return "messages" in channels
+    getter = getattr(graph, "get_input_jsonschema", None)
+    if callable(getter):
+        try:
+            return "messages" in (getter().get("properties") or {})
+        except Exception:  # noqa: BLE001, S110 - a probe; absence is a valid answer
+            pass
+    return False
+
+
+def user_turn(inputs: dict) -> str:
+    for key in ("message", "query", "prompt", "input"):
+        value = inputs.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return json.dumps(inputs)
+
+
+def to_dicts(messages) -> list[dict]:
+    """LangChain messages -> {role, content}; tool turns dropped (half a pair breaks the next turn)."""
+    out = []
+    for m in messages or []:
+        if isinstance(m, dict):
+            role, content = m.get("role"), m.get("content")
+        else:
+            if getattr(m, "tool_calls", None) or getattr(m, "type", None) == "tool":
+                continue
+            role, content = ROLES.get(getattr(m, "type", ""), ""), getattr(m, "content", None)
+        if role in ROLES.values() and isinstance(content, str) and content.strip():
+            out.append({"role": role, "content": content})
+    return out
+
+
+def emit(type_: str, **fields) -> None:
+    line = json.dumps({"type": type_, **fields}, default=str, ensure_ascii=False)
+    print(EVENT_PREFIX + line, flush=True)
+
+
+def _text(value) -> str:
+    """A tool's output as text: ToolMessage, MCP content blocks, or a str."""
+    value = getattr(value, "content", value)
+    if isinstance(value, list):
+        value = "".join(b.get("text", "") if isinstance(b, dict) else str(b) for b in value)
+    return value if isinstance(value, str) else json.dumps(value, default=str)
+
+
+def _handle(ev: dict, started: dict) -> None:
+    """One LangGraph astream_events(v2) event -> zero or one gravity event."""
+    kind, name = ev["event"], ev["name"]
+    meta = ev.get("metadata") or {}
+    node = meta.get("langgraph_node")
+    top_level = "|" not in (meta.get("langgraph_checkpoint_ns") or "")
+    run_id = ev.get("run_id")
+
+    if kind in ("on_chain_start", "on_chain_end") and name == node and top_level:
+        if kind == "on_chain_start":
+            started[run_id] = time.perf_counter()
+            emit("step.started", node=name)
+        else:
+            emit("step.finished", node=name, ms=_ms(started, run_id))
+    elif kind == "on_chat_model_start":
+        started[run_id] = time.perf_counter()
+    elif kind == "on_chat_model_end":
+        emit("model.called", node=node, model=meta.get("ls_model_name") or name, ms=_ms(started, run_id))
+    elif kind == "on_tool_start":
+        # At the start too, so a call held for approval is visible while it waits.
+        started[run_id] = time.perf_counter()
+        emit("tool.started", node=node, tool=name, id=run_id)
+    elif kind == "on_tool_end":
+        emit("tool.called", node=node, tool=name, id=run_id, ms=_ms(started, run_id), output=_text(ev["data"].get("output"))[:100_000])
+    elif kind == "on_tool_error":
+        emit("tool.failed", node=node, tool=name, id=run_id, ms=_ms(started, run_id), error=str(ev["data"].get("error")))
+
+
+def _ms(started: dict, run_id) -> int | None:
+    t = started.pop(run_id, None)
+    return round((time.perf_counter() - t) * 1000) if t else None
+
+
+async def _consume_async(graph, state, history):
+    graph = await _resolve(graph)
+    if accepts_messages(graph):
+        state["messages"] = history or [{"role": "user", "content": user_turn(state["inputs"])}]
+    if not hasattr(graph, "astream_events"):
+        # Not LangGraph: no timeline; plain astream(state), folding the deltas.
+        final: dict = {}
+        async for update in graph.astream(state):
+            if isinstance(update, dict):
+                for value in update.values() if all(isinstance(v, dict) for v in update.values()) else [update]:
+                    final.update(value)
+        return final
+    final, started = None, {}
+    async for ev in graph.astream_events(state, version="v2"):
+        _handle(ev, started)
+        if ev["event"] == "on_chain_end" and not ev.get("parent_ids"):
+            final = ev["data"].get("output")
+    return final
+
+
+def main() -> int:
+    entry_file, entry_object = sys.argv[1], sys.argv[2]
+    with open(sys.argv[3], encoding="utf-8") as f:
+        payload = json.load(f)
+    history = payload.get("messages")
+    state = {"inputs": payload.get("inputs") or {}}
+    if "memory" in payload:
+        state["memory"] = payload["memory"] or {}
+
+    try:
+        graph = _load_graph(entry_file, entry_object)
+    except Exception as e:  # noqa: BLE001 — surfaced to the builder, not swallowed
+        emit("run.failed", stage="load", error=f"could not load the agent: {e}")
+        return 1
+
+    # astream: agent graphs have async nodes, so the sync stream() fails on them.
+    start = time.time()
+    try:
+        final = asyncio.run(_consume_async(graph, state, history))
+    except Exception as e:  # noqa: BLE001
+        emit("run.failed", stage="run", error=str(e), ms=round((time.time() - start) * 1000))
+        return 1
+
+    final = final if isinstance(final, dict) else {}
+    emit(
+        "run.finished",
+        ms=round((time.time() - start) * 1000),
+        has_result="result" in final,
+        result=final.get("result"),
+        messages=to_dicts(final.get("messages")) if "messages" in state else None,
+        memory=final.get("memory") if "memory" in state else None,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gravity_cli/api.py

@@ -0,0 +1,88 @@
+"""Thin client for the control plane."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+import typer
+from rich import print as rprint
+
+from . import config
+
+
+def _handle(resp: httpx.Response) -> Any:
+    """The JSON body, or print the server's message and exit 1."""
+    if resp.status_code >= 400:
+        try:
+            body = resp.json()
+            message = body.get("message") or body
+        except (ValueError, AttributeError):  # not JSON, or not an object
+            message = resp.text
+        if isinstance(message, list):
+            message = "; ".join(str(m) for m in message)
+        rprint(f"[red]✖[/red] {message}")
+        raise typer.Exit(1)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()
+
+
+def _post(path: str, **kw) -> Any:
+    """Unauthenticated: the device-code login runs before there is a token."""
+    with httpx.Client(base_url=config.api_url(), timeout=15) as client:
+        return _handle(client.post(path, **kw))
+
+
+def device_start() -> dict:
+    return _post("/api/cli/device/start")
+
+
+def device_poll(device_code: str) -> dict:
+    return _post("/api/cli/device/poll", json={"deviceCode": device_code})
+
+
+def require_session() -> config.Session:
+    session = config.load_session()
+    if session is None:
+        typer.secho(
+            "not logged in — run `gravity login` first, or set GRAVITY_API_TOKEN.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+    return session
+
+
+def _token() -> str:
+    # GRAVITY_API_TOKEN (the control plane's dev token) wins over a stored session.
+    return os.environ.get("GRAVITY_API_TOKEN", "").strip() or require_session().access_token
+
+
+def _auth_client() -> httpx.Client:
+    return httpx.Client(
+        base_url=config.api_url(),
+        timeout=60,
+        headers={"Authorization": f"Bearer {_token()}"},
+    )
+
+
+def get(path: str) -> Any:
+    with _auth_client() as client:
+        return _handle(client.get(path))
+
+
+def push_agent(manifest_json: dict, zip_bytes: bytes, source_sha256: str) -> dict:
+    import base64
+    import json
+
+    headers = {
+        "Authorization": f"Bearer {_token()}",
+        "Content-Type": "application/octet-stream",
+        "x-manifest": base64.b64encode(json.dumps(manifest_json).encode()).decode(),
+        "x-source-sha256": source_sha256,
+    }
+    with httpx.Client(base_url=config.api_url(), timeout=120, headers=headers) as client:
+        resp = client.post("/api/cli/agents/push", content=zip_bytes)
+        return _handle(resp)

gravity_cli/cli.py

@@ -0,0 +1,124 @@
+"""gravity CLI. Convenience only, never security: the server re-checks everything."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+import typer.rich_utils as help_style
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+from rich.text import Text
+
+from . import config
+from .commands.adapt import adapt_command
+from .commands.build import build_command
+from .commands.init import TEMPLATE_NAMES, init_command
+from .commands.login import login_command, logout_command, whoami_command
+from .commands.push import push_command
+from .commands.run import run_command
+from .commands.runs import agents_command, logs_command, runs_command
+from .commands.schedule import schedule_command
+from .commands.tools import tools_command
+from .commands.validate import validate_command
+
+EMBER, AMBER, RED = "#ff6b35", "#ffb627", "#e63946"
+
+help_style.STYLE_USAGE = f"bold {EMBER}"
+help_style.STYLE_COMMANDS_TABLE_FIRST_COLUMN = f"bold {EMBER}"
+help_style.STYLE_OPTION = help_style.STYLE_SWITCH = f"bold {AMBER}"
+help_style.STYLE_COMMANDS_PANEL_BORDER = help_style.STYLE_OPTIONS_PANEL_BORDER = AMBER
+help_style.STYLE_ERRORS_PANEL_BORDER = RED
+
+app = typer.Typer(
+    name="gravity",
+    help="Build, test and publish AI agents on Gravity.",
+    epilog=(
+        f"[bold {EMBER}]New here?[/]  gravity init my-agent  →  cd my-agent  →  gravity run --input query=\"hi\"\n\n"
+        "Settings live in ~/.gravity/.env. Add -h to any command for its options."
+    ),
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    add_completion=False,
+)
+
+BUILD, PUBLISH, AGENTS, ACCOUNT = "Build an agent", "Publish", "Your agents", "Account"
+for name, command, panel, summary in [
+    ("init", init_command, BUILD, "Create a new agent from a template"),
+    ("validate", validate_command, BUILD, "Check your agent for mistakes before it runs"),
+    ("run", run_command, BUILD, "Run your agent locally against real tools"),
+    ("schedule", schedule_command, BUILD, "Run your agent on its schedule, locally"),
+    ("adapt", adapt_command, BUILD, "Write a new slot adapter with AI, kept only if its tests pass"),
+    ("build", build_command, PUBLISH, "Package your agent into build/agent.zip"),
+    ("push", push_command, PUBLISH, "Publish your built agent to Gravity"),
+    ("agents", agents_command, AGENTS, "List your published agents and their review status"),
+    ("runs", runs_command, AGENTS, "Show recent runs of one agent"),
+    ("logs", logs_command, AGENTS, "Show the logs of one run"),
+    ("tools", tools_command, AGENTS, "Browse the tools your agent can use"),
+    ("login", login_command, ACCOUNT, "Sign in to Gravity in your browser"),
+    ("logout", logout_command, ACCOUNT, "Sign out"),
+    ("whoami", whoami_command, ACCOUNT, "Show who you are signed in as"),
+]:
+    app.command(name, help=summary, rich_help_panel=panel)(command)
+
+
+@app.command("help", rich_help_panel=ACCOUNT)
+def help_command(ctx: typer.Context):
+    """Show this list of commands"""
+    ctx.parent.get_help()
+
+
+def _interactive() -> bool:
+    return sys.stdin.isatty() and sys.stderr.isatty()  # a person is there to answer
+
+
+def _welcome(console: Console) -> None:
+    steps = Table.grid(padding=(0, 2))
+    steps.add_column(style=f"bold {EMBER}", justify="right")
+    steps.add_column(style=f"bold {AMBER}")
+    steps.add_column(style="dim")
+    steps.add_row("1", "gravity init my-agent", "create a working agent from a template")
+    steps.add_row("2", "gravity validate", "catch mistakes before anything runs")
+    steps.add_row("3", "gravity run", "run it against real tools, live")
+    steps.add_row("4", "gravity push", "publish it to Gravity")
+    body = Group(
+        Text.from_markup(
+            "Build AI agents in plain Python with LangGraph. Declare what they may touch in one "
+            "[bold]manifest.yaml[/bold], and Gravity runs them with exactly those permissions.\n"
+        ),
+        steps,
+        Text.from_markup(f"\n[dim]Stuck? [bold {AMBER}]gravity help[/] lists every command.[/dim]"),
+    )
+    console.print(Panel(body, title=f"[bold {EMBER}]✦ Welcome to Gravity ✦", border_style=AMBER, padding=(1, 2), expand=False))
+
+
+def _first_agent(console: Console) -> bool:
+    """Offer to scaffold an agent right away. True if one was created."""
+    try:
+        if not Confirm.ask(f"[bold {AMBER}]Create your first agent now?", default=True, console=console):
+            return False
+        name = Prompt.ask("  Agent name", default="my-agent", console=console)
+        template = Prompt.ask("  Template", choices=TEMPLATE_NAMES, default="minimal", console=console)
+    except (EOFError, KeyboardInterrupt):
+        console.print()
+        return False
+    init_command(name, template=template, here=False)
+    return True
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    api_url: str = typer.Option(None, "--api-url", help="Save a different Gravity API URL (or set GRAVITY_API_URL)"),
+):
+    if config.first_run():
+        console = Console(stderr=True)  # stderr: never mixed into output someone pipes
+        _welcome(console)
+        if ctx.invoked_subcommand is None and _interactive() and _first_agent(console):
+            raise typer.Exit()
+    if api_url:
+        config.set_api_url(api_url)
+    if ctx.invoked_subcommand is None:
+        ctx.get_help()

gravity_cli/commands/adapt.py

@@ -0,0 +1,155 @@
+"""`gravity adapt <slot> <name> --tools ...`: a coding agent writes one adapter file, kept only
+if the slot's conformance tests pass. Naming the tools is the grant."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+import httpx
+import typer
+from rich import print as rprint
+from rich.markup import escape
+
+from .. import project
+from ..manifest import ManifestValidationError, load_manifest, render_issues
+from .run import BUILDER_TOKENS, _mint_run_token, gateway_urls
+
+ATTEMPTS = 3
+CODE_BLOCK = re.compile(r"```python\n(.*?)```", re.DOTALL)
+
+SYSTEM = (
+    "You write one adapter file for a Python agent. Follow the slot contract exactly. Reach "
+    "the outside world only through the `call` function you are given, only with the tools "
+    "you are told this adapter may use, with arguments that match their schemas. Stdlib and "
+    "the slot package only. Match the style of the existing adapters. Reply with the whole "
+    "file in one ```python block and nothing else."
+)
+
+
+def _declare(manifest_path: Path, slot: str, name: str, tools: list[str]) -> str:
+    """Add `<name>: [tools]` under slots.<slot>.adapters. Returns the original text."""
+    original = manifest_path.read_text(encoding="utf-8")
+    lines = original.splitlines(keepends=True)
+    slot_at = next(i for i, ln in enumerate(lines) if re.match(rf"^\s+{slot}:\s*$", ln))
+    adapters_at = next(i for i in range(slot_at + 1, len(lines)) if lines[i].strip() == "adapters:")
+    indent = len(lines[adapters_at]) - len(lines[adapters_at].lstrip())
+    end = adapters_at + 1
+    while end < len(lines) and (not lines[end].strip() or len(lines[end]) - len(lines[end].lstrip()) > indent):
+        end += 1
+    while not lines[end - 1].strip():  # keep the new entry above any blank line
+        end -= 1
+    lines.insert(end, f"{' ' * (indent + 2)}{name}: [{', '.join(tools)}]\n")
+    manifest_path.write_text("".join(lines), encoding="utf-8")
+    return original
+
+
+def _ask(gateway_base: str, token: str, model: str, messages: list[dict]) -> str:
+    resp = httpx.post(
+        f"{gateway_base}/v1/chat/completions",
+        json={"model": model, "messages": messages},
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=180,
+    )
+    resp.raise_for_status()
+    return resp.json()["choices"][0]["message"]["content"]
+
+
+def adapt_command(
+    slot: str = typer.Argument(..., help="The slot to extend, e.g. deliver"),
+    name: str = typer.Argument(..., help="Name of the new adapter, e.g. slack"),
+    tools: str = typer.Option(..., "--tools", help="Tools the adapter may call, comma-separated. This is what it is granted"),
+    hint: str = typer.Option("", "--hint", help="Anything the coding agent should know, e.g. 'post to #leads'"),
+    model: str = typer.Option("anthropic/claude-sonnet-5", "--model", help="Model that writes the adapter"),
+    path: Path = typer.Option(Path("."), "--path", help="Agent folder"),
+):
+    """Write a new adapter for a slot with a coding agent, gated by the slot's conformance tests."""
+    project_dir = path.resolve()
+    manifest_path = project_dir / "manifest.yaml"
+    manifest = load_manifest(manifest_path)
+    if slot not in manifest.slots:
+        rprint(f"[red]✖[/red] no slot {slot!r} in manifest.yaml (slots: {', '.join(manifest.slots) or 'none'})")
+        raise typer.Exit(1)
+    if not name.isidentifier() or name in manifest.slots[slot].adapters:
+        rprint(f"[red]✖[/red] {name!r} is not a new adapter name for {slot}")
+        raise typer.Exit(1)
+    folder = project_dir / "src" / "adapters" / slot
+    target = folder / f"{name}.py"
+    test_file = project_dir / "tests" / f"test_{slot}_adapters.py"
+    if not test_file.is_file():
+        rprint(f"[red]✖[/red] no tests/test_{slot}_adapters.py — the conformance tests are what make this safe")
+        raise typer.Exit(1)
+    grant = [t.strip() for t in tools.split(",") if t.strip()]
+
+    # Declare first so validation (and the tests) see the adapter with exactly its grant.
+    original = _declare(manifest_path, slot, name, grant)
+    try:
+        load_manifest(manifest_path)  # catalog check on the new tools
+    except ManifestValidationError as e:
+        manifest_path.write_text(original, encoding="utf-8")
+        render_issues(e)
+        raise typer.Exit(1) from e
+
+    _, gateway_base = gateway_urls()
+    dev = {"Authorization": f"Bearer {os.environ.get('GRAVITY_DEV_TOKEN', '')}"}
+    all_tools = sorted({t for tl in manifest.slots[slot].adapters.values() for t in tl} | set(grant))
+    try:
+        schemas = httpx.get(f"{gateway_base}/tools", params={"names": ",".join(all_tools)}, headers=dev, timeout=15)
+        schemas.raise_for_status()
+    except httpx.HTTPError as e:
+        manifest_path.write_text(original, encoding="utf-8")
+        rprint(f"[red]✖[/red] couldn't read tool schemas from the gateway at {gateway_base}: {e}")
+        raise typer.Exit(1) from e
+    (project_dir / "tests" / "tool_schemas.json").write_text(json.dumps(schemas.json(), indent=2), encoding="utf-8")
+
+    def read(p: Path) -> str:
+        return f"### {p.relative_to(project_dir).as_posix()}\n```python\n{p.read_text(encoding='utf-8')}```"
+
+    gold = [read(p) for p in sorted(folder.glob("*.py")) if p != target]
+    new_schemas = [s for s in schemas.json() if s["name"] in grant]
+    messages = [
+        {"role": "system", "content": SYSTEM},
+        {"role": "user", "content": "\n\n".join([
+            f"Write src/adapters/{slot}/{name}.py. It may call only: {', '.join(grant)}.",
+            f"Their argument schemas:\n```json\n{json.dumps(new_schemas, indent=2)}\n```",
+            "The slot contract and the existing adapters:", *gold,
+            "It must pass these conformance tests:", read(test_file),
+            *( [f"Notes from the user: {hint}"] if hint else [] ),
+        ])},
+    ]
+
+    token = _mint_run_token(gateway_base, [], [])["token"]  # models only, no tools
+    python = project.find_python(project_dir)
+    test_env = {k: v for k, v in os.environ.items() if k not in BUILDER_TOKENS}  # it runs LLM-written code
+    for attempt in range(1, ATTEMPTS + 1):
+        rprint(f"[dim]attempt {attempt}/{ATTEMPTS}: asking {model}…[/dim]")
+        reply = _ask(gateway_base, token, model, messages)
+        match = CODE_BLOCK.search(reply)
+        code = match.group(1) if match else reply
+        target.write_text(code, encoding="utf-8")  # the only file it ever writes
+        result = subprocess.run(
+            [python, "-m", "pytest", "-q", str(test_file), "-k", name],
+            cwd=project_dir, env=test_env, capture_output=True, text=True, encoding="utf-8", errors="replace", check=False,
+        )
+        if result.returncode == 0:
+            rprint(f"[green]✓[/green] src/adapters/{slot}/{name}.py passes the {slot} conformance tests")
+            rprint(f"[green]✓[/green] declared in manifest.yaml: slots.{slot}.adapters.{name}: " + escape(f"[{', '.join(grant)}]"))
+            rprint(f"  try it: [bold]gravity run --input {slot}={name} --input destination=…[/bold]")
+            return
+        failure = (result.stdout + result.stderr)[-3000:]
+        if "No module named pytest" in failure:
+            break
+        rprint("[yellow]✗[/yellow] tests failed; feeding the failure back")
+        messages += [{"role": "assistant", "content": reply},
+                     {"role": "user", "content": f"The conformance tests failed:\n```\n{failure}\n```\nFix the file."}]
+
+    target.unlink(missing_ok=True)
+    manifest_path.write_text(original, encoding="utf-8")
+    rprint(f"[red]✖[/red] no adapter that passes the tests after {attempt} attempt(s); nothing was changed")
+    rprint("[dim]" + escape(failure.strip()[-1500:]) + "[/dim]")
+    if "No module named pytest" in failure:
+        rprint("[dim]install pytest in the agent's venv: uv pip install pytest pyyaml[/dim]")
+    raise typer.Exit(1)

gravity_cli/commands/build.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import zipfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+
+from ..manifest import ManifestValidationError, load_manifest, render_issues
+from ..project import project_files, source_digest
+from .validate import validate_command
+
+
+def build_paths(project_dir: Path) -> tuple[Path, Path]:
+    """(zip, meta) — the two files `gravity build` writes and `gravity push` reads."""
+    d = project_dir / "build"
+    return d / "agent.zip", d / "build.json"
+
+
+def _zip_project(project_dir: Path) -> bytes:
+    """Deterministic (fixed timestamps, sorted entries): same source, same sha256."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for f in project_files(project_dir):
+            info = zipfile.ZipInfo(f.relative_to(project_dir).as_posix())
+            info.date_time = (1980, 1, 1, 0, 0, 0)
+            info.compress_type = zipfile.ZIP_DEFLATED
+            zf.writestr(info, f.read_bytes())
+    return buf.getvalue()
+
+
+def build_command(
+    path: Path = typer.Argument(Path("."), help="Agent folder"),
+    skip_validate: bool = typer.Option(False, "--skip-validate", hidden=True),
+):
+    """Validate, then bundle src + manifest + lockfile into build/agent.zip.
+    Nothing leaves your machine — inspect the zip, then `gravity push`."""
+    project_dir = path.resolve()
+
+    if not skip_validate:
+        try:
+            validate_command(project_dir)
+        except typer.Exit as e:
+            if e.exit_code != 0:
+                rprint("[red]build aborted — fix the errors above and re-run.[/red]")
+                raise
+
+    try:
+        manifest = load_manifest(project_dir / "manifest.yaml")
+    except ManifestValidationError as e:
+        render_issues(e)
+        raise typer.Exit(1) from e
+
+    # After validate recompiled the lock, so the digest covers what ships.
+    zip_bytes = _zip_project(project_dir)
+    digest = source_digest(project_dir)
+    zip_sha256 = hashlib.sha256(zip_bytes).hexdigest()
+
+    zip_path, meta_path = build_paths(project_dir)
+    zip_path.parent.mkdir(exist_ok=True)
+    zip_path.write_bytes(zip_bytes)
+    meta_path.write_text(
+        json.dumps(
+            {
+                "source_sha256": digest,
+                "zip_sha256": zip_sha256,
+                "built_at": datetime.now(UTC).isoformat(timespec="seconds"),
+            },
+            indent=2,
+        )
+        + "\n"
+    )
+
+    rel = zip_path.relative_to(project_dir).as_posix()
+    rprint(
+        f"[green]✓ built {manifest.name}@{manifest.version}[/green] → {rel} "
+        f"· {len(zip_bytes)} bytes · sha256:{zip_sha256[:12]}…"
+    )
+    rprint("[dim]next: gravity push[/dim]")