gravity-cli 0.4.4__tar.gz → 0.5.0__tar.gz

gravity_cli-0.4.4/README.md → gravity_cli-0.5.0/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.5
+Name: gravity-cli
+Version: 0.5.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.5.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">
@@ -161,8 +178,8 @@ gravity push
 
 | Service | What it does | Used by |
 |---|---|---|
-| **Gateway** | Serves tools over MCP (`/mcp`) and models over an OpenAI-compatible API (`/v1`). Issues run tokens and refuses any tool a run was not granted. | `run`, `schedule`, `adapt`, and your agent |
-| **Control plane** | Accounts, the tool catalog, pushed agents, builds and hosted runs. | `login`, `logout`, `whoami`, `push`, `tools`, `agents`, `runs`, `logs` |
+| **Gateway** | Serves tools over MCP (`/mcp`) and models over an OpenAI-compatible API (`/v1`). Lists its tools at `/tools` and your connected accounts at `/connections`. Issues run tokens and refuses any tool a run was not granted. | `run`, `schedule`, `adapt`, `tools`, `connect`, and your agent |
+| **Control plane** | Accounts, pushed agents, builds and hosted runs. | `login`, `logout`, `whoami`, `push`, `agents`, `runs`, `logs` |
 
 On `gravity run`, the CLI trades your dev token for a run token scoped to the manifest's tools and starts the agent with only that token. Your own tokens are removed from the agent's environment, so agent code can never act as you.
 
