gravity-cli 0.8.0__tar.gz → 0.10.0__tar.gz

{gravity_cli-0.8.0 → gravity_cli-0.10.0}/.env.example

@@ -2,7 +2,7 @@
 # Every gravity command loads that file. Never commit the filled-in copy.
 # What each variable does: README.md, "Environment variables".
 
-# --- gravity run / schedule / adapt -------------------------------------
+# --- gravity run / dev / schedule / check / connect -----------------------
 # A gateway token. Leave unset: gravity login stores one for you.
 # Set it only for a local gateway (it prints one at startup, or uses its LOCAL_DEV_TOKEN).
 # GRAVITY_DEV_TOKEN=
@@ -14,9 +14,9 @@
 # The model endpoint. Leave unset: it follows the gateway (<gateway>/v1).
 # GRAVITY_LLM_URL=
 
-# --- push / tools / agents / runs / logs / whoami ------------------------
-# The control plane. Leave unset for Gravity's; set it only for a local one.
-# GRAVITY_API_URL=http://localhost:3010
+# --- push / tools / agents / runs / logs / whoami -------------------------
+# The control plane. Leave unset for the default; set it for another one.
+# GRAVITY_API_URL=http://127.0.0.1:3010
 
 # Development only: the control plane's dev token, instead of `gravity login`.
 # GRAVITY_API_TOKEN=

gravity_cli-0.10.0/.github/workflows/composio-watch.yml

@@ -0,0 +1,47 @@
+name: Composio watch
+
+# Every Monday: compare the Composio toolkit versions our connectors pin with what Composio serves, and open (or
+# update) one issue when something needs review. scripts/composio-watch.sh says which cases alert and which don't.
+on:
+  schedule:
+    - cron: "0 6 * * 1"   # Mondays 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: composio-watch
+  cancel-in-progress: false
+
+jobs:
+  watch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install gravity-schema
+        run: pip install -e packages/gravity-schema
+
+      - name: Check Composio
+        run: bash scripts/composio-watch.sh
+        env:
+          COMPOSIO_API_KEY: ${{ secrets.API_COMPOSIO_API_KEY }}
+          GH_TOKEN: ${{ github.token }}
+          WATCH_ASSIGNEE: ${{ vars.COMPOSIO_WATCH_ASSIGNEE || 'anwesha0123' }}
+          WATCH_OUT: ${{ runner.temp }}/composio-watch
+
+      - name: Keep the report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: composio-watch-report
+          path: ${{ runner.temp }}/composio-watch
+          if-no-files-found: ignore
+          retention-days: 30

{gravity_cli-0.8.0 → gravity_cli-0.10.0}/AGENT_STANDARD.md

@@ -12,6 +12,9 @@ The manifest rules below are enforced by `python/gravity-schema`, the one
 model shared by the CLI, the runner and the server. Where this document and
 that package disagree, the package wins and this document has a bug.
 
