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

{gravity_schema-0.4.4 → gravity_schema-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gravity-schema
-Version: 0.4.4
+Version: 0.5.0
 Summary: Gravity agent manifest contract — models, validation, and JSON Schema export
 License-Expression: Apache-2.0
 License-File: LICENSE

{gravity_schema-0.4.4 → gravity_schema-0.5.0}/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_schema-0.4.4 → gravity_schema-0.5.0}/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_schema-0.4.4 → gravity_schema-0.5.0}/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_schema-0.5.0/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_schema-0.4.4 → gravity_schema-0.5.0}/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_schema-0.4.4 → gravity_schema-0.5.0}/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_schema-0.5.0/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_schema-0.4.4 → gravity_schema-0.5.0}/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}