gravity-cli 0.5.2__tar.gz → 0.5.4__tar.gz

{gravity_cli-0.5.2 → gravity_cli-0.5.4}/AGENT_STANDARD.md

@@ -39,7 +39,7 @@ description: One line.            # ≤500 chars
 
 runtime:
   framework: langgraph            # only value accepted
-  python: "3.13"                  # 3.10–3.13; the lockfile is compiled for it
+  python: "3.12"                  # the platform runs 3.12; validate refuses any other
   entrypoint: src/agent.py:graph  # file:object — see §3
   timeout_seconds: 300            # 10–900
 
@@ -67,7 +67,7 @@ resources:
 triggers:                         # optional — what starts a run
   manual: true                    # default
   # schedule:
-  #   cron: "0 9 * * 1"           # 5 fields: digits, * / , - only (no @daily, no MON)
+  #   cron: "0 9 * * 1"           # 5 fields: digits, * / , - only (no @daily, no MON); every 5 minutes at the fastest; one day field at most; Asia/Kolkata
   #   consumer_can_change: true
 
 approvals:                        # optional — tools that pause the run for the consumer's yes
@@ -78,8 +78,9 @@ approvals:                        # optional — tools that pause the run for th
 ```
 
 **`approvals` is enforced by the gateway.** A listed tool is held until a
-human answers: in `gravity run` you're asked (`Approve? [y/N]`, default no;
-no answer is a no); in the product it's the consumer's approval inbox. Not
+human answers: in `gravity run` you're asked (`y approve · n reject · enter reject`,
+default no; no answer is a no) and `gravity dev` shows Approve/Reject buttons; in the
+product it's the consumer's approval inbox. Not
 approved, the call returns `APPROVAL_REJECTED` (or `APPROVAL_TIMEOUT` after 4
 minutes) and never runs — handle that and fall back, as `meeting-notes`
 keeps the recap as a draft. Your code can't skip the question: the gateway
@@ -109,7 +110,7 @@ async def graph():                # ✓ recommended — an async factory
     ...
     return workflow.compile()
 
-graph = asyncio.run(_build())     # ✓ a graph compiled at import
+graph = asyncio.run(_build())     # ✗ gravity validate refuses asyncio.run at import
 graph = _build()                  # ✓ also fine — a coroutine is awaited
 ```
 
@@ -179,9 +180,10 @@ tools = await client.get_tools()  # exactly permissions.tools, nothing else
 Tool names are `<app>.<action>`, lowercase, from `gravity tools` — Gravity's
 names, never a vendor's (`gmail.read`, not `GMAIL_FETCH_EMAILS`). The gateway
 hands them to your model with `_` for `.` (`gmail_read`), because
-OpenAI-family models reject dots in function names. The sandbox allows no
-other egress — `requests.get(...)` to anywhere times out. Declare what you
-need; don't reach around it.
+OpenAI-family models reject dots in function names. Outbound network from the
+sandbox is open today (it may be locked down later), but anything that acts on a
+user's account must go through a tool: that is where the credentials are, and a
+direct call would have none. Declare what you need; don't reach around it.
 
 **Models** go through the LLM gateway with the same token:
 
@@ -202,6 +204,26 @@ emb = OpenAIEmbeddings(model="voyageai/voyage-4-lite",   # or google/gemini-embe
 vectors = await emb.aembed_documents(["first text", "second text"])
 ```
 
+**Images** come from an image model through the same URL and token: no tool to
+declare. Ask for image output; the picture comes back as a data URL, which is
+exactly what the corpus takes (§8):
+
+```python
+async with httpx.AsyncClient(timeout=120) as http:
+    resp = await http.post(f"{os.environ['GRAVITY_LLM_URL']}/chat/completions",
+        headers={"Authorization": f"Bearer {os.environ['GRAVITY_RUN_TOKEN']}"},
+        json={"model": "google/gemini-2.5-flash-image",   # or openai/gpt-5-image-mini
+              "modalities": ["image", "text"],
+              "messages": [{"role": "user", "content": "A flat illustration of ..., no text"}]})
+    resp.raise_for_status()
+    src = resp.json()["choices"][0]["message"]["images"][0]["image_url"]["url"]   # data:image/png;base64,...
+```
+
+An image is a few MB and the whole state is checkpointed after every step, so
+make pictures in the **last** node (or the one that builds the corpus) and keep
+them out of state until then. Each one is metered and counts toward the run's
+budget like any model call.
+
 Those three env vars — `GRAVITY_GATEWAY_URL`, `GRAVITY_LLM_URL`,
 `GRAVITY_RUN_TOKEN` — are the entire Gravity surface, plus the `gravity`
 package for tools on the platform (§8). No `OPENAI_API_KEY`: locally and in
@@ -221,12 +243,17 @@ Windows or macOS pins the wrong wheels and only fails at deploy.
 
 `gravity run --input k=v` runs your graph in your own venv against a real
 gateway, exactly as production does: tools over `GRAVITY_GATEWAY_URL`,
-models over `GRAVITY_LLM_URL`, both with `GRAVITY_RUN_TOKEN`. You set a
-different token once, `GRAVITY_DEV_TOKEN`, in `~/.gravity/.env`: each run
-trades it for a run token scoped to your `permissions.tools`, so an
-undeclared tool is refused locally exactly as it will be when hosted. Your
-agent only ever sees the run token. `GRAVITY_GATEWAY_URL` defaults to
-`http://127.0.0.1:8000/mcp` and `GRAVITY_LLM_URL` to the same host's `/v1`.
+models over `GRAVITY_LLM_URL`, both with `GRAVITY_RUN_TOKEN`. `gravity login`
+gives you a gateway token; each run trades it for a run token scoped to your
+`permissions.tools`, so an undeclared tool is refused locally exactly as it
+will be when hosted. Your agent only ever sees the run token. The gateway is
+the one Gravity names (`GET /api/cli/config`); set `GRAVITY_GATEWAY_URL` (and
+`GRAVITY_DEV_TOKEN`, in `~/.gravity/.env`) only for a gateway you run yourself.
+
+`gravity dev` opens a local dashboard over the same runs: a form from your
+manifest, a live timeline, approvals, the result and a history. A run from
+`gravity run` in the same folder shows up in it, and the other way round (both
+leave their record in `.gravity/runs/`; one run is live per folder).
 
 ## 7. What's checked where
 
@@ -250,10 +277,10 @@ graph. `gravity` is preinstalled in the image; don't put it in
 
 **Tools: `await gravity.tools()`** instead of your own `MultiServerMCPClient`.
 The same LangChain tools under the same names (`gmail_read`), from the same env
-vars. Off the platform (`gravity run`, tests) it is exactly the client in §4,
-but only if your venv has it: it stays out of `requirements.txt` and `gravity run`
-doesn't add it, so install it yourself (`uv pip install -e <repo>/code-first/python/gravity-sdk`)
-or `gravity run` fails with `No module named 'gravity'`.
+vars. Off the platform (`gravity run`, `gravity dev`, tests) the package is not
+installed and is not on PyPI: use the client in §4 directly, as the templates do
+(it is the same tools under the same names), or guard the import
+(`try: import gravity except ImportError: ...`). A plain dict works for the corpus.
 On the platform, each tool in `approvals.required_for` is wrapped: calling it
 checkpoints the run and stops it until the consumer decides, with no
 connection held open. Approved, the call runs with the arguments the consumer
@@ -328,6 +355,7 @@ corpus = gravity.Corpus(
         facts=[gravity.Fact(label="TAM", value="$18B", source="s1")],   # value: text or a number
         table=gravity.Table(columns=["Segment", "Teams"], rows=[["Founders", "1.2M"]]),
         notes="speaker notes / read-out text",
+        images=[gravity.Image(src=src, alt="server rack", caption="Option A")],   # data URL, see §4
         sections=[gravity.Section(heading="one level of nesting, same shape")],
     )],
     sources=[gravity.Source(id="s1", title="Report", url="https://example.com")],
@@ -336,7 +364,10 @@ return {**corpus.to_state(), "result": {"title": corpus.title}}
 ```
 
 A plain dict of the same shape works too. The models catch a typo when the
-corpus is built rather than when it's rendered. Set `result` as well: it's
+corpus is built rather than when it's rendered. Images (`png`, `jpeg`, `webp`
+or `gif` data URLs, at most 8 MB each and 12 per corpus) are embedded in the
+Word, PowerPoint and Markdown downloads and shown on `/app` and in `gravity
+dev`; an emailed output names each one as `[image: alt — caption]` instead. Set `result` as well: it's
 what the run returns.
 
 ## 9. Checklist

{gravity_cli-0.5.2 → gravity_cli-0.5.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: gravity-cli
-Version: 0.5.2
+Version: 0.5.4
 Summary: gravity cli — init, run, and push python agents to the Gravity marketplace
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.12
-Requires-Dist: gravity-schema==0.5.2
+Requires-Dist: gravity-schema==0.5.4
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: keyring>=25.0.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -108,10 +108,10 @@ The same rules apply on your laptop and when the agent runs hosted, because both
 
 | | |
 |---|---|
-| Commands | 16, grouped into build, publish, inspect, account and help |
+| Commands | 18, grouped into build an agent, publish, your agents, account and help |
 | Starter templates | 4: `minimal`, `structured`, `deepagent`, `chat` |
-| Tool catalog | 1,139 tools across 8 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn), 25 of them curated |
-| Test suite | 285 tests, run on Ubuntu and Windows with Python 3.12 and 3.13 |
+| Tool catalog | 1,402 tools across 15 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn, Jira, Confluence, Notion, WhatsApp, web search, and two built-ins), 28 of them curated |
+| Test suite | 466 tests (214 CLI, 252 schema), run on Ubuntu and Windows with Python 3.12 and 3.13 |
 | Runtime contract | 3 environment variables, no Gravity import in your code |
 
 ## Five things to know before you start
@@ -196,6 +196,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | **Build an agent** | [`gravity init`](#gravity-init) | Create a new agent from a template |
 | | [`gravity validate`](#gravity-validate) | Check your agent for mistakes before it runs |
 | | [`gravity run`](#gravity-run) | Run your agent locally against real tools |
+| | [`gravity dev`](#gravity-dev) | Open a local dashboard to run and watch your agent |
 | | [`gravity schedule`](#gravity-schedule) | Run your agent on its schedule, locally |
 | | [`gravity adapt`](#gravity-adapt) | Write a new slot adapter with AI, kept only if its tests pass |
 | **Publish** | [`gravity build`](#gravity-build) | Package your agent into `build/agent.zip` |
@@ -211,7 +212,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | **Help** | [`gravity guide`](#gravity-guide) | Read the builder guide: how to build a good agent |
 | | [`gravity help`](#gravity-help) | Show the list of commands |
 
-`gravity --api-url URL <command>` saves a different control-plane address to `~/.gravity/config.json`. Wherever a command takes `[path]`, it is the agent's folder and defaults to the current one.
+`gravity --api-url URL <command>` saves a different control-plane address to `~/.gravity/config.json`; it must start with `http://` or `https://`. The flag applies to the command it is given with; on later commands a `GRAVITY_API_URL` in `~/.gravity/.env` or the shell still wins over `config.json`, and the CLI says so when that is the case. `gravity --version` (or `-V`) prints the installed version. Wherever a command takes `[path]`, it is the agent's folder and defaults to the current one.
 
 ### `gravity init`
 
@@ -260,6 +261,9 @@ What it checks:
 - every imported write tool is under `approvals.required_for`
 - your code never names a write tool the manifest does not grant
 - a warning, never a failure, for read tools your code names but the manifest does not declare
+- `graph` is an `async def` (or a compiled graph), not a plain `def` or a bare value; a name bound by an import counts
+- nothing under `src/` reads `os.environ` or calls `asyncio.run` at module level, and no import is relative
+- a schedule runs at most every 5 minutes and restricts the day of the month or the weekday, not both
 
 ```bash
 gravity validate
@@ -291,10 +295,33 @@ gravity run --reply "make it shorter"
 - Requires a gateway token: the one `gravity login` stores, or `GRAVITY_DEV_TOKEN`.
 - A call to a tool in `approvals.required_for` pauses, shows what it would do, and waits for `y` or `n`. With no terminal to ask in, it is rejected.
 - Exits with code 0 when the run finishes and 1 when it fails.
+- Leaves a record in `.gravity/runs/<id>/` (`run.json` and `events.jsonl`), which is what `gravity dev` reads. One run is live per folder at a time, because runs share the folder's memory, store and thread files.
+
+### `gravity dev`
+
+Open a local dashboard for the agent in this folder: a form built from the manifest's inputs, a live timeline of each step, model call and tool call, approval buttons for held calls, the result, and a history of runs.
+
+```
+gravity dev [path] [--port 4747] [--no-open] [--llm-url URL]
+```
+
+| Option | Description |
+|---|---|
+| `--port N` | Port to listen on (default 4747). If it is taken, a free one is used and printed. |
+| `--no-open` | Print the address without opening a browser (SSH, WSL, CI) |
+| `--llm-url URL` | Model endpoint to use instead of `GRAVITY_LLM_URL` |
+
+- A run from `gravity run` in the same folder shows up in the dashboard live, and a run started in the dashboard is the same run (same engine, same memory, store and thread files), so `gravity run --reply` continues it.
+- It listens on `127.0.0.1` only, behind a random token in the printed address, for as long as the command runs. Ctrl+C stops it and any run it started. Nothing keeps running in the background.
+- Connected accounts: it shows the accounts your tools need and a Connect button for each one that is missing.
+- Approvals: a call held for approval can be decided in the terminal or in the dashboard; whichever answers first wins.
+- Cancel a run from the dashboard only if the dashboard started it; stop a terminal run with Ctrl+C in that terminal.
+- Results show as text. Word, PowerPoint and CSV files are produced by Gravity after you push. A file input is read as text here.
+- Same requirements as `gravity run`: a gateway token from `gravity login`, or `GRAVITY_DEV_TOKEN`.
 
 ### `gravity schedule`
 
-Run the agent on its `triggers.schedule`, the way the platform will, until you press Ctrl+C. Each tick is an ordinary run with the same inputs.
+Run the agent on its `triggers.schedule`, the way the platform will, until you press Ctrl+C. Ticks are timed in Asia/Kolkata, as the hosted schedules are. Each tick is an ordinary run with the same inputs; a missing required input is refused before the first tick.
 
 ```
 gravity schedule [path] [--input KEY=VALUE]... [--cron EXPR] [--now]
@@ -334,7 +361,7 @@ gravity adapt <slot> <name> --tools TOOLS [--hint TEXT] [--model MODEL] [--path
 gravity adapt deliver slack --tools slack.send,slack.list_channels --hint "post to #leads"
 ```
 
-Requires `tests/test_<slot>_adapters.py` in the project, `GRAVITY_DEV_TOKEN` and a reachable gateway. It makes up to 3 attempts, feeding each test failure back to the model.
+Requires `tests/test_<slot>_adapters.py` in the project and a gateway token (`gravity login`, or `GRAVITY_DEV_TOKEN`). It makes up to 3 attempts, feeding each test failure back to the model.
 
 ### `gravity build`
 
@@ -344,7 +371,7 @@ Validate the agent, then bundle it into `build/agent.zip` with its hashes in `bu
 gravity build [path]
 ```
 
-The bundle holds `manifest.yaml`, `requirements.txt`, `requirements.lock`, `src/` and `tests/`. The same source always produces the same bytes.
+The bundle holds `manifest.yaml`, `requirements.txt`, `requirements.lock`, `src/`, `tests/` and `tools_needed.yaml` when present; dotfiles under `src/` and `tests/` are left out. It refuses to build without `requirements.lock` (run `gravity validate` first). The same source always produces the same bytes.
 
 ```bash
 gravity build
@@ -362,6 +389,9 @@ gravity push [path]
 - Refuses if there is no build, or if the source changed since the build. Run `gravity build` again.
 - A published version can never be replaced. Raise `version` in the manifest to publish again.
 - Press Ctrl+C to stop waiting; the build carries on, and `gravity agents` shows its status.
+- The bundle may be at most 30 MB; a larger `agent.zip` is refused before upload. Remove large files from `src/` or `tests/` and build again.
+- The manifest travels in a request header, so `manifest.yaml` must stay under 12 KB once encoded; a larger one is refused before upload. Keep descriptions and help text short.
+- Re-pushing a version whose build failed, without changing the source, is refused with the failure reason: fix it and raise `version` in the manifest.
 
 ```bash
 gravity build && gravity push
@@ -369,7 +399,7 @@ gravity build && gravity push
 
 ### `gravity agents`
 
-List your published agents with their version, status and last update.
+List your published agents with their version, status, review and last update. Under the table it prints what the Gravity team told you: the reviewer's notes on an approved or rejected version, and the reason if an agent was turned off. A rejected version needs a fix and a new `version:` in `manifest.yaml` before you push again. A failed build prints its reason under the table.
 
 ```
 gravity agents
@@ -428,7 +458,7 @@ gravity logout
 
 ### `gravity whoami`
 
-Show the account you are signed in as, and whether you hold a gateway token and until when.
+Show the account you are signed in as, and whether you hold a gateway token and until when (an expired one is a warning).
 
 ```
 gravity whoami
@@ -628,7 +658,7 @@ resources:
 triggers:
   manual: true                    # the consumer can start a run
   schedule:
-    cron: "0 8 * * 1-5"           # weekdays at 08:00, local time
+    cron: "0 8 * * 1-5"           # weekdays at 08:00, Asia/Kolkata
     consumer_can_change: true
 
 state:
@@ -672,7 +702,7 @@ outputs:                          # extra formats the platform renders and deliv
 | `approvals.required_for` | no | none | Tools that pause until a person approves. Each must also be declared under `permissions.tools` or a slot adapter. |
 | `resources.memory_mb` | no | `512` | 128 to 4096. A request; the platform may lower it. |
 | `triggers.manual` | no | `true` | Whether the consumer can start a run. Something must start the agent: `manual`, a `schedule` or a `webhook`. |
-| `triggers.schedule` | no | none | `cron` (5 fields, local time, such as `"0 9 * * 1"`) and `consumer_can_change` (default `true`). |
+| `triggers.schedule` | no | none | `cron` (5 fields, Asia/Kolkata, such as `"0 9 * * 1"`; every 5 minutes at the fastest; day of month or weekday, not both) and `consumer_can_change` (default `true`). |
 | `triggers.webhook` | no | none | A list of events; `github.push` is the only one today. |
 | `state.max_kb` | no | no memory | Include `state:` to keep memory between runs, in `state["memory"]`. 1 to 256 KB. |
 | `slots.<name>` | no | none | A swappable part: `label`, `default` adapter, and `adapters` mapping each adapter name to the tools it may call. Code lives in `src/adapters/<slot>/<adapter>.py`. Slot names cannot repeat an input's name. |
@@ -700,6 +730,8 @@ Files the CLI writes:
 | `.gravity/payload.json` | `run` | The inputs passed to the agent |
 | `.gravity/thread.json` | `run` | The last conversation of a chat agent, for `--reply` |
 | `.gravity/memory.json` | `run` | Memory kept between runs, when the manifest declares `state` |
+| `.gravity/payload.json` | `run`, `dev` | The run's inputs for the runner; deleted when the run ends (`run.json` keeps them with secret inputs redacted) |
+| `.gravity/tool_schemas.json` | `adapt` | Argument schemas of every tool the slot uses, read from the gateway |
 
 The template `.gitignore` excludes `build/`, `.gravity/` and `.env`.
 
@@ -747,7 +779,12 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 | `Can't reach the gateway at …` | No gateway at that address. Set `GRAVITY_GATEWAY_URL` to your gateway's `/mcp` address. |
 | `The gateway refused this run` | The gateway rejected the token or a declared tool. Run `gravity whoami` to check the token, or `gravity login` for a fresh one. |
 | `You are not signed in` | A control-plane command without credentials. Run `gravity login`. |
-| `Can't reach Gravity at …` | The control plane did not answer. Check `GRAVITY_API_URL` in `~/.gravity/.env`. |
+| `Can't reach Gravity at …` | The control plane did not answer. Check `GRAVITY_API_URL` in `~/.gravity/.env`, or `api_url` in `~/.gravity/config.json` (set by `gravity --api-url`). |
+| `Gravity refused GRAVITY_API_TOKEN` | The dev token in `~/.gravity/.env` is wrong or revoked. Fix it there, or remove it and run `gravity login`. |
+| `… did not answer with JSON` or `Gravity answered 5xx at …` | A proxy, VPN sign-in page or outage is answering instead of Gravity. Check `GRAVITY_API_URL`; for a 5xx wait a minute and retry, then tell Gravity if it persists. |
+| `Another run is live` | Runs in one folder take turns. Wait for it, or stop it; if none is live, delete `.gravity/run.lock`. |
+| `Manifest is not UTF-8 text` | Notepad saved it as "Unicode" (UTF-16). Re-save it with Encoding: UTF-8. |
+| `could not load the agent: No module named …` only on Windows | Windows limits paths to 260 characters and some packages in `.venv` exceed it from a deep folder. Move the agent to a shorter path or enable long paths. |
 | `Missing required input: …` | Pass each required input with `--input name=value`, or give it a `default` in the manifest. |
 | `No build to push` or `The build is stale` | Run `gravity build` again after any change to `src/`, the manifest or the requirements. |
 | `✗ requirements.lock` in `gravity validate` | A dependency has no prebuilt package for the platform image (ARM64 Linux). Pick a version that publishes one, or a different package. |
@@ -755,6 +792,8 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
+- **0.5.4** `gravity agents` shows each agent's review: a REVIEW column (not submitted, submitted, approved, rejected), and under "From the Gravity team" the reviewer's notes and what to do next. An agent the Gravity team turned off shows as `off` with the reason. UPDATED reads "3 min ago" instead of a timestamp, and status and review are coloured. Also, from a full audit of every command: `gravity --version`. Clear messages instead of tracebacks for: a proxy or sign-in page answering instead of Gravity, a refused `GRAVITY_API_TOKEN` or `GRAVITY_DEV_TOKEN`, an expired sign-in code, a non-UTF-8 manifest, an out-of-range `--port`, a missing agent folder, a malformed session file. `gravity validate` now refuses what the build would refuse: a `graph` that is not an async factory, `os.environ` or `asyncio.run` at import, relative imports, unquoted `python: 3.12`, schedules faster than every 5 minutes or with both day fields, out-of-range cron fields; it accepts a re-exported `graph`. `gravity agents` shows the review status and failure reasons; `gravity runs` never shortens an id; `gravity logs` never wraps. `gravity push` refuses a bundle over 30 MB or a manifest over 12 KB before uploading, and says why when a failed version is re-pushed. `gravity build` ships `tools_needed.yaml`, leaves dotfiles out, and refuses to build without `requirements.lock`. `gravity adapt` leaves the folder untouched when a model call fails. `gravity schedule` checks inputs before the first tick and runs on Asia/Kolkata like the hosted schedules. `gravity run` deletes `.gravity/payload.json` after the run, warns when no `.venv` is present, and keeps a plain agent's `result`. `gravity connect <app>` refuses on the shared test account instead of attaching your account to it. The builder guide and agent standard describe the real flow (init, validate, run or dev, build, push, review on /app).
+- **0.5.3** `gravity dev` opens a local dashboard for your agent: a form from your manifest, a live timeline, approvals, the result and run history; runs from `gravity run` in the same folder show up in it live, and the other way round. WhatsApp joins the catalog (51 tools; 1,402 across 15 apps including the curated and built-in ones). Agents can return generated images: put them in a corpus section's `images` and they land in the Word, PowerPoint and Markdown outputs. The agent standard now shows how to generate images and embeddings through the gateway. `NEEDS_RECONNECT` on the shared test account tells you to ask Gravity, not to connect your own account.
 - **0.5.2** Jira, Confluence and Notion join the catalog: 1,351 tools across 11 apps. `get_store()` works in local runs, kept in `.gravity/store.json`. Renewing an expired sign-in keeps your gateway token, so `gravity run` keeps working after an hour. Commands start faster: the catalog loads in a quarter of the time.
 - **0.5.0** `gravity connect` links your own accounts. `web.search` and `web.fetch` join the catalog. `gravity validate` now refuses a tool that isn't in the catalog, an imported write tool without an approval, and code that names a write tool the manifest doesn't grant. `gravity tools` reads the gateway's list and needs no sign-in. On Windows the session stays in the keychain instead of a file.
 - **0.4.4** Same code as 0.4.3, released from this repository so the GitHub release, the tag and PyPI line up again. Adds `RELEASING.md`.

{gravity_cli-0.5.2 → gravity_cli-0.5.4}/README.md

@@ -91,10 +91,10 @@ The same rules apply on your laptop and when the agent runs hosted, because both
 
 | | |
 |---|---|
-| Commands | 16, grouped into build, publish, inspect, account and help |
+| Commands | 18, grouped into build an agent, publish, your agents, account and help |
 | Starter templates | 4: `minimal`, `structured`, `deepagent`, `chat` |
-| Tool catalog | 1,139 tools across 8 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn), 25 of them curated |
-| Test suite | 285 tests, run on Ubuntu and Windows with Python 3.12 and 3.13 |
+| Tool catalog | 1,402 tools across 15 apps (Gmail, Slack, Linear, GitHub, Calendar, Drive, Sheets, LinkedIn, Jira, Confluence, Notion, WhatsApp, web search, and two built-ins), 28 of them curated |
+| Test suite | 466 tests (214 CLI, 252 schema), run on Ubuntu and Windows with Python 3.12 and 3.13 |
 | Runtime contract | 3 environment variables, no Gravity import in your code |
 
 ## Five things to know before you start