+Contract v2 (capabilities instead of tools, the person picks the app) is a preview with its own standard:
+`AGENT_STANDARD_V2.md`. The CLI accepts both; a manifest without `contract` is v1.
+
 ## 1. Layout
 
 ```

gravity_cli-0.10.0/AGENT_STANDARD_V2.md

@@ -0,0 +1,425 @@
+# Agent submission standard — `contract: v2`
+
+What a valid agent directory looks like, exactly what ships, and which check
+catches which mistake. Follow this and `gravity build` passes, the deploy
+succeeds, and the runtime loads it. Deviate and the failure happens at a stage
+you can't see — after upload, on our infrastructure.
+
+Start from `gravity init <name> --contract v2`; every v2 template already conforms
+(`minimal`, `structured`, `deepagent`, `chat`).
+
+The manifest rules below are enforced by `packages/gravity-schema`, the one
+model shared by the CLI, the runner and the server. Where this document and
+that package disagree, the package wins and this document has a bug.
+
+**v2 names capabilities, never apps or tools.** An agent says what it reads
+(`issue.list`) and what it changes (`issue.create`); the consumer picks the
+app — Linear, Jira, Asana — when they set it up. `contract: v1` manifests
+(tool names) are still accepted while the platform moves to v2; their standard is
+AGENT_STANDARD.md. **v2 is a preview:** it runs only against a gateway that serves v2.
+
+## 1. Layout
+
+```
+my-agent/
+├── manifest.yaml        required   the contract (§2)
+├── requirements.txt     required   your direct deps — may be empty, must exist
+├── requirements.lock    generated  by `gravity validate`/`build`, for the TARGET platform (§5)
+├── src/                 required   all your code; the entrypoint lives here
+│   └── agent.py                    `graph` is defined here (§3)
+└── tests/               optional   shipped if present
+```
+
+**Only these are bundled.** `gravity build` zips exactly `manifest.yaml`,
+`requirements.txt`, `requirements.lock`, and the contents of `src/` and
+`tests/` (minus dotfiles, `__pycache__` and bytecode). Anything else — `.venv/`, `build/`, notebooks,
+a `data/` folder — is not shipped, and code that reads it will fail at runtime.
+
+## 2. `manifest.yaml`
+
+```yaml
+contract: v2                      # capabilities; the only contract accepted
+name: my-agent                    # lowercase slug, ≤64 chars — appears in URLs
+version: 1.0.0                    # strict semver; bump to republish — a version can't be overwritten
+description: One line.            # ≤500 chars
+
+runtime:
+  framework: langgraph            # only value accepted
+  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
+
+dependencies:
+  lockfile: requirements.lock     # leave as-is
+
+inputs:                           # becomes the consumer's form; arrives as state["inputs"]
+  - name: query                   # the key in state["inputs"]
+    type: text                    # text | textarea | number | boolean | static-dropdown | email | url | date | secret | file
+    label: "What should I do?"    # what the consumer sees
+    required: true
+    # options: [a, b]             # static-dropdown only
+    # accept: [pdf, csv]          # file only — extensions without the dot
+    # default: ...                # never on a file input
+
+models:
+  tier: standard                  # standard | premium
+
+sources:                          # what the agent reads; the key is the name your code uses (§4)
+  tasks:
+    capability: issue.list        # <shape>.<verb>, a read: list | search | get (`gravity capabilities`)
+    default_app: linear           # the app it is built for (expected): setup starts with it, the consumer sees it before
+                                  # connecting anything, and chat prefers it; the consumer may change it
+    label: "Where your issues live"   # the question the consumer answers at setup
+    window: 7d                    # optional: 24h, 7d, 4w or since_last_run; the consumer may change it
+    filters: {state: open}        # optional: the shape's standard filters; the consumer may change them
+    # required: false             # the agent runs without it if the consumer picks nothing
+    # apps: [linear, jira]        # optional: limit the consumer's choice
+
+writes:                           # what the agent changes while it runs, as often as it decides
+  follow_up:
+    capability: issue.create
+    label: "Where follow-ups go"
+
+resources:
+  memory_mb: 512                  # 128–4096; a request the platform clamps
+
+triggers:                         # optional — what starts a run
+  manual: true                    # default
+  # schedule:
+  #   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 — writes that pause for the consumer's yes
+  required_for: [issue.create]    # each call of these capabilities waits; a delete (any *.delete)
+                                  # is off by default and must be listed here. Delivering an
+                                  # output isn't held: the consumer's pick is the consent
+
+# built_ins: [supadata.get_transcript]   # optional — tools built into the gateway (no app to connect);
+#                                 # they join the run's grant. List them: gravity capabilities built_ins
+
+# state:                          # optional — memory across runs, per consumer
+#   max_kb: 256                   # 1–256; leave out and the agent gets none
+```
+
+**`approvals` is enforced by the gateway.** A listed capability's call is held until a
+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
+holds the call, not the agent. Hosted, with tools from `gravity.tools()`, the
+run pauses durably instead of holding the call (§8).
+
+`triggers` and `state` are part of the contract so a published agent never
+has to change to use them. `gravity schedule` fires `triggers.schedule` locally, and an agent
+that declares `state` gets `state["memory"]` from its last finished run (saved only when a run
+finishes, never over `max_kb`); hosted, EventBridge fires the schedule and the gateway keeps the memory. An agent
+that nothing can start (`manual: false` with no schedule) is rejected.
+
+There are no per-app adapters: an agent declares the write once and the consumer picks the app.
+Each run gets exactly the consumer's picks as its grant — the capabilities on the apps they chose,
+nothing else.
+
+The same schema is validated twice — by `gravity validate` on your machine
+and again by the server on push — because an attacker won't use the CLI.
+
+## 3. The entrypoint
+
+`runtime.entrypoint` names a file under `src/` and a module-level object in
+it. The runtime accepts two forms:
+
+```python
+async def graph():                # ✓ recommended — an async factory
+    ...
+    return workflow.compile()
+
+graph = asyncio.run(_build())     # ✗ gravity validate refuses asyncio.run at import
+graph = _build()                  # ✓ also fine — a coroutine is awaited
+```
+
+**Prefer the factory**, which is what the templates do. The runner calls it
+fresh for every run, on that run's own event loop, after the run's env vars
+are set. Read the env vars *inside* it: helper modules under `src/` are
+imported once and cached, so an env var read at their top level can outlive
+the run it belonged to.
+
+A graph compiled at import without `asyncio.run` (`graph = workflow.compile()`)
+also works. `gravity validate` refuses `asyncio.run` and `os.environ` / `os.getenv`
+at module level under `src/`, a plain `def graph()`, and a `graph` that is a bare
+value: each of those passed a build and failed when the platform loaded it.
+
+**State.** The runtime invokes `graph.astream({"inputs": {...}}, stream_mode="updates")`
+— the keyword is passed only when your `astream` accepts it, so a hand-rolled
+object with a plain `astream(state)` works too (accepting `**kwargs` is the
+safe habit). The dict is the
+dict is the consumer's form answers keyed by `inputs[].name`. Your state
+therefore needs:
+
+```python
+class State(TypedDict):
+    inputs: dict                  # required — the consumer's form answers
+    result: Any                   # required in the FINAL state — what the consumer gets
+    ...                           # anything else is yours
+```
+
+**Result.** When the graph finishes, `state["result"]` is what the platform
+returns to the consumer. Any JSON-serialisable value — a string, a dict. A
+graph that finishes without setting `result` returns nothing.
+
+**Conversation.** Declaring a `messages` key in your state opts the agent
+into conversation: the platform passes the transcript in on every turn and
+stores what comes back. Don't declare it in a one-shot agent — see the
+`chat` template.
+
+Optional convention the platform surfaces if present: `source: "live" | "stub"`
+— whether real tool calls happened or a mock answered.
+
+## 4. Imports, tools, models
+
+**Imports: absolute, rooted at `src/`.** The runtime puts `src/` on
+`sys.path` and loads your entrypoint as a top-level module. So:
+
+```python
+from tools.scoring import score   # ✓  src/tools/scoring.py
+from nodes.agent import build     # ✓  src/nodes/agent.py
+from .nodes.agent import build    # ✗  relative imports don't resolve
+from src.nodes.agent import build # ✗  src/ is the root, not a package
+```
+
+`gravity run` loads the same way, so a local run is a faithful preview.
+
+**Sources and writes** come only through the gateway, by the names the
+manifest gives them. From code, with no model in between:
+
+```python
+tasks = await gravity.read("tasks", filters={"labels": ["bug"]})   # {"records": [...], "complete": ...}
+done = await gravity.act("follow_up", draft={"title": "Fix login"}) # the write's receipt: id, link, read-back
+```
+
+Records come back in the shape's fields (`gravity capabilities issue.list`
+says which), whichever app the consumer picked; the consumer's filters and
+window always apply. To let a model choose, `await gravity.tools()` gives one
+LangChain tool per source and write (`sources_tasks`, `writes_follow_up`),
+or use your own MCP client against `GRAVITY_GATEWAY_URL` with the run token.
+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 source or write:
+that is where the user's connected app is, and a direct call would have no
+credentials. Declare what you need; don't reach around it.
+
+**Models** go through the LLM gateway with the same token:
+
+```python
+model = ChatOpenAI(model="openai/gpt-6-luna",
+                   base_url=os.environ["GRAVITY_LLM_URL"],
+                   api_key=os.environ["GRAVITY_RUN_TOKEN"])
+```
+
+**Embeddings** use the same URL and token (`<GRAVITY_LLM_URL>/embeddings`), metered
+and budgeted like chat calls:
+
+```python
+emb = OpenAIEmbeddings(model="voyageai/voyage-4-lite",   # or google/gemini-embedding-2
+                       base_url=os.environ["GRAVITY_LLM_URL"],
+                       api_key=os.environ["GRAVITY_RUN_TOKEN"],
+                       check_embedding_ctx_length=False)  # send text, not OpenAI token ids
+vectors = await emb.aembed_documents(["first text", "second text"])
+```
+
+**Images** come from an image model through the same URL and token: nothing 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
+production, models go through the gateway.
+
+## 5. Dependencies
+
+List direct deps in `requirements.txt` with version ranges. `gravity validate`
+compiles `requirements.lock` **for the target** — `aarch64-manylinux2014`,
+Python `runtime.python`, binary wheels only — not for your laptop. The deploy
+installs from the lock and nothing else.
+
+Don't hand-edit the lock. Don't compile it yourself; a native compile on
+Windows or macOS pins the wrong wheels and only fails at deploy.
+
+## 6. Local runs
+
+`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`. `gravity login`
+gives you a gateway token; each run trades it for a run token bound to your
+picks, so anything undeclared 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.
+
+You are the consumer locally: each source and write runs on its `default_app`
+unless you pick another with `--use name=app[:resource=id,...]`
+(`--use tasks=linear --use follow_up=jira:project=APP`) or a `--setup` file. The
+picks are checked exactly as a consumer's setup is, and the apps must be
+connected for the account your token acts as (`gravity connect`, or on the shared
+test account, Gravity). Outputs are printed, not delivered: delivery is the
+platform's. `gravity check <capability> --app <app>` tries one capability on your
+account first, and says whose side a failure is on.
+
+`gravity dev` opens a local dashboard over the same runs: a form from your
+manifest, a picker for each source's and write's app, 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
+
+| Stage | Catches |
+|---|---|
+| `gravity validate` / `build` (local) | manifest schema · every capability exists, sources are reads, destinations take the output's rendering · filters are the shape's · blocked capabilities refused, deletes approved · `python: "3.12"` · schedules every 5 minutes at the fastest, one day field · entrypoint file + object exist, `graph` an async factory or a compiled graph (static) · no `os.environ` or `asyncio.run` at import, no relative imports · `requirements.txt` present · lockfile compiles for aarch64 · code reading or acting on a name the manifest doesn't declare (`gravity.read("x")`) · `build` refuses without the lockfile |
+| `gravity push` (server) | manifest re-validated with the same rules · version not already published |
+| setup (consumer) | each pick, and each extra app in its `also` list: the app serves the capability, the target it needs is picked (a channel; a table inside its base), recipients for an email are plain addresses |
+| deploy | every pin in the lock installs on ARM64 |
+| first run | module imports · `graph` resolves to something with `astream()` · state has `inputs` · final state has `result` |
+
+The further right a failure lands, the longer you wait to see it. `build`
+passing means everything in the first column is fine; it does not run your
+code. `gravity run` does.
+
+## 8. On the platform: `import gravity`
+
+Hosted runs are durable: they pause for approvals, survive a lost session,
+and remember the thread between runs. The platform does that around your
+graph. `gravity` is preinstalled in the image; don't put it in
+`requirements.txt`.
+
+**Tools: `await gravity.tools()`** instead of your own `MultiServerMCPClient`.
+One LangChain tool per source and write (`sources_tasks`, `writes_follow_up`),
+from the same env vars. Off the platform (`gravity run`, `gravity dev`, 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 <platform repo>/packages/gravity-sdk`)
+or `gravity run` fails with `No module named 'gravity'`.
+On the platform, each write whose capability is 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
+saw. Declined, it returns
+`APPROVAL_REJECTED: '<tool>' was not approved, so it did not run`, the same
+text as today, so keep your fallback.
+
+```python
+tools = {t.name: t for t in await gravity.tools()}
+await tools["writes_follow_up"].ainvoke({"draft": {"title": "Fix login"}})
+```
+
+When the run resumes, the node that made the call **runs again from its
+start**: everything before the call happens twice.
+
+- Put a gated call at the end of its own node, after nothing expensive or side-effecting.
+- Several gated calls in one node work, each approved in turn. On each resume the
+  earlier calls are repeated, and the gateway answers a repeat with the stored result
+  instead of doing it again, so each side effect still happens once. Work *between*
+  the calls repeats too, so keep it cheap.
+- Two approvals at once: make them parallel nodes. The consumer sees both together.
+- Any `interrupt()` of your own fails the run with `UNSUPPORTED_INTERRUPT` (for now).
+
+**Persistence is the platform's.** Compile with no checkpointer and no store
+(`workflow.compile()`); the platform injects its own, and one you pass is
+replaced. State is kept per thread. A key the next run doesn't send keeps its
+value (a monitor's `seen`, a draft). For memory shared by one consumer's
+threads, use `langgraph.config.get_store()` (`aget` / `aput` / `asearch` by
+namespace and filter; no semantic search). It is kept per consumer and agent,
+across runs and versions, until the agent deletes an item (`aput(ns, key, None)`);
+store one item per record, not one large blob. `gravity run` gives you the same
+store locally, saved in `.gravity/store.json` (delete it to start over).
+
+**Conversation.** `messages` must use the `add_messages` reducer:
+`messages: Annotated[list, add_messages]`. Each turn the platform sends only
+the new user turn. The history comes from the thread's checkpoint, and a
+plain `list` would replace it with that one message.
+
+**`kind` and `outputs`.**
+
+```yaml
+kind: transform            # transform | interactive (default) | monitor
+outputs:                   # what the consumer may ask the result to become
+  deck:    {renderer: pptx, label: "Pitch deck", default: {destination: download}}
+  readout: {renderer: docx, label: "Read-out document", default: {destination: download}}
+  summary: {renderer: markdown, label: "Summary", destinations: [download, message.send, document.create],
+            default: {destination: message.send, app: gmail}}
+```
+
+- `transform`: all input at the start, the result at the end. The platform
+  delivers it, so the agent needs no write tools.
+- `interactive`: calls tools mid-flow and may converse over several turns.
+- `monitor`: runs on a schedule or a webhook, on one thread, remembering the
+  last run. It needs `triggers.schedule` or a webhook.
+
+`destinations` is where an output may go: `download` (the default), or a
+capability that takes its rendering — markdown: `message.send`,
+`message.create`, `document.create`, `issue.create`, `comment.create`,
+`post.create`, `file.create`; docx and pptx: `file.create`, `message.send`
+(and `presentation.create` for a deck); rows: `row.append`, `file.create`.
+`default` (expected; `gravity validate` warns without it) is where it goes
+unless the consumer picks otherwise: a download, or a destination and its
+app. The consumer can change it, and picks the place (a Slack channel, a
+Notion page, recipients for an email) at setup, or asks for it in chat. The
+consumer may also send it to more places (`also`: an email and a Notion page),
+and read several apps into one source; the agent sees one merged list, each
+record tagged with its app in `extra.app`. The platform delivers it after the
+run, not the agent, so the agent declares no write for it; an email goes at
+most once per run and a thread sends at most 200 a day, extra places included.
+
+Renderers: `markdown`, `docx`, `pptx`, `rows` (the first table, as CSV). Each
+consumer picks outputs and destinations per run. The agent writes one
+**corpus** into its final state, and every output is rendered from it:
+
+```python
+corpus = gravity.Corpus(
+    title="Acme: seed round", subtitle="2026", summary="**Why now**: ...",
+    sections=[gravity.Section(
+        heading="Market", body="markdown", bullets=["..."],
+        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")],
+)
+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. 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
+
+- [ ] `manifest.yaml` with `contract: v2`: what the agent reads under `sources`, what it changes under `writes` (capabilities, never apps)
+- [ ] `requirements.txt` exists (empty is fine)
+- [ ] `src/agent.py` defines module-level `graph`: an `async def` factory (recommended) or a compiled graph
+- [ ] env vars read inside `graph()`, not at module level; no `asyncio.run` at import; `python: "3.12"`
+- [ ] state has `inputs`; final state sets `result`; `messages` only if the agent is conversational, with `add_messages`
+- [ ] sources and writes through `gravity.read` / `gravity.act` (or `gravity.tools()`); compiled with no checkpointer; nothing expensive before a gated call (§8)
+- [ ] all imports under `src/` are absolute from `src/`
+- [ ] nothing acts on a user's account except through a source or write; models via the LLM URL
+- [ ] nothing your code needs lives outside `src/` or `tests/`
+- [ ] `gravity check --manifest .` and `gravity build` pass; `gravity run` (or `gravity dev`) produces a `result`

gravity_cli-0.8.0/README.md → gravity_cli-0.10.0/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.5
+Name: gravity-cli
+Version: 0.10.0
+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.10.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uv>=0.8.0
+Description-Content-Type: text/markdown
+
 <h1 align="center">Gravity CLI</h1>
 
 <p align="center">
@@ -194,7 +211,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | | [`gravity connect`](#gravity-connect) | Connect an account your agents act on (Gmail, Slack...) |
 | **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 CLI** | [`gravity docs`](#gravity-docs) | Write `Gravity.agent.md` for the coding agent in this folder |
+| **Gravity CLI** | [`gravity docs`](#gravity-docs) | Write the Gravity guides for you and your coding agent in this folder |
 | | [`gravity update`](#gravity-update) | Update to the latest release and see what is new |
 | | [`gravity changelog`](#gravity-changelog) | What changed in each release |
 
@@ -490,7 +507,7 @@ gravity guide | less
 
 ### `gravity docs`
 
-Write or refresh the two files a coding agent needs to build for Gravity in this folder: `Gravity.agent.md` (how Gravity runs agents, the manifest, every tool this release knows, the output formats, the rules that fail a load) and `problem-to-agent.md` (the method for turning a problem statement into an agent that holds up).
+Write or refresh the three files that help you and your coding agent build for Gravity in this folder: `Gravity.agent.md` (how Gravity runs agents, the manifest, every tool this release knows, the output formats, the rules that fail a load) `problem-to-agent.md` (the method for turning a problem statement into an agent that holds up, with the bar an agent must meet), and `Gravity.getting-started.md` (a plain-language overview of Gravity, agents and the CLI for someone new).
 
 ```
 gravity docs [--force]
@@ -500,7 +517,7 @@ gravity docs [--force]
 |---|---|
 | `--force` | Replace the files even where you edited them, or where a file Gravity did not write has the same name |
 
-You rarely need this. Every command writes the two files into the folder it runs in if they are missing (never into your home folder or a drive root; `gravity init` writes them into the new agent), and rewrites them when a newer release changes them. The first line of a file Gravity wrote names the release and a hash of the text after it: if you edit the file the hash no longer matches and Gravity leaves it alone. Your own `agent.md`, `AGENTS.md` and `CLAUDE.md` are never touched. Point your coding agent at `Gravity.agent.md` from them if it does not look there by itself. Set `GRAVITY_AGENT_DOCS=0` to stop the automatic writes.
+You rarely need this. Every command writes the three files into the folder it runs in if they are missing (never into your home folder or a drive root; `gravity init` writes them into the new agent), and rewrites them when a newer release changes them. The first line of a file Gravity wrote names the release and a hash of the text after it: if you edit the file the hash no longer matches and Gravity leaves it alone. Your own `agent.md`, `AGENTS.md` and `CLAUDE.md` are never touched. Point your coding agent at `Gravity.agent.md` from them if it does not look there by itself. Set `GRAVITY_AGENT_DOCS=0` to stop the automatic writes.
 
 ### `gravity update`
 
@@ -584,7 +601,7 @@ Set `GRAVITY_API_URL` and `GRAVITY_GATEWAY_URL` only to work against services yo
 | `GRAVITY_API_TOKEN` | A control-plane dev token, used instead of `gravity login`. For development only. | none |
 | `GRAVITY_CONFIG_DIR` | Moves `~/.gravity` elsewhere. Useful for tests and CI. | `~/.gravity` |
 | `GRAVITY_AUTO_UPDATE` | When `0`, commands neither check for a newer release nor install one. Always off when `CI` is set. | `1` |
-| `GRAVITY_AGENT_DOCS` | When `0`, commands do not write `Gravity.agent.md` and `problem-to-agent.md` into the folder they run in. `gravity docs` still does. | `1` |
+| `GRAVITY_AGENT_DOCS` | When `0`, commands do not write `Gravity.agent.md`, `problem-to-agent.md` and `Gravity.getting-started.md` into the folder they run in. `gravity docs` still does. | `1` |
 | `GRAVITY_UPDATE_URL` | Where the latest version is read from, a JSON document with `info.version`. For tests and mirrors. | PyPI |
 | `GRAVITY_UNATTENDED` | When `1`, calls that need approval are rejected without asking. `gravity schedule` sets it for you. | unset |
 
@@ -739,6 +756,21 @@ outputs:                          # extra formats the platform renders and deliv
 
 Unknown fields are rejected rather than ignored, so a typo is reported instead of silently dropped.
 
+### Contract v2 (preview)
+
+The CLI also reads `contract: v2` manifests, where an agent names **capabilities** (`message.list`, `issue.create`)
+instead of tools, and the person picks the app when they set it up: Gmail or Outlook, Linear or Jira. What it reads
+goes under `sources`, what it changes under `writes`; code calls `gravity.read("inbox")` and `gravity.act("send", ...)`.
+v2 runs only against a gateway that serves it, and Gravity's hosted gateway runs v1 for now.
+
+```bash
+gravity init my-agent --contract v2      # the v2 templates
+gravity capabilities message             # what exists, and which apps serve it
+gravity check message.list --app gmail   # try one on your own account (v2 gateway)
+gravity run --use inbox=outlook          # pick the app for a local run
+gravity guide --contract v2              # the v2 guide; the rules are in AGENT_STANDARD_V2.md
+```
+
 ## An agent project
 
 ```
@@ -907,6 +939,7 @@ uv run python -m gravity_schema.gen_catalog --root <platform repo>/code-first
 | [Builder guide](src/gravity_cli/BUILDER_GUIDE.md) | How to build a good agent, start to finish, with a complete example. Also `gravity guide` |
 | [`Gravity.agent.md`](src/gravity_cli/docs/Gravity.agent.md) | The guide `gravity docs` writes for coding agents; its tool list is filled in from the catalog of the release that writes it |
 | [`problem-to-agent.md`](src/gravity_cli/docs/problem-to-agent.md) | The method for turning a problem statement into an agent that holds up |
+| [`Gravity.getting-started.md`](src/gravity_cli/docs/Gravity.getting-started.md) | A plain-language overview of Gravity, agents and the CLI, for someone new |
 | [Agent standard](AGENT_STANDARD.md) | The exact rules an agent must follow |
 | [Templates](TEMPLATES.md) | The four templates and when to pick each |
 | [`manifest.schema.json`](packages/gravity-schema/schema/manifest.schema.json) | The manifest as a machine-readable JSON Schema |