nutria-plugin 0.2.1__tar.gz → 0.2.2__tar.gz

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.2
+
+- Add backward-compatible schema-2.1 capability exposure and safe non-callability metadata.
+- Add prepared-action, idempotency, and completion receipt contracts.
+- Require model-selectable external writes to declare all execution safety contracts.
+
 ## 0.2.1
 
 - Add manifest schema `2.1` with typed world providers, custom resource types,

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nutria-plugin
-Version: 0.2.1
+Version: 0.2.2
 Summary: SDK for building, validating, signing, and packaging Nutria plugins
 Project-URL: Homepage, https://github.com/AlRos14/nutria-plugin-sdk
 Project-URL: Repository, https://github.com/AlRos14/nutria-plugin-sdk
@@ -21,8 +21,9 @@ Description-Content-Type: text/markdown
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.2.1` adds provider-backed world graph descriptors in manifest schema
-`2.1` while continuing to accept schema `2.0`. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
+Release `0.2.2` adds capability exposure, prepared-action, idempotency, and
+completion contracts to manifest schema `2.1` while continuing to accept existing
+schema `2.0` and `2.1` manifests. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
 plugin only reads channel state and delivers the exact approved snapshot.
 
 This release also supports **declarative admin extensions**, allowing plugins

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/README.md

@@ -2,8 +2,9 @@
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.2.1` adds provider-backed world graph descriptors in manifest schema
-`2.1` while continuing to accept schema `2.0`. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
+Release `0.2.2` adds capability exposure, prepared-action, idempotency, and
+completion contracts to manifest schema `2.1` while continuing to accept existing
+schema `2.0` and `2.1` manifests. ChatBotNutralia owns reviewable drafts, revisions, and approval; a
 plugin only reads channel state and delivers the exact approved snapshot.
 
 This release also supports **declarative admin extensions**, allowing plugins

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nutria-plugin"
-version = "0.2.1"
+version = "0.2.2"
 description = "SDK for building, validating, signing, and packaging Nutria plugins"
 readme = "README.md"
 license = {text = "MIT"}

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/src/nutria_plugin/__init__.py