@@ -179,6 +179,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | **Build an agent** | [`gravity init`](#gravity-init) | Create a new agent from a template |
 | | [`gravity validate`](#gravity-validate) | Check your agent for mistakes before it runs |
 | | [`gravity run`](#gravity-run) | Run your agent locally against real tools |
+| | [`gravity dev`](#gravity-dev) | Open a local dashboard to run and watch your agent |
 | | [`gravity schedule`](#gravity-schedule) | Run your agent on its schedule, locally |
 | | [`gravity adapt`](#gravity-adapt) | Write a new slot adapter with AI, kept only if its tests pass |
 | **Publish** | [`gravity build`](#gravity-build) | Package your agent into `build/agent.zip` |
@@ -194,7 +195,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | **Help** | [`gravity guide`](#gravity-guide) | Read the builder guide: how to build a good agent |
 | | [`gravity help`](#gravity-help) | Show the list of commands |
 
-`gravity --api-url URL <command>` saves a different control-plane address to `~/.gravity/config.json`. Wherever a command takes `[path]`, it is the agent's folder and defaults to the current one.
+`gravity --api-url URL <command>` saves a different control-plane address to `~/.gravity/config.json`; it must start with `http://` or `https://`. The flag applies to the command it is given with; on later commands a `GRAVITY_API_URL` in `~/.gravity/.env` or the shell still wins over `config.json`, and the CLI says so when that is the case. `gravity --version` (or `-V`) prints the installed version. Wherever a command takes `[path]`, it is the agent's folder and defaults to the current one.
 
 ### `gravity init`
 
@@ -243,6 +244,9 @@ What it checks:
 - every imported write tool is under `approvals.required_for`
 - your code never names a write tool the manifest does not grant
 - a warning, never a failure, for read tools your code names but the manifest does not declare
+- `graph` is an `async def` (or a compiled graph), not a plain `def` or a bare value; a name bound by an import counts
+- nothing under `src/` reads `os.environ` or calls `asyncio.run` at module level, and no import is relative
+- a schedule runs at most every 5 minutes and restricts the day of the month or the weekday, not both
 
 ```bash
 gravity validate
@@ -274,10 +278,33 @@ gravity run --reply "make it shorter"
 - Requires a gateway token: the one `gravity login` stores, or `GRAVITY_DEV_TOKEN`.
 - A call to a tool in `approvals.required_for` pauses, shows what it would do, and waits for `y` or `n`. With no terminal to ask in, it is rejected.
 - Exits with code 0 when the run finishes and 1 when it fails.
+- Leaves a record in `.gravity/runs/<id>/` (`run.json` and `events.jsonl`), which is what `gravity dev` reads. One run is live per folder at a time, because runs share the folder's memory, store and thread files.
+
+### `gravity dev`
+
+Open a local dashboard for the agent in this folder: a form built from the manifest's inputs, a live timeline of each step, model call and tool call, approval buttons for held calls, the result, and a history of runs.
+
+```
+gravity dev [path] [--port 4747] [--no-open] [--llm-url URL]
+```
+
+| Option | Description |
+|---|---|
+| `--port N` | Port to listen on (default 4747). If it is taken, a free one is used and printed. |
+| `--no-open` | Print the address without opening a browser (SSH, WSL, CI) |
+| `--llm-url URL` | Model endpoint to use instead of `GRAVITY_LLM_URL` |
+
+- A run from `gravity run` in the same folder shows up in the dashboard live, and a run started in the dashboard is the same run (same engine, same memory, store and thread files), so `gravity run --reply` continues it.
+- It listens on `127.0.0.1` only, behind a random token in the printed address, for as long as the command runs. Ctrl+C stops it and any run it started. Nothing keeps running in the background.
+- Connected accounts: it shows the accounts your tools need and a Connect button for each one that is missing.
+- Approvals: a call held for approval can be decided in the terminal or in the dashboard; whichever answers first wins.
+- Cancel a run from the dashboard only if the dashboard started it; stop a terminal run with Ctrl+C in that terminal.
+- Results show as text. Word, PowerPoint and CSV files are produced by Gravity after you push. A file input is read as text here.
+- Same requirements as `gravity run`: a gateway token from `gravity login`, or `GRAVITY_DEV_TOKEN`.
 
 ### `gravity schedule`
 
-Run the agent on its `triggers.schedule`, the way the platform will, until you press Ctrl+C. Each tick is an ordinary run with the same inputs.
+Run the agent on its `triggers.schedule`, the way the platform will, until you press Ctrl+C. Ticks are timed in Asia/Kolkata, as the hosted schedules are. Each tick is an ordinary run with the same inputs; a missing required input is refused before the first tick.
 
 ```
 gravity schedule [path] [--input KEY=VALUE]... [--cron EXPR] [--now]
@@ -317,7 +344,7 @@ gravity adapt <slot> <name> --tools TOOLS [--hint TEXT] [--model MODEL] [--path
 gravity adapt deliver slack --tools slack.send,slack.list_channels --hint "post to #leads"
 ```
 
-Requires `tests/test_<slot>_adapters.py` in the project, `GRAVITY_DEV_TOKEN` and a reachable gateway. It makes up to 3 attempts, feeding each test failure back to the model.
+Requires `tests/test_<slot>_adapters.py` in the project and a gateway token (`gravity login`, or `GRAVITY_DEV_TOKEN`). It makes up to 3 attempts, feeding each test failure back to the model.
 
 ### `gravity build`
 
@@ -327,7 +354,7 @@ Validate the agent, then bundle it into `build/agent.zip` with its hashes in `bu
 gravity build [path]
 ```
 
-The bundle holds `manifest.yaml`, `requirements.txt`, `requirements.lock`, `src/` and `tests/`. The same source always produces the same bytes.
+The bundle holds `manifest.yaml`, `requirements.txt`, `requirements.lock`, `src/`, `tests/` and `tools_needed.yaml` when present; dotfiles under `src/` and `tests/` are left out. It refuses to build without `requirements.lock` (run `gravity validate` first). The same source always produces the same bytes.
 
 ```bash
 gravity build
@@ -345,6 +372,9 @@ gravity push [path]
 - Refuses if there is no build, or if the source changed since the build. Run `gravity build` again.
 - A published version can never be replaced. Raise `version` in the manifest to publish again.
 - Press Ctrl+C to stop waiting; the build carries on, and `gravity agents` shows its status.
+- The bundle may be at most 30 MB; a larger `agent.zip` is refused before upload. Remove large files from `src/` or `tests/` and build again.
+- The manifest travels in a request header, so `manifest.yaml` must stay under 12 KB once encoded; a larger one is refused before upload. Keep descriptions and help text short.
+- Re-pushing a version whose build failed, without changing the source, is refused with the failure reason: fix it and raise `version` in the manifest.
 
 ```bash
 gravity build && gravity push
@@ -352,7 +382,7 @@ gravity build && gravity push
 
 ### `gravity agents`
 
-List your published agents with their version, status and last update.
+List your published agents with their version, status, review and last update. Under the table it prints what the Gravity team told you: the reviewer's notes on an approved or rejected version, and the reason if an agent was turned off. A rejected version needs a fix and a new `version:` in `manifest.yaml` before you push again. A failed build prints its reason under the table.
 
 ```
 gravity agents
@@ -411,7 +441,7 @@ gravity logout
 
 ### `gravity whoami`
 
-Show the account you are signed in as, and whether you hold a gateway token and until when.
+Show the account you are signed in as, and whether you hold a gateway token and until when (an expired one is a warning).
 
 ```
 gravity whoami
@@ -611,7 +641,7 @@ resources:
 triggers:
   manual: true                    # the consumer can start a run
   schedule:
-    cron: "0 8 * * 1-5"           # weekdays at 08:00, local time
+    cron: "0 8 * * 1-5"           # weekdays at 08:00, Asia/Kolkata
     consumer_can_change: true
 
 state:
@@ -655,7 +685,7 @@ outputs:                          # extra formats the platform renders and deliv
 | `approvals.required_for` | no | none | Tools that pause until a person approves. Each must also be declared under `permissions.tools` or a slot adapter. |
 | `resources.memory_mb` | no | `512` | 128 to 4096. A request; the platform may lower it. |
 | `triggers.manual` | no | `true` | Whether the consumer can start a run. Something must start the agent: `manual`, a `schedule` or a `webhook`. |
-| `triggers.schedule` | no | none | `cron` (5 fields, local time, such as `"0 9 * * 1"`) and `consumer_can_change` (default `true`). |
+| `triggers.schedule` | no | none | `cron` (5 fields, Asia/Kolkata, such as `"0 9 * * 1"`; every 5 minutes at the fastest; day of month or weekday, not both) and `consumer_can_change` (default `true`). |
 | `triggers.webhook` | no | none | A list of events; `github.push` is the only one today. |
 | `state.max_kb` | no | no memory | Include `state:` to keep memory between runs, in `state["memory"]`. 1 to 256 KB. |
 | `slots.<name>` | no | none | A swappable part: `label`, `default` adapter, and `adapters` mapping each adapter name to the tools it may call. Code lives in `src/adapters/<slot>/<adapter>.py`. Slot names cannot repeat an input's name. |
@@ -683,6 +713,8 @@ Files the CLI writes:
 | `.gravity/payload.json` | `run` | The inputs passed to the agent |
 | `.gravity/thread.json` | `run` | The last conversation of a chat agent, for `--reply` |
 | `.gravity/memory.json` | `run` | Memory kept between runs, when the manifest declares `state` |
+| `.gravity/payload.json` | `run`, `dev` | The run's inputs for the runner; deleted when the run ends (`run.json` keeps them with secret inputs redacted) |
+| `.gravity/tool_schemas.json` | `adapt` | Argument schemas of every tool the slot uses, read from the gateway |
 
 The template `.gitignore` excludes `build/`, `.gravity/` and `.env`.
 
@@ -730,7 +762,12 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 | `Can't reach the gateway at …` | No gateway at that address. Set `GRAVITY_GATEWAY_URL` to your gateway's `/mcp` address. |
 | `The gateway refused this run` | The gateway rejected the token or a declared tool. Run `gravity whoami` to check the token, or `gravity login` for a fresh one. |
 | `You are not signed in` | A control-plane command without credentials. Run `gravity login`. |
-| `Can't reach Gravity at …` | The control plane did not answer. Check `GRAVITY_API_URL` in `~/.gravity/.env`. |
+| `Can't reach Gravity at …` | The control plane did not answer. Check `GRAVITY_API_URL` in `~/.gravity/.env`, or `api_url` in `~/.gravity/config.json` (set by `gravity --api-url`). |
+| `Gravity refused GRAVITY_API_TOKEN` | The dev token in `~/.gravity/.env` is wrong or revoked. Fix it there, or remove it and run `gravity login`. |
+| `… did not answer with JSON` or `Gravity answered 5xx at …` | A proxy, VPN sign-in page or outage is answering instead of Gravity. Check `GRAVITY_API_URL`; for a 5xx wait a minute and retry, then tell Gravity if it persists. |
+| `Another run is live` | Runs in one folder take turns. Wait for it, or stop it; if none is live, delete `.gravity/run.lock`. |
+| `Manifest is not UTF-8 text` | Notepad saved it as "Unicode" (UTF-16). Re-save it with Encoding: UTF-8. |
+| `could not load the agent: No module named …` only on Windows | Windows limits paths to 260 characters and some packages in `.venv` exceed it from a deep folder. Move the agent to a shorter path or enable long paths. |
 | `Missing required input: …` | Pass each required input with `--input name=value`, or give it a `default` in the manifest. |
 | `No build to push` or `The build is stale` | Run `gravity build` again after any change to `src/`, the manifest or the requirements. |
 | `✗ requirements.lock` in `gravity validate` | A dependency has no prebuilt package for the platform image (ARM64 Linux). Pick a version that publishes one, or a different package. |
@@ -738,6 +775,8 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
+- **0.5.4** `gravity agents` shows each agent's review: a REVIEW column (not submitted, submitted, approved, rejected), and under "From the Gravity team" the reviewer's notes and what to do next. An agent the Gravity team turned off shows as `off` with the reason. UPDATED reads "3 min ago" instead of a timestamp, and status and review are coloured. Also, from a full audit of every command: `gravity --version`. Clear messages instead of tracebacks for: a proxy or sign-in page answering instead of Gravity, a refused `GRAVITY_API_TOKEN` or `GRAVITY_DEV_TOKEN`, an expired sign-in code, a non-UTF-8 manifest, an out-of-range `--port`, a missing agent folder, a malformed session file. `gravity validate` now refuses what the build would refuse: a `graph` that is not an async factory, `os.environ` or `asyncio.run` at import, relative imports, unquoted `python: 3.12`, schedules faster than every 5 minutes or with both day fields, out-of-range cron fields; it accepts a re-exported `graph`. `gravity agents` shows the review status and failure reasons; `gravity runs` never shortens an id; `gravity logs` never wraps. `gravity push` refuses a bundle over 30 MB or a manifest over 12 KB before uploading, and says why when a failed version is re-pushed. `gravity build` ships `tools_needed.yaml`, leaves dotfiles out, and refuses to build without `requirements.lock`. `gravity adapt` leaves the folder untouched when a model call fails. `gravity schedule` checks inputs before the first tick and runs on Asia/Kolkata like the hosted schedules. `gravity run` deletes `.gravity/payload.json` after the run, warns when no `.venv` is present, and keeps a plain agent's `result`. `gravity connect <app>` refuses on the shared test account instead of attaching your account to it. The builder guide and agent standard describe the real flow (init, validate, run or dev, build, push, review on /app).
+- **0.5.3** `gravity dev` opens a local dashboard for your agent: a form from your manifest, a live timeline, approvals, the result and run history; runs from `gravity run` in the same folder show up in it live, and the other way round. WhatsApp joins the catalog (51 tools; 1,402 across 15 apps including the curated and built-in ones). Agents can return generated images: put them in a corpus section's `images` and they land in the Word, PowerPoint and Markdown outputs. The agent standard now shows how to generate images and embeddings through the gateway. `NEEDS_RECONNECT` on the shared test account tells you to ask Gravity, not to connect your own account.
 - **0.5.2** Jira, Confluence and Notion join the catalog: 1,351 tools across 11 apps. `get_store()` works in local runs, kept in `.gravity/store.json`. Renewing an expired sign-in keeps your gateway token, so `gravity run` keeps working after an hour. Commands start faster: the catalog loads in a quarter of the time.
 - **0.5.0** `gravity connect` links your own accounts. `web.search` and `web.fetch` join the catalog. `gravity validate` now refuses a tool that isn't in the catalog, an imported write tool without an approval, and code that names a write tool the manifest doesn't grant. `gravity tools` reads the gateway's list and needs no sign-in. On Windows the session stays in the keychain instead of a file.
 - **0.4.4** Same code as 0.4.3, released from this repository so the GitHub release, the tag and PyPI line up again. Adds `RELEASING.md`.