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

{gravity_cli-0.5.3 → 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:
 
@@ -241,12 +243,12 @@ 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
@@ -275,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

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: gravity-cli
-Version: 0.5.3
+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.3
+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
@@ -212,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`
 
@@ -261,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
@@ -318,7 +321,7 @@ gravity dev [path] [--port 4747] [--no-open] [--llm-url URL]
 
 ### `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]
@@ -358,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`
 
@@ -368,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
@@ -386,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
@@ -393,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
@@ -452,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
@@ -652,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:
@@ -696,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. |
@@ -724,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`.
 
@@ -771,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. |
@@ -779,7 +792,8 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
-- **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,374 across 12 apps). 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.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.3 → 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
@@ -195,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`
 
@@ -244,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
@@ -301,7 +304,7 @@ gravity dev [path] [--port 4747] [--no-open] [--llm-url URL]
 
 ### `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]
@@ -341,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`
 
@@ -351,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
@@ -369,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
@@ -376,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
@@ -435,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
@@ -635,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:
@@ -679,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. |
@@ -707,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`.
 
@@ -754,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. |
@@ -762,7 +775,8 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
-- **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,374 across 12 apps). 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.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.3 → gravity_cli-0.5.4}/packages/gravity-schema/gravity_schema/cron.py

@@ -1,11 +1,16 @@
-"""Standard 5-field cron, local time. Day-of-week 0 or 7 is Sunday; when both day
+"""Standard 5-field cron, in whatever timezone the `after` datetime carries (gravity
+schedule passes Asia/Kolkata, like the hosted schedules). Day-of-week 0 or 7 is Sunday; when both day
 fields are restricted, either matching is enough (as in cron itself)."""
 
 from __future__ import annotations
 
+import math
 from datetime import datetime, timedelta
+from itertools import pairwise
 
 _BOUNDS = ((0, 59), (0, 23), (1, 31), (1, 12), (0, 7))
+# Every tick is a paid run; the control plane's MIN_SCHEDULE_MINUTES.
+MIN_GAP_MINUTES = 5
 
 
 def _values(field: str, low: int, high: int) -> set[int]:
@@ -22,6 +27,26 @@ def _values(field: str, low: int, high: int) -> set[int]:
     return out
 
 
+def field_values(expr: str) -> list[set[int]]:
+    """Each field's values. ValueError when a field is malformed, empty or out of its range."""
+    out = [_values(f, lo, hi) for f, (lo, hi) in zip(expr.split(), _BOUNDS)]
+    for vals, (lo, hi) in zip(out, _BOUNDS):
+        if not vals or min(vals) < lo or max(vals) > hi:
+            raise ValueError(f"'{expr}' has a value out of range")
+    return out
+
+
+def min_gap(expr: str) -> float:
+    """Minutes between the closest two fires, from the minute and hour fields alone (the day
+    fields can only widen it). Same arithmetic as the control plane's checkScheduleFloor."""
+    minutes, hours = field_values(expr)[:2]
+    mins = sorted(minutes)
+    gap = min((b - a for a, b in pairwise(mins)), default=math.inf)
+    if any((h + 1) % 24 in hours for h in hours):
+        gap = min(gap, 60 - mins[-1] + mins[0])
+    return gap
+
+
 def matches(expr: str, at: datetime) -> bool:
     fields = expr.split()
     minute, hour, dom, month, dow = (_values(f, *b) for f, b in zip(fields, _BOUNDS))

{gravity_cli-0.5.3 → gravity_cli-0.5.4}/packages/gravity-schema/gravity_schema/manifest.py

@@ -9,6 +9,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 from pydantic_core import PydanticCustomError
 
 from . import contract as C
+from . import cron
 from .errors import ErrorCode
 
 # Unknown fields are rejected, so a newer-contract field is reported, not dropped.
@@ -99,6 +100,18 @@ class RuntimeSpec(BaseModel):
             )
         return v
 
+    @field_validator("python", mode="before")
+    @classmethod
+    def _check_python_is_text(cls, v: Any) -> Any:
+        # YAML reads an unquoted 3.12 as a float (and 3.10 as 3.1).
+        if isinstance(v, (int, float)):
+            raise PydanticCustomError(
+                ErrorCode.INVALID_PYTHON_VERSION.value,
+                "Python version {value} is not quoted text.",
+                {"value": v, "remediation": 'Put it in quotes: python: "3.12".'},
+            )
+        return v
+
     @field_validator("python")
     @classmethod
     def _check_python(cls, v: str) -> str:
@@ -375,6 +388,37 @@ class ScheduleSpec(BaseModel):
                     ),
                 },
             )
+        try:
+            cron.field_values(v)
+        except ValueError:
+            raise PydanticCustomError(
+                ErrorCode.INVALID_TRIGGER.value,
+                "Schedule '{value}' has a value out of range.",
+                {
+                    "value": v,
+                    "remediation": (
+                        "Minutes are 0-59, hours 0-23, days 1-31, months 1-12 and "
+                        "weekdays 0-7 (0 and 7 are Sunday)."
+                    ),
+                },
+            ) from None
+        # The platform's scheduler cannot express cron's "either day matches".
+        if fields[2] != "*" and fields[4] != "*":
+            raise PydanticCustomError(
+                ErrorCode.INVALID_TRIGGER.value,
+                "Schedule '{value}' restricts both the day of the month and the weekday.",
+                {"value": v, "remediation": "Set one of them to *."},
+            )
+        if cron.min_gap(v) < cron.MIN_GAP_MINUTES:
+            raise PydanticCustomError(
+                ErrorCode.INVALID_TRIGGER.value,
+                "Schedules can run at most every {limit} minutes.",
+                {
+                    "value": v,
+                    "limit": cron.MIN_GAP_MINUTES,
+                    "remediation": f"Use '*/{cron.MIN_GAP_MINUTES} * * * *' or something slower.",
+                },
+            )
         return v
 
 
@@ -527,6 +571,18 @@ class Manifest(BaseModel):
             )
         return v
 
+    @field_validator("version", mode="before")
+    @classmethod
+    def _check_version_is_text(cls, v: Any) -> Any:
+        # YAML reads an unquoted 1.0 as a float.
+        if isinstance(v, (int, float)):
+            raise PydanticCustomError(
+                ErrorCode.INVALID_AGENT_VERSION.value,
+                "Agent version {value} is not quoted text.",
+                {"value": v, "remediation": 'Put it in quotes: version: "1.0.0".'},
+            )
+        return v
+
     @field_validator("version")
     @classmethod
     def _check_version(cls, v: str) -> str:

{gravity_cli-0.5.3 → gravity_cli-0.5.4}/packages/gravity-schema/gravity_schema/validation.py

@@ -156,7 +156,17 @@ def load_manifest_file(
             "Run `gravity init` to create one, or check the path.",
             str(p),
         )
-    return load_manifest_text(p.read_text(encoding="utf-8"), catalog=catalog)
+    try:
+        text = p.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        # Notepad's "Unicode" is UTF-16; a BOM-only UTF-8 file decodes fine and YAML skips the BOM.
+        raise _fail(
+            ErrorCode.MALFORMED_YAML,
+            "Manifest is not UTF-8 text.",
+            "Save the file as UTF-8 (in Notepad: Encoding, then UTF-8).",
+            str(p),
+        ) from None
+    return load_manifest_text(text, catalog=catalog)
 
 
 def _fail(code: ErrorCode, message: str, remediation: str, location: str = "") -> ManifestValidationError:

{gravity_cli-0.5.3 → gravity_cli-0.5.4}/packages/gravity-schema/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gravity-schema"
-version = "0.5.3"
+version = "0.5.4"
 description = "Gravity agent manifest contract — models, validation, and JSON Schema export"
 readme = "README.md"
 license = "Apache-2.0"

{gravity_cli-0.5.3 → gravity_cli-0.5.4}/packages/gravity-schema/tests/test_cron.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 
 import pytest
-from gravity_schema.cron import matches, next_run
+from gravity_schema.cron import field_values, matches, min_gap, next_run
 
 MON_0900 = datetime(2026, 9, 28, 9, 0)  # a Monday
 
@@ -29,3 +29,18 @@ def test_next_run_is_strictly_after():
     assert next_run("0 9 * * *", MON_0900) == datetime(2026, 9, 29, 9, 0)
     with pytest.raises(ValueError):
         next_run("0 0 31 2 *", MON_0900)  # 31 February
+
+
+def test_field_values_checks_every_range():
+    assert field_values("0 9 1 * 7")[4] == {7}
+    for bad in ("60 * * * *", "0 24 * * *", "0 0 0 * *", "0 0 32 * *", "0 0 * 13 *", "0 0 * * 8", "5-3 * * * *", "*/0 * * * *"):
+        with pytest.raises(ValueError):
+            field_values(bad)
+
+
+def test_min_gap_is_the_closest_two_fires():
+    assert min_gap("*/5 * * * *") == 5
+    assert min_gap("0,3 * * * *") == 3
+    assert min_gap("0,59 * * * *") == 1  # 10:59 then 11:00
+    assert min_gap("59 9 * * *") == float("inf")  # once a day; the day fields don't matter
+    assert min_gap("58 9,10 * * *") == 60