@@ -190,6 +207,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | **Account** | [`gravity login`](#gravity-login) | Sign in to Gravity in your browser |
 | | [`gravity logout`](#gravity-logout) | Sign out |
 | | [`gravity whoami`](#gravity-whoami) | Show who you are signed in as |
+| | [`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 |
 
@@ -238,7 +256,10 @@ What it checks:
 - the entrypoint file exists and defines the object the manifest names
 - `requirements.txt` exists, and compiles into `requirements.lock` for the platform image (ARM64 Linux) and the manifest's Python version
 - every adapter a slot declares has a file, and every adapter file is declared
-- warnings, never failures, for tool names or network libraries in your code that the manifest does not declare
+- every tool in the manifest exists in the catalog, the same list the platform's build uses, so a typo fails here instead of after a push
+- 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
 
 ```bash
 gravity validate
@@ -376,7 +397,9 @@ gravity logs <run_id>
 
 ### `gravity tools`
 
-Browse the tool catalog: the names you can put under `permissions.tools`, with a description and the access each one needs.
+Browse the tool catalog: the names you can put under `permissions.tools`, with what each one does. It is the gateway's own list, so it shows exactly what a run can call, and it needs no sign-in.
+
+About 25 tools are curated, such as `gmail.read` and `web.search`. The other ~1,100 are imported from the same apps and unreviewed: any imported tool that changes something must also be under `approvals.required_for`, and `gravity validate` checks that.
 
 ```
 gravity tools [search]
@@ -412,6 +435,23 @@ gravity whoami
 gravity whoami --token    # print the gateway token itself, for CI or a teammate's .env
 ```
 
+### `gravity connect`
+
+Connect an account your agents' tools act on, through the app's own sign-in page in your browser. With no app, list what is connected.
+
+```
+gravity connect [app]
+```
+
+```bash
+gravity connect           # what is connected, and whose accounts runs act on
+gravity connect gmail     # opens the sign-in page, then waits until it is done
+gravity connect sheets    # use the app name from tool names: sheets, calendar, drive, linear, slack, github...
+```
+
+- Uses the gateway token from `gravity login`.
+- `web` tools need no account.
+
 ### `gravity guide`
 
 Read the builder guide, which ships with the CLI: how an agent is put together, the rules your code must follow, formatting results, approvals, adapters, scheduling, memory, and a checklist.
@@ -472,7 +512,8 @@ Never commit a `.env` file. The `.gitignore` in every template keeps `.env` and
 |---|---|---|---|
 | Create, check and package an agent | `init`, `validate`, `build` | nothing | nothing |
 | Run an agent locally | `run`, `schedule`, `adapt` | `gravity login` (or `GRAVITY_DEV_TOKEN`) | nothing |
-| Publish and inspect agents | `push`, `tools`, `agents`, `runs`, `logs`, `whoami` | `gravity login` | nothing |
+| Publish and inspect agents | `push`, `agents`, `runs`, `logs`, `whoami` | `gravity login` | nothing |
+| Browse tools, connect accounts | `tools`, `connect` | nothing for `tools`; `gravity login` for `connect` | nothing |
 
 Set `GRAVITY_API_URL` and `GRAVITY_GATEWAY_URL` only to work against services you run yourself; see [Running a local gateway](#running-a-local-gateway).
 
@@ -714,6 +755,7 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
+- **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`.
 - **0.4.3** Documents the `secret` input type and the `supadata.get_transcript` tool.
 - **0.4.1** New input type `secret` for an API key, password or other confidential value. New built-in tool `supadata.get_transcript` (`gravity tools supadata`).

gravity_cli-0.4.4/PKG-INFO → gravity_cli-0.5.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.5
-Name: gravity-cli
-Version: 0.4.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.4.4
-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">
@@ -178,8 +161,8 @@ gravity push
 
 | Service | What it does | Used by |
 |---|---|---|
-| **Gateway** | Serves tools over MCP (`/mcp`) and models over an OpenAI-compatible API (`/v1`). Issues run tokens and refuses any tool a run was not granted. | `run`, `schedule`, `adapt`, and your agent |
-| **Control plane** | Accounts, the tool catalog, pushed agents, builds and hosted runs. | `login`, `logout`, `whoami`, `push`, `tools`, `agents`, `runs`, `logs` |
+| **Gateway** | Serves tools over MCP (`/mcp`) and models over an OpenAI-compatible API (`/v1`). Lists its tools at `/tools` and your connected accounts at `/connections`. Issues run tokens and refuses any tool a run was not granted. | `run`, `schedule`, `adapt`, `tools`, `connect`, and your agent |
+| **Control plane** | Accounts, pushed agents, builds and hosted runs. | `login`, `logout`, `whoami`, `push`, `agents`, `runs`, `logs` |
 
 On `gravity run`, the CLI trades your dev token for a run token scoped to the manifest's tools and starts the agent with only that token. Your own tokens are removed from the agent's environment, so agent code can never act as you.
 
@@ -207,6 +190,7 @@ Run `gravity help` for this list in the terminal, and add `-h` to any command fo
 | **Account** | [`gravity login`](#gravity-login) | Sign in to Gravity in your browser |
 | | [`gravity logout`](#gravity-logout) | Sign out |
 | | [`gravity whoami`](#gravity-whoami) | Show who you are signed in as |
+| | [`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 |
 
@@ -255,7 +239,10 @@ What it checks:
 - the entrypoint file exists and defines the object the manifest names
 - `requirements.txt` exists, and compiles into `requirements.lock` for the platform image (ARM64 Linux) and the manifest's Python version
 - every adapter a slot declares has a file, and every adapter file is declared
-- warnings, never failures, for tool names or network libraries in your code that the manifest does not declare
+- every tool in the manifest exists in the catalog, the same list the platform's build uses, so a typo fails here instead of after a push
+- 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
 
 ```bash
 gravity validate
@@ -393,7 +380,9 @@ gravity logs <run_id>
 
 ### `gravity tools`
 
-Browse the tool catalog: the names you can put under `permissions.tools`, with a description and the access each one needs.
+Browse the tool catalog: the names you can put under `permissions.tools`, with what each one does. It is the gateway's own list, so it shows exactly what a run can call, and it needs no sign-in.
+
+About 25 tools are curated, such as `gmail.read` and `web.search`. The other ~1,100 are imported from the same apps and unreviewed: any imported tool that changes something must also be under `approvals.required_for`, and `gravity validate` checks that.
 
 ```
 gravity tools [search]
@@ -429,6 +418,23 @@ gravity whoami
 gravity whoami --token    # print the gateway token itself, for CI or a teammate's .env
 ```
 
+### `gravity connect`
+
+Connect an account your agents' tools act on, through the app's own sign-in page in your browser. With no app, list what is connected.
+
+```
+gravity connect [app]
+```
+
+```bash
+gravity connect           # what is connected, and whose accounts runs act on
+gravity connect gmail     # opens the sign-in page, then waits until it is done
+gravity connect sheets    # use the app name from tool names: sheets, calendar, drive, linear, slack, github...
+```
+
+- Uses the gateway token from `gravity login`.
+- `web` tools need no account.
+
 ### `gravity guide`
 
 Read the builder guide, which ships with the CLI: how an agent is put together, the rules your code must follow, formatting results, approvals, adapters, scheduling, memory, and a checklist.
@@ -489,7 +495,8 @@ Never commit a `.env` file. The `.gitignore` in every template keeps `.env` and
 |---|---|---|---|
 | Create, check and package an agent | `init`, `validate`, `build` | nothing | nothing |
 | Run an agent locally | `run`, `schedule`, `adapt` | `gravity login` (or `GRAVITY_DEV_TOKEN`) | nothing |
-| Publish and inspect agents | `push`, `tools`, `agents`, `runs`, `logs`, `whoami` | `gravity login` | nothing |
+| Publish and inspect agents | `push`, `agents`, `runs`, `logs`, `whoami` | `gravity login` | nothing |
+| Browse tools, connect accounts | `tools`, `connect` | nothing for `tools`; `gravity login` for `connect` | nothing |
 
 Set `GRAVITY_API_URL` and `GRAVITY_GATEWAY_URL` only to work against services you run yourself; see [Running a local gateway](#running-a-local-gateway).
 
@@ -731,6 +738,7 @@ Real tools act on a connected account. Connect one with `gravity-gateway connect
 
 ## What's new
 
+- **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`.
 - **0.4.3** Documents the `secret` input type and the `supadata.get_transcript` tool.
 - **0.4.1** New input type `secret` for an API key, password or other confidential value. New built-in tool `supadata.get_transcript` (`gravity tools supadata`).

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/packages/gravity-schema/gravity_schema/__init__.py

@@ -36,7 +36,9 @@ from .manifest import (
     StateSpec,
     TriggersSpec,
 )
+from .source_scan import is_agent_source, undeclared_write_tools
 from .validation import (
+    check_imported_write_approvals,
     check_tool_references,
     load_manifest_file,
     load_manifest_text,
@@ -73,6 +75,10 @@ __all__ = [  # noqa: RUF022 - grouped by concern, not alphabetical
     "load_manifest_text",
     "load_manifest_file",
     "check_tool_references",
+    "check_imported_write_approvals",
+    # source scan
+    "is_agent_source",
+    "undeclared_write_tools",
     # catalog
     "ToolCatalog",
     "StaticToolCatalog",

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/packages/gravity-schema/gravity_schema/catalog.yaml

@@ -27,6 +27,22 @@
   guarantee: certified
   side_effect: read
 
+- name: web.search
+  slug: COMPOSIO_SEARCH_WEB
+  description: search the web; returns results with titles, links and snippets. No account needed
+  scopes: []
+  breadth: generic
+  guarantee: certified
+  side_effect: read
+
+- name: web.fetch
+  slug: COMPOSIO_SEARCH_FETCH_URL_CONTENT
+  description: read the text content of a web page by its URL. No account needed
+  scopes: []
+  breadth: generic
+  guarantee: certified
+  side_effect: read
+
 - name: supadata.get_transcript
   slug: null
   description: fetch the transcript of a YouTube video with the caller's own Supadata API key (api_key argument)

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/packages/gravity-schema/gravity_schema/errors.py

@@ -27,6 +27,8 @@ class ErrorCode(str, Enum):
     INVALID_TOOL_NAME = "INVALID_TOOL_NAME"
     DUPLICATE_TOOL = "DUPLICATE_TOOL"
     TOOL_NOT_FOUND = "TOOL_NOT_FOUND"
+    UNDECLARED_TOOL_CALL = "UNDECLARED_TOOL_CALL"
+    APPROVAL_REQUIRED = "APPROVAL_REQUIRED"
     INVALID_MODEL_TIER = "INVALID_MODEL_TIER"
     INVALID_RESOURCES = "INVALID_RESOURCES"
     INVALID_TRIGGER = "INVALID_TRIGGER"

gravity_cli-0.5.0/packages/gravity-schema/gravity_schema/source_scan.py

@@ -0,0 +1,83 @@
+"""Agent code that calls a write tool its manifest does not grant.
+
+The gateway refuses such a call at run time (TOOL_NOT_DECLARED). This finds it
+before the build, from the source text alone: nothing is imported or run.
+`gravity validate` and the platform's build step share it, so a builder who
+skips the CLI is still stopped.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable, Iterator
+from pathlib import PurePath
+
+from .catalog import CATALOG, ToolEntry
+from .errors import ErrorCode, ManifestIssue, Severity
+from .manifest import Manifest
+
+# Not shipped as agent behaviour: tests may name any tool to assert it is refused.
+SKIPPED_DIRS = frozenset({".venv", "venv", "tests", "__pycache__", ".gravity"})
+
+# Manifests say 'gmail.send'; code says 'gmail_send' (some models reject dots in
+# function names). Either spelling is the same tool.
+_BY_SPELLING: dict[str, ToolEntry] = {
+    spelling: e for e in CATALOG for spelling in (e.name, e.name.replace(".", "_"))
+}
+
+
+def is_agent_source(path: PurePath) -> bool:
+    return path.suffix == ".py" and not SKIPPED_DIRS & set(path.parts)
+
+
+def _docstrings(tree: ast.Module) -> set[int]:
+    owners = [tree, *(n for n in ast.walk(tree) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)))]
+    return {
+        id(owner.body[0].value)
+        for owner in owners
+        if owner.body
+        and isinstance(owner.body[0], ast.Expr)
+        and isinstance(owner.body[0].value, ast.Constant)
+        and isinstance(owner.body[0].value.value, str)
+    }
+
+
+def _string_literals(tree: ast.Module) -> Iterator[str]:
+    """Every string constant except docstrings, which describe rather than call."""
+    skip = _docstrings(tree)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Constant) and isinstance(node.value, str) and id(node) not in skip:
+            yield node.value
+
+
+def undeclared_write_tools(sources: Iterable[tuple[str, str]], manifest: Manifest) -> list[ManifestIssue]:
+    """One issue per catalog write tool named in `sources` ((path, text) pairs)
+    that no part of the manifest grants. Reads stay the drift scan's warning."""
+    declared = manifest.declared_tools
+    first_seen: dict[str, str] = {}
+    for path, text in sources:
+        try:
+            tree = ast.parse(text, filename=path)
+        except SyntaxError:
+            continue  # the entrypoint check reports a broken entrypoint; this scan has nothing to read
+        for literal in _string_literals(tree):
+            entry = _BY_SPELLING.get(literal)
+            if entry and entry.side_effect == "write" and entry.name not in declared:
+                first_seen.setdefault(entry.name, path)
+
+    return [
+        ManifestIssue(
+            code=ErrorCode.UNDECLARED_TOOL_CALL,
+            location=path,
+            message=f"{path} calls '{tool}', a write tool the manifest does not grant.",
+            remediation=(
+                f"Declare '{tool}' under permissions.tools (and approvals.required_for, so a person "
+                "says yes before it acts), or remove the call. If it only delivers the finished "
+                "result, list it under an output's destinations instead: the platform sends it "
+                "from the user's own connected account after the run."
+            ),
+            value=tool,
+            severity=Severity.HIGH,
+        )
+        for tool, path in sorted(first_seen.items())
+    ]

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/packages/gravity-schema/gravity_schema/validation.py

@@ -9,7 +9,7 @@ import yaml
 from pydantic import ValidationError
 
 from . import contract as C
-from .catalog import ToolCatalog
+from .catalog import CATALOG, ToolCatalog
 from .errors import (
     ErrorCode,
     ManifestIssue,
@@ -56,7 +56,28 @@ def check_tool_references(manifest: Manifest, catalog: ToolCatalog) -> list[Mani
             )
         )
 
-    return issues
+    return issues + check_imported_write_approvals(manifest)
+
+
+# Imported tools (catalog_imported.yaml) are unreviewed. The gateway refuses a run that is
+# granted an imported write tool without a human approval in front of it (APPROVAL_REQUIRED).
+_IMPORTED_WRITES = frozenset(e.name for e in CATALOG if e.guarantee == "experimental" and e.side_effect == "write")
+
+
+def check_imported_write_approvals(manifest: Manifest) -> list[ManifestIssue]:
+    """One issue per imported write tool the agent may call that no approval covers."""
+    gated = set(manifest.approvals.required_for)
+    return [
+        ManifestIssue(
+            code=ErrorCode.APPROVAL_REQUIRED,
+            location="approvals.required_for",
+            message=f"'{name}' is an imported write tool, so a person must approve each call.",
+            remediation=f"Add '{name}' under approvals.required_for, with a fallback for when it isn't approved.",
+            value=name,
+            severity=Severity.HIGH,
+        )
+        for name in sorted(manifest.declared_tools & _IMPORTED_WRITES - gated)
+    ]
 
 
 def validate_manifest(

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/packages/gravity-schema/pyproject.toml

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

gravity_cli-0.5.0/packages/gravity-schema/tests/test_source_scan.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+import pytest
+from gravity_schema import Manifest, is_agent_source, undeclared_write_tools
+
+
+def manifest(tools: list[str], adapters: dict[str, list[str]] | None = None) -> Manifest:
+    data = {
+        "name": "scan-agent",
+        "version": "1.0.0",
+        "runtime": {"python": "3.12", "entrypoint": "src/agent.py:graph"},
+        "permissions": {"tools": tools},
+    }
+    if adapters:
+        data["slots"] = {"deliver": {"label": "Deliver to", "default": next(iter(adapters)), "adapters": adapters}}
+    return Manifest.model_validate(data)
+
+
+def found(source: str, m: Manifest) -> list[str]:
+    return [i.value for i in undeclared_write_tools([("src/agent.py", source)], m)]
+
+
+@pytest.mark.parametrize("spelling", ["gmail.send", "gmail_send"])
+def test_an_undeclared_send_is_found_in_either_spelling(spelling):
+    assert found(f'TOOL = "{spelling}"\n', manifest(["gmail.read"])) == ["gmail.send"]
+
+
+def test_a_declared_send_is_not_reported():
+    assert found('TOOL = "gmail_send"\n', manifest(["gmail.send"])) == []
+
+
+def test_a_tool_an_adapter_declares_is_granted():
+    m = manifest([], {"slack": ["slack.send"]})
+    assert found('TOOL = "slack_send"\n', m) == []
+
+
+def test_reads_are_left_to_the_drift_warning():
+    assert found('TOOL = "gmail_read"\n', manifest([])) == []
+
+
+def test_docstrings_describe_rather_than_call():
+    source = '"""Never "gmail.send"."""\n\n\ndef f():\n    """Uses gmail_send? No."""\n    return 1\n'
+    assert found(source, manifest([])) == []
+
+
+def test_each_tool_is_reported_once_with_where_it_was_first_seen():
+    sources = [("src/a.py", 'X = "slack.send"\n'), ("src/b.py", 'Y = "slack_send"\nZ = "gmail.send"\n')]
+    issues = undeclared_write_tools(sources, manifest([]))
+    assert [(i.value, i.location, i.code.value) for i in issues] == [
+        ("gmail.send", "src/b.py", "UNDECLARED_TOOL_CALL"),
+        ("slack.send", "src/a.py", "UNDECLARED_TOOL_CALL"),
+    ]
+
+
+def test_a_file_that_does_not_parse_is_skipped():
+    assert found("def broken(:\n  'gmail.send'\n", manifest([])) == []
+
+
+@pytest.mark.parametrize(
+    ("path", "shipped"),
+    [("src/agent.py", True), ("agent.py", True), ("tests/test_x.py", False),
+     (".venv/lib/x.py", False), ("src/__pycache__/x.py", False), ("README.md", False)],
+)
+def test_only_shipped_python_is_scanned(path, shipped):
+    assert is_agent_source(PurePosixPath(path)) is shipped

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/packages/gravity-schema/tests/test_validation.py

@@ -170,3 +170,28 @@ def test_missing_file_reports_clearly(tmp_path):
 
     assert "gravity init" in (ei.value.issues[0].remediation or "")
 
+
+
+def test_an_imported_write_tool_needs_an_approval(manifest_data, catalog):
+    """The gateway refuses a run granted an unreviewed write tool without a human approval."""
+    manifest_data["permissions"]["tools"] = ["gmail.read", "github.add_assignees_to_an_issue"]
+    with pytest.raises(ManifestValidationError) as e:
+        validate_manifest(manifest_data, catalog=catalog)
+    issues = [i for i in e.value.issues if i.code == ErrorCode.APPROVAL_REQUIRED]
+    assert [i.value for i in issues] == ["github.add_assignees_to_an_issue"]
+
+    manifest_data["approvals"] = {"required_for": ["github.add_assignees_to_an_issue"]}
+    validate_manifest(manifest_data, catalog=catalog)
+
+
+def test_curated_writes_and_imported_reads_need_no_approval(manifest_data, catalog):
+    manifest_data["permissions"]["tools"] = ["gmail.send", "github.get_a_repository", "web.search", "web.fetch"]
+    manifest_data.pop("approvals", None)
+    validate_manifest(manifest_data, catalog=catalog)
+
+
+def test_a_tool_in_no_catalog_is_refused(manifest_data, catalog):
+    manifest_data["permissions"]["tools"] = ["composio_search.web"]
+    with pytest.raises(ManifestValidationError) as e:
+        validate_manifest(manifest_data, catalog=catalog)
+    assert {i.code for i in e.value.issues} == {ErrorCode.TOOL_NOT_FOUND}

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "gravity-cli"
-version = "0.4.4"
+version = "0.5.0"
 description = "gravity cli — init, run, and push python agents to the Gravity marketplace"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.12"
 dependencies = [
-    "gravity-schema==0.4.4",  # released in lockstep: always the same version as this package
+    "gravity-schema==0.5.0",  # released in lockstep: always the same version as this package
     "typer>=0.15.0",
     "httpx>=0.27.0",
     "rich>=13.9.0",

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/src/gravity_cli/BUILDER_GUIDE.md

@@ -278,7 +278,7 @@ If any of these is broken, the agent fails when we load or run it.
 | Environment variables are read inside `graph()` | `token = os.environ[...]` inside it | reading them at module level |
 | Imports are absolute from `src/` | `from summary import count_by_sender` | `from .summary import ...`, `from src.summary import ...` |
 | Every tool you call is in the manifest | `gmail.send` listed under `permissions.tools` | calling a tool you didn't list |
-| Tools come only from the gateway, models only from `GRAVITY_LLM_URL` | `tools["gmail_read"]`, `ChatOpenAI(base_url=...)` | `requests.post(...)`, your own API keys, `OPENAI_API_KEY` |
+| Accounts are reached only through tools, models only through `GRAVITY_LLM_URL` | `tools["gmail_read"]`, `ChatOpenAI(base_url=...)` | calling Gmail's API with your own credentials, your own API keys, `OPENAI_API_KEY` |
 | The final state sets `result` | `return {"result": {...}}` | a last node that returns nothing |
 | No Gravity imports | only your code and your dependencies | there's nothing to import anyway |
 | Only declare `messages` in the state if the agent is a conversation | see §6.3 | adding it "just in case" (the agent is then run as a chat) |
@@ -610,7 +610,8 @@ return {"result": result, "memory": {"seen": sorted(seen | delivered)[-1000:]}}
 
 Your agent can be for any field: sales, marketing, finance, support, engineering, operations,
 anything. **The table below is today's starting set, not the limit.** If your agent needs a tool
-that isn't here, use it anyway and describe it as in §7.1; we connect it for you.
+that isn't here, run `gravity tools <app>` first: the gateway serves about 1,100 more tools for the
+same apps. If it still isn't there, ask for it as in §7.1.
 
 | App | Tools |
 |---|---|
@@ -621,12 +622,21 @@ that isn't here, use it anyway and describe it as in §7.1; we connect it for yo
 | Linear | `linear.list_teams`, `linear.list_issues`, `linear.get_issue`, `linear.create_issue` |
 | Slack | `slack.list_channels`, `slack.read_history`, `slack.send`, `slack.find_user` |
 | GitHub (read) | `github.list_commits`, `github.get_commit`, `github.compare`, `github.list_pull_requests`, `github.list_pr_files`, `github.list_pr_reviews`, `github.search_issues` |
+| Web | `web.search`, `web.fetch` (need no account) |
 | Test | `example.echo` (needs no account) |
 
 - In `manifest.yaml` use the dotted name (`gmail.read`); in code use `_` (`tools["gmail_read"]`).
 - Your own pure-Python helpers (scoring, parsing, dedupe) need no tool; put them in `src/`.
-- Only the gateway is reachable from where your agent runs: direct network calls (`requests`,
-  `httpx`, sockets) will fail. Anything outside your own code goes through a tool.
+- **Imported tools need an approval to write.** The tools beyond this table are imported from
+  the vendor and unreviewed. Any imported tool that changes something must also be listed under
+  `approvals.required_for`, or the run is refused with `APPROVAL_REQUIRED`. Reads need nothing
+  extra. `gravity validate` checks this.
+- **Outbound network is open.** Your code may read public pages or public APIs directly (`httpx`,
+  a search library). Anything that acts on a user's account still goes through a tool, so the
+  user's connection and approvals apply. `web.search` and `web.fetch` do the same through the
+  gateway with nothing to install.
+- **Connect your own accounts** for local runs with `gravity connect gmail` (or `slack`,
+  `sheets`, `calendar`, `linear`...). `gravity connect` on its own lists what is connected.
 
 ### 7.1 Using a tool that isn't listed
 
@@ -635,10 +645,11 @@ Do three things; we handle the rest when your files arrive.
 1. **Name it** `app.action`, lowercase, with underscores inside a word if needed:
    `notion.create_page`, `hubspot.find_contact`, `github.list_pull_requests`. Use a plain name
    for what it does, not the app's own API name.
-2. **Use it like any other tool:** list it under `permissions.tools` in `manifest.yaml` (and under
-   `approvals.required_for` if it changes something), and call it in code with `_` for `.`:
-   `tools["notion_create_page"]`. Pass the arguments you describe in step 3 and parse the result
-   with `_payload`.
+2. **Write the code that calls it**, with `_` for `.`: `tools.get("notion_create_page")`. Pass the
+   arguments you describe in step 3 and parse the result with `_payload`. Leave it out of
+   `manifest.yaml` for now: `gravity validate` and the build refuse a tool that isn't in the
+   catalog yet. Once we've added it, declare it under `permissions.tools` (and under
+   `approvals.required_for` if it changes something).
 3. **Describe it** in a `tools_needed.yaml` file in the folder's root, one entry per tool:
 
 ```yaml
@@ -674,8 +685,8 @@ two actions are two tools.
 **What happens next:** we connect each tool to the real app. If an argument name or the result
 shape has to change to fit the real app, we tell you exactly what to change, and it's usually a
 line or two. A few kinds of tool we may not add, such as bulk deletes or anything that moves
-money; we'll say so and suggest an alternative. Because the tool doesn't exist yet on our side,
-a run before we've added it fails with `TOOL_UNAVAILABLE`. That's expected.
+money; we'll say so and suggest an alternative. Once it's added, upgrade the CLI so `gravity
+validate` knows the name: `uv tool install --force --refresh gravity-cli`.
 
 ## 8. What you can check yourself
 
@@ -715,7 +726,10 @@ get the result, or what to fix. Messages you may see:
 |---|---|---|
 | `TOOL_NOT_DECLARED` | Your code called a tool that isn't in the manifest | Add it to `permissions.tools` (or the adapter's list), or stop calling it |
 | `NEEDS_RECONNECT` | Our test account for that app isn't connected | Nothing on your side; we'll connect it |
-| `TOOL_UNAVAILABLE` | That tool isn't available yet | For a listed tool, check the spelling against §7. For a new one, we're adding it (§7.1) |
+| `TOOL_NOT_FOUND` | A tool in `manifest.yaml` isn't in the catalog | Check the spelling with `gravity tools`. For a new one, ask for it (§7.1) |
+| `APPROVAL_REQUIRED` | An imported write tool has no approval | List it under `approvals.required_for`, with a fallback (§6.1) |
+| `UNDECLARED_TOOL_CALL` | Your code names a write tool the manifest doesn't grant | Declare it (and gate it), or remove the call |
+| `TOOL_UNAVAILABLE` | That tool isn't available yet | Check the spelling against §7, or wait until we've added it (§7.1) |
 | `APPROVAL_REJECTED` / `APPROVAL_TIMEOUT` | A gated call wasn't approved | Expected; your fallback should have run |
 | "the final state has no result" | Your last node didn't set `result` | Return `{"result": ...}` |
 | "could not load the agent" | An import error, a relative import, or building the graph at import | Follow §4 |
@@ -724,7 +738,8 @@ get the result, or what to fix. Messages you may see:
 ## 11. Checklist before you send
 
 - [ ] `manifest.yaml`: `contract: v1`, a clear `description`, clear input labels, `python: "3.12"`
-- [ ] Every tool the code calls is declared; nothing makes its own network calls
+- [ ] Every tool the code calls is declared; every account action goes through a tool
+- [ ] Every imported write tool is under `approvals.required_for`
 - [ ] Any tool not in §7's list is described in `tools_needed.yaml` (§7.1)
 - [ ] `src/agent.py` defines `async def graph()`; env vars read inside it; imports absolute from `src/`
 - [ ] Every tool result goes through `_payload`; a failed source is named in the result

{gravity_cli-0.4.4 → gravity_cli-0.5.0}/src/gravity_cli/cli.py

@@ -9,6 +9,7 @@ from typer.core import TyperCommand, TyperGroup
 from . import Problem, config, ui
 from .commands.adapt import adapt_command
 from .commands.build import build_command
+from .commands.connect import connect_command
 from .commands.guide import guide_command
 from .commands.init import TEMPLATES, init_command
 from .commands.login import login_command, logout_command, whoami_command
@@ -85,6 +86,7 @@ for name, command, panel, summary, example in [
     ("login", login_command, ACCOUNT, "Sign in to Gravity in your browser", None),
     ("logout", logout_command, ACCOUNT, "Sign out", None),
     ("whoami", whoami_command, ACCOUNT, "Show who you are signed in as", None),
+    ("connect", connect_command, ACCOUNT, "Connect an account your agents act on (Gmail, Slack...)", "gravity connect gmail"),
     ("guide", guide_command, HELP, "Read the builder guide: how to build a good agent", "gravity guide --save"),
 ]:
     app.command(name, cls=HelpCommand, help=summary, epilog=example, rich_help_panel=panel)(command)