gravity-schema 0.7.2__tar.gz → 0.7.4__tar.gz

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/PKG-INFO

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

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/gravity_schema/catalog.yaml

@@ -65,6 +65,24 @@
   guarantee: certified
   side_effect: read
 
+- name: browser.read
+  slug: null
+  toolkit: null
+  description: read a page of a site the person signed in to once (an account the manifest declares) through Gravity's browser worker, as that person; returns the final url, the page text and its links. Only pages of the account's own site. The agent never sees the login. Charged to the run's budget
+  scopes: []
+  breadth: generic
+  guarantee: certified
+  side_effect: read
+
+- name: browser.act
+  slug: null
+  toolkit: null
+  description: do one typed action as the person on a site account they signed in to (linkedin.com send_dm, connect, comment; x.com send_dm, reply), with the text given; paced and capped per account per day by the gateway. Must be under approvals.required_for. Returns what was done, or a refusal code (NOT_SIGNED_IN, NOT_CONNECTED, DAILY_CAP, BLOCKED_BY_SITE)
+  scopes: []
+  breadth: generic
+  guarantee: certified
+  side_effect: write
+
 - name: supadata.get_transcript
   slug: null
   toolkit: null
@@ -354,6 +372,15 @@
   guarantee: certified
   side_effect: read
 
+- name: apollo.enrich_person
+  slug: APOLLO_PEOPLE_ENRICHMENT
+  toolkit: apollo
+  description: match one person in Apollo from their name and company domain (or LinkedIn URL) and return their work email, title and profile links; uses the person's own Apollo account and its credits
+  scopes: []
+  breadth: generic
+  guarantee: community
+  side_effect: read
+
 - name: hunter.find_email
   slug: HUNTER_EMAIL_FINDER
   toolkit: hunter

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/gravity_schema/contract.py

@@ -82,6 +82,10 @@ MAX_PREVIOUS_KB: Final[int] = 256
 
 # Declared actions (manifest `actions`).
 MAX_ACTIONS: Final[int] = 20
+# Sites the gateway's browser worker has sign-in and recipes for (accounts, browser.read, browser.act).
+ACCOUNT_SITES: Final[frozenset[str]] = frozenset({"linkedin.com", "x.com"})
+MAX_ACCOUNTS: Final[int] = 5
+BROWSER_TOOLS: Final[frozenset[str]] = frozenset({"browser.read", "browser.act"})
 
 
 # Generous bounds, so a pathological manifest can't tie up the validator.

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/gravity_schema/errors.py

@@ -39,6 +39,7 @@ class ErrorCode(str, Enum):
     INVALID_CONDITION = "INVALID_CONDITION"
     INVALID_ACTION = "INVALID_ACTION"
     INVALID_MEMORY = "INVALID_MEMORY"
+    INVALID_ACCOUNT = "INVALID_ACCOUNT"
     LOCKFILE_MISMATCH = "LOCKFILE_MISMATCH"
     MISSING_FIELD = "MISSING_FIELD"
     UNKNOWN_FIELD = "UNKNOWN_FIELD"

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/gravity_schema/manifest.py

@@ -726,6 +726,42 @@ class ActionSpec(BaseModel):
         return self
 
 
+class AccountSpec(BaseModel):
+    """A site account the person signs in to once on a Gravity page (Accounts vault). The agent never sees the
+    login: the gateway's browser worker opens the session for browser.read and browser.act calls only."""
+
+    model_config = _STRICT
+
+    name: Annotated[str, Field(max_length=C.MAX_NAME_LENGTH)]
+    site: str
+    label: Annotated[str, Field(max_length=C.MAX_LABEL_LENGTH)] = ""
+    purpose: Annotated[str, Field(max_length=C.MAX_LABEL_LENGTH)] = ""
+    required: bool = False
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, v: str) -> str:
+        if not C.INPUT_NAME_RE.match(v):
+            raise PydanticCustomError(
+                ErrorCode.INVALID_ACCOUNT.value,
+                "Account name '{value}' is not a valid identifier.",
+                {"value": v, "remediation": "Use lowercase letters, digits and underscores, e.g. linkedin."},
+            )
+        return v
+
+    @field_validator("site")
+    @classmethod
+    def _check_site(cls, v: str) -> str:
+        site = v.strip().lower().removeprefix("www.")
+        if site not in C.ACCOUNT_SITES:
+            raise PydanticCustomError(
+                ErrorCode.INVALID_ACCOUNT.value,
+                "Accounts on '{value}' are not supported.",
+                {"value": v, "remediation": f"Use one of: {', '.join(sorted(C.ACCOUNT_SITES))}."},
+            )
+        return site
+
+
 class OfferAs(str, Enum):
     """How the actions under a result are shown."""
 
@@ -767,6 +803,8 @@ class Manifest(BaseModel):
     actions: Annotated[list[ActionSpec], Field(max_length=C.MAX_ACTIONS)] = Field(default_factory=list)
     offer_as: OfferAs = OfferAs.BUTTONS
     offer_label: Annotated[str, Field(max_length=C.MAX_LABEL_LENGTH)] | None = None
+    # Site accounts the person signs in to once (Accounts vault); browser.* tools act through them.
+    accounts: Annotated[list[AccountSpec], Field(max_length=C.MAX_ACCOUNTS)] = Field(default_factory=list)
 
     @field_validator("contract")
     @classmethod
@@ -897,6 +935,31 @@ class Manifest(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _check_accounts(self) -> Manifest:
+        names = [a.name for a in self.accounts]
+        dupes = sorted({n for n in names if names.count(n) > 1})
+        if dupes:
+            raise PydanticCustomError(
+                ErrorCode.INVALID_ACCOUNT.value,
+                "Account name(s) declared twice: {value}.",
+                {"value": ", ".join(dupes), "remediation": "Give each account its own name."},
+            )
+        browser = sorted(self.declared_tools & C.BROWSER_TOOLS)
+        if browser and not self.accounts:
+            raise PydanticCustomError(
+                ErrorCode.INVALID_ACCOUNT.value,
+                "{value} acts through a person's own site account, and none is declared.",
+                {"value": ", ".join(browser), "remediation": "Declare the site under `accounts` (e.g. name: linkedin, site: linkedin.com)."},
+            )
+        if "browser.act" in self.declared_tools and "browser.act" not in self.approvals.required_for:
+            raise PydanticCustomError(
+                ErrorCode.APPROVAL_REQUIRED.value,
+                "browser.act sends messages as the person, so each call needs their approval.",
+                {"remediation": "Add browser.act under approvals.required_for, with a fallback for when it isn't approved."},
+            )
+        return self
+
     @model_validator(mode="after")
     def _check_memory(self) -> Manifest:
         if self.state is not None and self.memory is not None:

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/pyproject.toml

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

{gravity_schema-0.7.2 → gravity_schema-0.7.4}/schema/manifest.schema.json

@@ -1,5 +1,43 @@
 {
   "$defs": {
+    "AccountSpec": {
+      "additionalProperties": false,
+      "description": "A site account the person signs in to once on a Gravity page (Accounts vault). The agent never sees the\nlogin: the gateway's browser worker opens the session for browser.read and browser.act calls only.",
+      "properties": {
+        "label": {
+          "default": "",
+          "maxLength": 200,
+          "title": "Label",
+          "type": "string"
+        },
+        "name": {
+          "maxLength": 64,
+          "title": "Name",
+          "type": "string"
+        },
+        "purpose": {
+          "default": "",
+          "maxLength": 200,
+          "title": "Purpose",
+          "type": "string"
+        },
+        "required": {
+          "default": false,
+          "title": "Required",
+          "type": "boolean"
+        },
+        "site": {
+          "title": "Site",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "site"
+      ],
+      "title": "AccountSpec",
+      "type": "object"
+    },
     "ActionSpec": {
       "additionalProperties": false,
       "description": "One thing the agent can do. The runner passes the chosen ones in state[\"actions\"].",
@@ -736,6 +774,14 @@
   "additionalProperties": false,
   "description": "What a builder declares about an agent: identity, entrypoint, consumer inputs, and the tools it is permitted to call. Contract version v1.",
   "properties": {
+    "accounts": {
+      "items": {
+        "$ref": "#/$defs/AccountSpec"
+      },
+      "maxItems": 5,
+      "title": "Accounts",
+      "type": "array"
+    },
     "actions": {
       "items": {
         "$ref": "#/$defs/ActionSpec"

gravity_schema-0.7.4/tests/test_accounts.py

@@ -0,0 +1,42 @@
+"""Site accounts (the Accounts vault) and the browser tools that act through them."""
+
+import pytest
+from gravity_schema import dev_catalog, load_manifest_text, validate_manifest
+from gravity_schema.errors import ManifestValidationError
+
+BASE = {"name": "leads", "runtime": {"entrypoint": "src/agent.py:graph"}}
+LINKEDIN = {"name": "linkedin", "site": "www.LinkedIn.com", "label": "Your LinkedIn", "purpose": "send messages you approve"}
+
+
+def codes(manifest):
+    with pytest.raises(ManifestValidationError) as e:
+        validate_manifest(manifest)
+    return {i.code.value for i in e.value.issues}
+
+
+def test_accounts_with_browser_tools_validate():
+    m = validate_manifest({**BASE, "accounts": [LINKEDIN, {"name": "x", "site": "x.com"}],
+                           "permissions": {"tools": ["browser.read", "browser.act"]},
+                           "approvals": {"required_for": ["browser.act"]}})
+    assert [a.site for a in m.accounts] == ["linkedin.com", "x.com"] and not m.accounts[0].required
+
+
+def test_account_rules():
+    assert codes({**BASE, "accounts": [{"name": "fb", "site": "facebook.com"}]}) == {"INVALID_ACCOUNT"}
+    assert codes({**BASE, "accounts": [LINKEDIN, LINKEDIN]}) == {"INVALID_ACCOUNT"}
+    assert codes({**BASE, "accounts": [{"name": "Linked In", "site": "linkedin.com"}]}) == {"INVALID_ACCOUNT"}
+    assert codes({**BASE, "permissions": {"tools": ["browser.read"]}}) == {"INVALID_ACCOUNT"}  # no account to act through
+    assert codes({**BASE, "accounts": [LINKEDIN], "permissions": {"tools": ["browser.act"]}}) == {"APPROVAL_REQUIRED"}
+
+
+def test_browser_and_apollo_tools_are_in_the_catalog():
+    names = dev_catalog().names()
+    assert {"browser.read", "browser.act", "apollo.enrich_person"} <= names
+    text = """
+name: leads
+runtime: {entrypoint: src/agent.py:graph}
+accounts: [{name: linkedin, site: linkedin.com}]
+permissions: {tools: [browser.read, browser.act, apollo.enrich_person]}
+approvals: {required_for: [browser.act]}
+"""
+    assert load_manifest_text(text, catalog=dev_catalog()).accounts[0].name == "linkedin"