@@ -15,14 +15,19 @@ Signing:
     generate_keypair, sign_manifest, verify_manifest, SignatureStatus
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 from .capabilities import (
     CapabilityDescriptor,
     CapabilityEffect,
+    CapabilityExposure,
     CapabilityInputBinding,
     CapabilityOutputBinding,
     CapabilityRequirement,
+    CompletionDescriptor,
+    IdempotencyDescriptor,
+    NonCallableReason,
+    PreparedActionDescriptor,
     ResourceBinding,
     ResourceType,
     ResourceTypeDescriptor,
@@ -72,9 +77,14 @@ __all__ = [
     "PreparationToolContract",
     "CapabilityDescriptor",
     "CapabilityEffect",
+    "CapabilityExposure",
     "CapabilityInputBinding",
     "CapabilityOutputBinding",
     "CapabilityRequirement",
+    "CompletionDescriptor",
+    "IdempotencyDescriptor",
+    "NonCallableReason",
+    "PreparedActionDescriptor",
     "ResourceBinding",
     "ResourceType",
     "ResourceTypeDescriptor",

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/src/nutria_plugin/capabilities.py

@@ -18,6 +18,69 @@ class CapabilityEffect(str, Enum):
     EXTERNAL_WRITE = "external_write"
 
 
+class CapabilityExposure(str, Enum):
+    """Who may invoke a graph-visible capability."""
+
+    MODEL = "model"
+    HOST = "host"
+    ADMIN = "admin"
+    DEPRECATED = "deprecated"
+
+
+class NonCallableReason(BaseModel):
+    """Safe explanation for a graph-visible capability that the model cannot load."""
+
+    code: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    safe_summary: str = Field(..., min_length=1, max_length=500)
+
+    model_config = {"extra": "forbid"}
+
+
+class PreparedActionDescriptor(BaseModel):
+    """Exact-preview contract used by the host prepared-action boundary."""
+
+    preview_argument: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
+    preview_value: Any
+    execute_value: Any
+    adapter: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    ttl_seconds: int = Field(..., ge=60, le=86_400)
+    merge_previews: bool
+    guard_mode: str = Field(..., pattern=r"^(always|pending_only)$")
+    argument_default: Any
+
+    model_config = {"extra": "forbid"}
+
+
+class IdempotencyDescriptor(BaseModel):
+    """Execution idempotency contract for a capability."""
+
+    argument_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
+    required_for_execution: bool
+
+    model_config = {"extra": "forbid"}
+
+
+class CompletionDescriptor(BaseModel):
+    """Authoritative receipt kinds required before a capability is complete."""
+
+    receipts: list[str] = Field(..., min_length=1)
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("receipts")
+    @classmethod
+    def _validate_receipts(cls, value: list[str]) -> list[str]:
+        cleaned = list(dict.fromkeys(item.strip() for item in value if item.strip()))
+        if not cleaned:
+            raise ValueError("completion receipts must not be empty")
+        for receipt in cleaned:
+            import re
+
+            if not re.fullmatch(r"^[a-z][a-z0-9_.-]{0,127}$", receipt):
+                raise ValueError("completion receipts must be stable lowercase identifiers")
+        return cleaned
+
+
 class ResourceType(str, Enum):
     TENANT = "tenant"
     CLIENT = "client"
@@ -213,6 +276,11 @@ class CapabilityDescriptor(BaseModel):
     inputs: list[CapabilityInputBinding] = Field(default_factory=list)
     requirements: CapabilityRequirement = Field(default_factory=CapabilityRequirement)
     model_callable: bool = True
+    exposure: CapabilityExposure | None = None
+    non_callable_reason: NonCallableReason | None = None
+    prepared_action: PreparedActionDescriptor | None = None
+    idempotency: IdempotencyDescriptor | None = None
+    completion: CompletionDescriptor | None = None
     reviewable_action_id: str | None = Field(
         default=None, pattern=r"^[a-z][a-z0-9-]{0,63}$"
     )
@@ -221,6 +289,24 @@ class CapabilityDescriptor(BaseModel):
 
     @model_validator(mode="after")
     def _validate_contract(self) -> "CapabilityDescriptor":
+        if self.exposure is None:
+            self.exposure = (
+                CapabilityExposure.MODEL if self.model_callable else CapabilityExposure.HOST
+            )
+            if not self.model_callable and self.non_callable_reason is None:
+                self.non_callable_reason = NonCallableReason(
+                    code="legacy_host_only",
+                    safe_summary="This capability is available only through the trusted host.",
+                )
+        if self.exposure == CapabilityExposure.MODEL and not self.model_callable:
+            raise ValueError("exposure=model requires model_callable=true")
+        if self.exposure != CapabilityExposure.MODEL:
+            if self.model_callable:
+                raise ValueError("non-model exposure requires model_callable=false")
+            if self.non_callable_reason is None:
+                raise ValueError("non-model exposure requires non_callable_reason")
+        elif self.non_callable_reason is not None:
+            raise ValueError("model exposure must not declare non_callable_reason")
         if self.connection_id and self.requirements.connection_id not in (None, self.connection_id):
             raise ValueError("capability connection_id conflicts with its requirement")
         if (
@@ -235,6 +321,25 @@ class CapabilityDescriptor(BaseModel):
         output_names = [item.output_name for item in self.produces]
         if len(output_names) != len(set(output_names)):
             raise ValueError("capability outputs must not repeat output names")
+        if self.effect == CapabilityEffect.EXTERNAL_WRITE and self.model_callable:
+            missing = [
+                name
+                for name, value in (
+                    ("prepared_action", self.prepared_action),
+                    ("idempotency", self.idempotency),
+                    ("completion", self.completion),
+                )
+                if value is None
+            ]
+            if missing:
+                raise ValueError(
+                    "model-selectable external writes require " + ", ".join(missing)
+                )
+            assert self.idempotency is not None
+            if not self.idempotency.required_for_execution:
+                raise ValueError(
+                    "model-selectable external writes require execution idempotency"
+                )
         return self
 
 

nutria_plugin-0.2.2/tests/test_capability_contracts.py

@@ -0,0 +1,97 @@
+"""Capability exposure and effect-safety contracts introduced in SDK 0.2.2."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from nutria_plugin import CapabilityDescriptor, CapabilityExposure
+
+
+def _capability(**overrides):
+    payload = {
+        "id": "shipping.create",
+        "title": "Create shipment",
+        "description": "Create one shipment after an exact preview.",
+        "effect": "external_write",
+        "tool": "create_shipment",
+    }
+    payload.update(overrides)
+    return payload
+
+
+def _safety_contracts():
+    return {
+        "prepared_action": {
+            "preview_argument": "preview_only",
+            "preview_value": True,
+            "execute_value": False,
+            "adapter": "exact_preview",
+            "ttl_seconds": 3600,
+            "merge_previews": True,
+            "guard_mode": "pending_only",
+            "argument_default": True,
+        },
+        "idempotency": {
+            "argument_name": "idempotency_key",
+            "required_for_execution": True,
+        },
+        "completion": {"receipts": ["shipping.shipment.created"]},
+    }
+
+
+def test_legacy_model_capability_gets_explicit_model_exposure():
+    descriptor = CapabilityDescriptor.model_validate(
+        _capability(effect="read", model_callable=True)
+    )
+    assert descriptor.exposure == CapabilityExposure.MODEL
+    assert descriptor.non_callable_reason is None
+
+
+def test_legacy_non_callable_capability_gets_safe_host_projection():
+    descriptor = CapabilityDescriptor.model_validate(
+        _capability(model_callable=False)
+    )
+    assert descriptor.exposure == CapabilityExposure.HOST
+    assert descriptor.non_callable_reason.code == "legacy_host_only"
+
+
+@pytest.mark.parametrize("exposure", ["host", "admin", "deprecated"])
+def test_non_model_exposure_requires_reason(exposure):
+    with pytest.raises(ValidationError, match="non_callable_reason"):
+        CapabilityDescriptor.model_validate(
+            _capability(exposure=exposure, model_callable=False)
+        )
+
+
+def test_model_exposure_requires_model_callable():
+    with pytest.raises(ValidationError, match="model_callable"):
+        CapabilityDescriptor.model_validate(
+            _capability(exposure="model", model_callable=False)
+        )
+
+
+def test_model_selectable_external_write_requires_all_safety_contracts():
+    with pytest.raises(ValidationError, match="prepared_action"):
+        CapabilityDescriptor.model_validate(_capability())
+
+    descriptor = CapabilityDescriptor.model_validate(
+        _capability(**_safety_contracts())
+    )
+    assert descriptor.prepared_action.adapter == "exact_preview"
+    assert descriptor.idempotency.required_for_execution is True
+    assert descriptor.completion.receipts == ["shipping.shipment.created"]
+
+
+def test_host_external_write_remains_valid_without_prepared_contract():
+    descriptor = CapabilityDescriptor.model_validate(
+        _capability(
+            exposure="host",
+            model_callable=False,
+            non_callable_reason={
+                "code": "prepared_execution_only",
+                "safe_summary": "Execution is restricted to the prepared-action host.",
+            },
+        )
+    )
+    assert descriptor.exposure == CapabilityExposure.HOST

{nutria_plugin-0.2.1 → nutria_plugin-0.2.2}/uv.lock

@@ -262,7 +262,7 @@ wheels = [
 
 [[package]]
 name = "nutria-plugin"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },