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

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

@@ -1,5 +1,18 @@
 # 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,
+  stable identity fields, safe projections, and provider capability references.
+- Keep schema `2.0` compatible and export the new provider descriptor models.
+- Scaffold new plugins with schema `2.1` while preserving the 0.3.0 roadmap.
+
 ## 0.2.0
 
 - Make manifest schema `2.0` the single production schema.

{nutria_plugin-0.2.0 → 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.0
+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.0` introduces the typed capability graph and manifest 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
@@ -62,7 +63,7 @@ my-workspace-plugin/
 
 ```json
 {
-  "schema_version": "2.0",
+  "schema_version": "2.1",
   "id": "my-workspace-plugin",
   "name": "My Workspace Plugin",
   "version": "0.1.0",
@@ -81,7 +82,20 @@ my-workspace-plugin/
       "tool": "search_workspace",
       "connection_id": "workspace"
     }
-  ]
+  ],
+  "world_providers": [{
+    "id": "workspace",
+    "title": "Workspace",
+    "description": "Authoritative workspace resources.",
+    "connection_id": "workspace",
+    "resource_types": [{
+      "id": "workspace.item",
+      "title": "Workspace item",
+      "description": "One stable workspace item.",
+      "identity_fields": ["id"],
+      "search_capability": "workspace.search"
+    }]
+  }]
 }
 ```
 

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

@@ -2,8 +2,9 @@
 
 SDK for building, validating, signing, and packaging Nutria plugins.
 
-Release `0.2.0` introduces the typed capability graph and manifest 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
@@ -43,7 +44,7 @@ my-workspace-plugin/
 
 ```json
 {
-  "schema_version": "2.0",
+  "schema_version": "2.1",
   "id": "my-workspace-plugin",
   "name": "My Workspace Plugin",
   "version": "0.1.0",
@@ -62,7 +63,20 @@ my-workspace-plugin/
       "tool": "search_workspace",
       "connection_id": "workspace"
     }
-  ]
+  ],
+  "world_providers": [{
+    "id": "workspace",
+    "title": "Workspace",
+    "description": "Authoritative workspace resources.",
+    "connection_id": "workspace",
+    "resource_types": [{
+      "id": "workspace.item",
+      "title": "Workspace item",
+      "description": "One stable workspace item.",
+      "identity_fields": ["id"],
+      "search_capability": "workspace.search"
+    }]
+  }]
 }
 ```
 

{nutria_plugin-0.2.0 → nutria_plugin-0.2.2}/docs/index.md

@@ -31,6 +31,7 @@ Plugins define:
 - **Settings schema** — admin-configurable options shown in the Nutria UI
 - **Admin extensions** — safe, declarative operator views rendered by the Nutria host
 - **Admin flows** — safe, declarative operator workflows such as external login/pairing
+- **World providers** — resource types and capability paths injected into the host graph
 
 ## Minimal plugin structure
 
@@ -53,7 +54,7 @@ my-plugin/
 
 ## Version
 
-This documentation describes `nutria-plugin` **v0.2.0** and manifest schema
-**2.0**.
+This documentation describes `nutria-plugin` **v0.2.1** and manifest schema
+**2.1**. Schema 2.0 remains accepted for plugins that do not declare world providers.
 
 API and file format compatibility are not yet guaranteed between pre-release releases.

{nutria_plugin-0.2.0 → nutria_plugin-0.2.2}/docs/manifest.md

@@ -8,7 +8,7 @@ directory as `plugin.json`.
 
 ```json
 {
-  "schema_version": "2.0",
+  "schema_version": "2.1",
   "id": "my-plugin",
   "name": "My Plugin",
   "version": "0.1.0",
@@ -42,6 +42,19 @@ directory as `plugin.json`.
       "connection_id": "workspace"
     }
   ],
+  "world_providers": [{
+    "id": "workspace",
+    "title": "Workspace",
+    "description": "Authoritative workspace resources.",
+    "connection_id": "workspace",
+    "resource_types": [{
+      "id": "workspace.item",
+      "title": "Workspace item",
+      "description": "One stable workspace item.",
+      "identity_fields": ["id"],
+      "search_capability": "workspace.search"
+    }]
+  }],
   "tags": ["crm", "sales"],
   "admin_extensions": [
     {
@@ -73,7 +86,8 @@ directory as `plugin.json`.
 
 ### `schema_version` *(string, required)*
 
-The manifest schema is `"2.0"`. Every plugin must declare this version.
+The current manifest schema is `"2.1"`; schema `"2.0"` remains accepted for
+backward compatibility. Schema 2.1 adds provider-backed world graph contracts.
 Capabilities and reviewable actions are typed by the SDK; schema `1.x` is not
 accepted by the production host.
 
@@ -285,6 +299,20 @@ See [reviewable-actions.md](reviewable-actions.md) for the complete schema.
 
 ---
 
+### `world_providers` *(array of objects, optional; schema 2.1)*
+
+Each provider declares a stable `id`, title, description, optional
+`connection_id` and `health_capability`, plus one or more resource types. A
+resource type has a stable built-in or plugin-namespaced custom `id`, at least
+one `identity_fields` entry, optional `search_capability` and
+`inspect_capability`, bounded `ttl_seconds`, and named safe `projections`.
+
+Referenced capabilities must exist in the same manifest. Provider declarations
+describe navigation only: the host still enforces audience, persona assignment,
+connection state, and effect authorization before executing a tool.
+
+---
+
 ### `tags` *(array of strings, optional)*
 
 Discovery tags shown in the plugin marketplace.

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

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

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

@@ -15,16 +15,24 @@ Signing:
     generate_keypair, sign_manifest, verify_manifest, SignatureStatus
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 from .capabilities import (
     CapabilityDescriptor,
     CapabilityEffect,
+    CapabilityExposure,
     CapabilityInputBinding,
     CapabilityOutputBinding,
     CapabilityRequirement,
+    CompletionDescriptor,
+    IdempotencyDescriptor,
+    NonCallableReason,
+    PreparedActionDescriptor,
     ResourceBinding,
     ResourceType,
+    ResourceTypeDescriptor,
+    WorldProjectionDescriptor,
+    WorldProviderDescriptor,
 )
 
 
@@ -69,11 +77,19 @@ __all__ = [
     "PreparationToolContract",
     "CapabilityDescriptor",
     "CapabilityEffect",
+    "CapabilityExposure",
     "CapabilityInputBinding",
     "CapabilityOutputBinding",
     "CapabilityRequirement",
+    "CompletionDescriptor",
+    "IdempotencyDescriptor",
+    "NonCallableReason",
+    "PreparedActionDescriptor",
     "ResourceBinding",
     "ResourceType",
+    "ResourceTypeDescriptor",
+    "WorldProjectionDescriptor",
+    "WorldProviderDescriptor",
     # Bundle
     "PluginBundleError",
     "load_plugin_bundle",

nutria_plugin-0.2.2/src/nutria_plugin/capabilities.py

@@ -0,0 +1,350 @@
+"""Typed resource and capability contracts for Nutria plugin manifests."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+_RESOURCE_TYPE_PATTERN = r"^[a-z][a-z0-9_.-]{0,127}$"
+
+
+class CapabilityEffect(str, Enum):
+    READ = "read"
+    PREPARE = "prepare"
+    WRITE = "write"
+    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"
+    BRAND = "brand"
+    AGENT = "agent"
+    SERVICE_PRINCIPAL = "service_principal"
+    HUMAN_ACTOR = "human_actor"
+    CUSTOMER_SESSION = "customer_session"
+    CONNECTOR = "connector"
+    TEAM = "team"
+    AUTHORITY_GRANT = "authority_grant"
+    CONVERSATION = "conversation"
+    CHANNEL_CONVERSATION = "channel_conversation"
+    MESSAGE = "message"
+    CHANNEL_EVENT = "channel_event"
+    ATTACHMENT = "attachment"
+    CASE = "case"
+    ORDER = "order"
+    PREPARED_ACTION = "prepared_action"
+    OPERATION = "operation"
+    RESPONSE = "response"
+    ARTIFACT = "artifact"
+    CAPABILITY = "capability"
+    CUSTOMER = "customer"
+    EMAIL_THREAD = "email_thread"
+    EMAIL_MESSAGE = "email_message"
+    WHATSAPP_CHAT = "whatsapp_chat"
+    WHATSAPP_MESSAGE = "whatsapp_message"
+    WHATSAPP_ATTACHMENT = "whatsapp_attachment"
+    PRODUCT = "product"
+    FILE = "file"
+    TASK = "task"
+    TRELLO_BOARD = "trello_board"
+    TRELLO_CARD = "trello_card"
+    TRELLO_LABEL = "trello_label"
+    MRW_SHIPMENT = "mrw_shipment"
+    MRW_LABEL = "mrw_label"
+
+
+class CapabilityRequirement(BaseModel):
+    """Runtime requirement evaluated by the host before exposing a capability."""
+
+    authority: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    connection_id: str | None = Field(default=None, pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
+    audience: list[str] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("audience")
+    @classmethod
+    def _validate_audience(cls, value: list[str]) -> list[str]:
+        return list(dict.fromkeys(item.strip() for item in value if item.strip()))
+
+
+class ResourceBinding(BaseModel):
+    """A resource consumed or produced by a capability."""
+
+    name: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    resource_type: ResourceType | str
+    required: bool = True
+    many: bool = False
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("resource_type")
+    @classmethod
+    def _validate_resource_type(cls, value: ResourceType | str) -> ResourceType | str:
+        _validate_resource_type_id(value)
+        return value
+
+
+class CapabilityInputBinding(BaseModel):
+    """Maps a semantic input to one plugin tool argument."""
+
+    semantic_field: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    argument_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
+    resource_type: ResourceType | str | None = None
+    required: bool = True
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("resource_type")
+    @classmethod
+    def _validate_resource_type(cls, value: ResourceType | str | None) -> ResourceType | str | None:
+        if value is not None:
+            _validate_resource_type_id(value)
+        return value
+
+
+class CapabilityOutputBinding(BaseModel):
+    """Maps one plugin result field to a typed resource output."""
+
+    field_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$")
+    resource_type: ResourceType | str
+    output_name: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    many: bool = False
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("resource_type")
+    @classmethod
+    def _validate_resource_type(cls, value: ResourceType | str) -> ResourceType | str:
+        _validate_resource_type_id(value)
+        return value
+
+
+def _validate_resource_type_id(value: ResourceType | str) -> None:
+    import re
+
+    raw = value.value if isinstance(value, ResourceType) else str(value)
+    if not re.fullmatch(_RESOURCE_TYPE_PATTERN, raw):
+        raise ValueError("resource type must be a stable lowercase identifier")
+
+
+class WorldProjectionDescriptor(BaseModel):
+    """Named provider projection; payload fields remain provider-owned."""
+
+    id: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,63}$")
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(default="", max_length=1_000)
+    fields: list[str] = Field(default_factory=list, max_length=64)
+    sensitivity: str = Field(default="safe", pattern=r"^(safe|authorized)$")
+
+    model_config = {"extra": "forbid"}
+
+
+class ResourceTypeDescriptor(BaseModel):
+    """How one provider exposes a stable resource namespace to the world."""
+
+    id: ResourceType | str
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(..., min_length=1, max_length=2_000)
+    identity_fields: list[str] = Field(default_factory=list, min_length=1, max_length=16)
+    version_field: str | None = Field(default=None, max_length=128)
+    search_capability: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    inspect_capability: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    ttl_seconds: int = Field(default=300, ge=0, le=86_400)
+    projections: list[WorldProjectionDescriptor] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("id")
+    @classmethod
+    def _validate_id(cls, value: ResourceType | str) -> ResourceType | str:
+        _validate_resource_type_id(value)
+        return value
+
+    @model_validator(mode="after")
+    def _validate_projections(self) -> "ResourceTypeDescriptor":
+        ids = [item.id for item in self.projections]
+        if len(ids) != len(set(ids)):
+            raise ValueError("resource projections must not repeat IDs")
+        return self
+
+
+class WorldProviderDescriptor(BaseModel):
+    """Static contract projected into the host-owned agent world graph."""
+
+    id: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(..., min_length=1, max_length=2_000)
+    connection_id: str | None = Field(
+        default=None, pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$"
+    )
+    health_capability: str | None = Field(
+        default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$"
+    )
+    resource_types: list[ResourceTypeDescriptor] = Field(default_factory=list, min_length=1)
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def _validate_resources(self) -> "WorldProviderDescriptor":
+        ids = [item.id.value if isinstance(item.id, ResourceType) else str(item.id) for item in self.resource_types]
+        if len(ids) != len(set(ids)):
+            raise ValueError("world provider resource types must not repeat IDs")
+        return self
+
+
+class CapabilityDescriptor(BaseModel):
+    """Declarative capability contract shared by SDK, host, and plugins."""
+
+    id: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
+    title: str = Field(..., min_length=1, max_length=160)
+    description: str = Field(..., min_length=1, max_length=2_000)
+    effect: CapabilityEffect
+    tool: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
+    connection_id: str | None = Field(
+        default=None, pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$"
+    )
+    consumes: list[ResourceBinding] = Field(default_factory=list)
+    produces: list[CapabilityOutputBinding] = Field(default_factory=list)
+    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}$"
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @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 (
+            self.reviewable_action_id
+            and self.effect == CapabilityEffect.EXTERNAL_WRITE
+            and self.model_callable
+        ):
+            raise ValueError("reviewable delivery capabilities must be host-only")
+        input_names = [item.semantic_field for item in self.inputs]
+        if len(input_names) != len(set(input_names)):
+            raise ValueError("capability inputs must not repeat semantic fields")
+        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
+
+
+def normalize_capability_map(value: Any) -> list[CapabilityDescriptor]:
+    """Parse a manifest capability list with a useful validation error."""
+    if not isinstance(value, list):
+        raise ValueError("capabilities must be a list of capability descriptors")
+    return [CapabilityDescriptor.model_validate(item) for item in value]

{nutria_plugin-0.2.0 → nutria_plugin-0.2.2}/src/nutria_plugin/manifest.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
-from .capabilities import CapabilityDescriptor, CapabilityEffect
+from .capabilities import CapabilityDescriptor, CapabilityEffect, ResourceType, WorldProviderDescriptor
 
 _SEMVER_RE = re.compile(
     r"^(0|[1-9]\d*)\."
@@ -325,7 +325,7 @@ class PluginAdminFlow(BaseModel):
 class PluginManifest(BaseModel):
     """Manifest stored in plugin.json — the single source of truth for plugin metadata."""
 
-    schema_version: str = Field(..., pattern=r"^2\.0$")
+    schema_version: str = Field(..., pattern=r"^2\.(0|1)$")
     id: str = Field(..., pattern=r"^[a-z][a-z0-9\-]*$", max_length=64)
     name: str = Field(..., min_length=1, max_length=128)
     version: str = Field(..., min_length=5, max_length=64)
@@ -339,6 +339,7 @@ class PluginManifest(BaseModel):
     optional_secrets: List[str] = Field(default_factory=list)
     remote_endpoints: List[str] = Field(default_factory=list)
     capabilities: List[CapabilityDescriptor] = Field(default_factory=list)
+    world_providers: List[WorldProviderDescriptor] = Field(default_factory=list)
     tags: List[str] = Field(default_factory=list)
     reviewable_actions: List[ReviewableActionContract] = Field(default_factory=list)
     admin_extensions: List[PluginAdminExtension] = Field(default_factory=list)
@@ -376,6 +377,26 @@ class PluginManifest(BaseModel):
         if len(action_ids_list) != len(set(action_ids_list)):
             raise ValueError("reviewable_actions must not contain duplicate contract IDs")
         capability_map = {capability.id: capability for capability in self.capabilities}
+        provider_ids = [provider.id for provider in self.world_providers]
+        if len(provider_ids) != len(set(provider_ids)):
+            raise ValueError("world_providers must not contain duplicate IDs")
+        for provider in self.world_providers:
+            for resource in provider.resource_types:
+                resource_id = resource.id.value if isinstance(resource.id, ResourceType) else str(resource.id)
+                for field_name, capability_id in (
+                    ("search_capability", resource.search_capability),
+                    ("inspect_capability", resource.inspect_capability),
+                ):
+                    if capability_id and capability_id not in capability_map:
+                        raise ValueError(
+                            f"world provider resource {resource_id!r} {field_name} references "
+                            f"unknown capability {capability_id!r}"
+                        )
+                if provider.health_capability and provider.health_capability not in capability_map:
+                    raise ValueError(
+                        f"world provider {provider.id!r} references unknown health capability "
+                        f"{provider.health_capability!r}"
+                    )
         action_ids = set(action_ids_list)
         for action in self.reviewable_actions:
             execute = capability_map.get(action.execute_capability)

{nutria_plugin-0.2.0 → nutria_plugin-0.2.2}/src/nutria_plugin/packaging.py

@@ -25,7 +25,7 @@ class PackagingError(Exception):
 SCAFFOLD_TEMPLATE = {
     "plugin.json": lambda plugin_id, name: json.dumps(
         {
-            "schema_version": "2.0",
+            "schema_version": "2.1",
             "id": plugin_id,
             "name": name,
             "version": "0.1.0",

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.0 → nutria_plugin-0.2.2}/tests/test_manifest.py

@@ -64,7 +64,7 @@ def test_version_must_be_semver():
         PluginManifest.model_validate(_minimal_manifest(version="1.0"))
 
 
-def test_schema_version_must_be_2_0():
+def test_schema_version_must_be_2_x():
     with pytest.raises(ValidationError):
         PluginManifest.model_validate(_minimal_manifest(schema_version="1.1"))
 
@@ -74,6 +74,80 @@ def test_schema_version_1_x_is_rejected():
         PluginManifest.model_validate(_minimal_manifest(schema_version="1.0"))
 
 
+def test_schema_2_1_world_provider_accepts_custom_resource_type():
+    manifest = PluginManifest.model_validate(
+        _minimal_manifest(
+            schema_version="2.1",
+            capabilities=[
+                {
+                    "id": "workspace.search",
+                    "title": "Search workspace",
+                    "description": "Find authoritative workspace items.",
+                    "effect": "read",
+                    "tool": "search_workspace",
+                    "connection_id": "workspace",
+                    "produces": [
+                        {
+                            "field_name": "items",
+                            "resource_type": "workspace.item",
+                            "output_name": "items",
+                            "many": True,
+                        }
+                    ],
+                }
+            ],
+            world_providers=[
+                {
+                    "id": "workspace",
+                    "title": "Workspace",
+                    "description": "Authoritative workspace provider.",
+                    "connection_id": "workspace",
+                    "resource_types": [
+                        {
+                            "id": "workspace.item",
+                            "title": "Workspace item",
+                            "description": "A stable workspace item.",
+                            "identity_fields": ["id"],
+                            "search_capability": "workspace.search",
+                            "projections": [
+                                {"id": "admin", "title": "Admin", "fields": ["id"]}
+                            ],
+                        }
+                    ],
+                }
+            ],
+        )
+    )
+
+    assert manifest.schema_version == "2.1"
+    assert manifest.world_providers[0].resource_types[0].id == "workspace.item"
+
+
+def test_world_provider_rejects_unknown_capability_reference():
+    with pytest.raises(ValidationError, match="unknown capability"):
+        PluginManifest.model_validate(
+            _minimal_manifest(
+                schema_version="2.1",
+                world_providers=[
+                    {
+                        "id": "workspace",
+                        "title": "Workspace",
+                        "description": "Authoritative workspace provider.",
+                        "resource_types": [
+                            {
+                                "id": "workspace.item",
+                                "title": "Workspace item",
+                                "description": "A stable workspace item.",
+                                "identity_fields": ["id"],
+                                "search_capability": "workspace.missing",
+                            }
+                        ],
+                    }
+                ],
+            )
+        )
+
+
 def test_empty_runtime_types_rejected():
     with pytest.raises(ValidationError):
         PluginManifest.model_validate(_minimal_manifest(runtime_types=[]))

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

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

nutria_plugin-0.2.0/src/nutria_plugin/capabilities.py

@@ -1,142 +0,0 @@
-"""Typed resource and capability contracts for Nutria plugin manifests."""
-
-from __future__ import annotations
-
-from enum import Enum
-from typing import Any
-
-from pydantic import BaseModel, Field, field_validator, model_validator
-
-
-class CapabilityEffect(str, Enum):
-    READ = "read"
-    PREPARE = "prepare"
-    WRITE = "write"
-    EXTERNAL_WRITE = "external_write"
-
-
-class ResourceType(str, Enum):
-    TENANT = "tenant"
-    CLIENT = "client"
-    BRAND = "brand"
-    AGENT = "agent"
-    SERVICE_PRINCIPAL = "service_principal"
-    HUMAN_ACTOR = "human_actor"
-    CUSTOMER_SESSION = "customer_session"
-    CONNECTOR = "connector"
-    TEAM = "team"
-    AUTHORITY_GRANT = "authority_grant"
-    CONVERSATION = "conversation"
-    CHANNEL_CONVERSATION = "channel_conversation"
-    MESSAGE = "message"
-    CHANNEL_EVENT = "channel_event"
-    ATTACHMENT = "attachment"
-    CASE = "case"
-    ORDER = "order"
-    PREPARED_ACTION = "prepared_action"
-    OPERATION = "operation"
-    RESPONSE = "response"
-    ARTIFACT = "artifact"
-    CAPABILITY = "capability"
-    CUSTOMER = "customer"
-    EMAIL_THREAD = "email_thread"
-    EMAIL_MESSAGE = "email_message"
-    WHATSAPP_CHAT = "whatsapp_chat"
-    WHATSAPP_MESSAGE = "whatsapp_message"
-    WHATSAPP_ATTACHMENT = "whatsapp_attachment"
-
-
-class CapabilityRequirement(BaseModel):
-    """Runtime requirement evaluated by the host before exposing a capability."""
-
-    authority: str | None = Field(default=None, pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
-    connection_id: str | None = Field(default=None, pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
-    audience: list[str] = Field(default_factory=list)
-
-    model_config = {"extra": "forbid"}
-
-    @field_validator("audience")
-    @classmethod
-    def _validate_audience(cls, value: list[str]) -> list[str]:
-        return list(dict.fromkeys(item.strip() for item in value if item.strip()))
-
-
-class ResourceBinding(BaseModel):
-    """A resource consumed or produced by a capability."""
-
-    name: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
-    resource_type: ResourceType
-    required: bool = True
-    many: bool = False
-
-    model_config = {"extra": "forbid"}
-
-
-class CapabilityInputBinding(BaseModel):
-    """Maps a semantic input to one plugin tool argument."""
-
-    semantic_field: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
-    argument_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
-    resource_type: ResourceType | None = None
-    required: bool = True
-
-    model_config = {"extra": "forbid"}
-
-
-class CapabilityOutputBinding(BaseModel):
-    """Maps one plugin result field to a typed resource output."""
-
-    field_name: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$")
-    resource_type: ResourceType
-    output_name: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
-    many: bool = False
-
-    model_config = {"extra": "forbid"}
-
-
-class CapabilityDescriptor(BaseModel):
-    """Declarative capability contract shared by SDK, host, and plugins."""
-
-    id: str = Field(..., pattern=r"^[a-z][a-z0-9_.-]{0,127}$")
-    title: str = Field(..., min_length=1, max_length=160)
-    description: str = Field(..., min_length=1, max_length=2_000)
-    effect: CapabilityEffect
-    tool: str = Field(..., pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$")
-    connection_id: str | None = Field(
-        default=None, pattern=r"^[a-zA-Z][a-zA-Z0-9_-]{0,127}$"
-    )
-    consumes: list[ResourceBinding] = Field(default_factory=list)
-    produces: list[CapabilityOutputBinding] = Field(default_factory=list)
-    inputs: list[CapabilityInputBinding] = Field(default_factory=list)
-    requirements: CapabilityRequirement = Field(default_factory=CapabilityRequirement)
-    model_callable: bool = True
-    reviewable_action_id: str | None = Field(
-        default=None, pattern=r"^[a-z][a-z0-9-]{0,63}$"
-    )
-
-    model_config = {"extra": "forbid"}
-
-    @model_validator(mode="after")
-    def _validate_contract(self) -> "CapabilityDescriptor":
-        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 (
-            self.reviewable_action_id
-            and self.effect == CapabilityEffect.EXTERNAL_WRITE
-            and self.model_callable
-        ):
-            raise ValueError("reviewable delivery capabilities must be host-only")
-        input_names = [item.semantic_field for item in self.inputs]
-        if len(input_names) != len(set(input_names)):
-            raise ValueError("capability inputs must not repeat semantic fields")
-        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")
-        return self
-
-
-def normalize_capability_map(value: Any) -> list[CapabilityDescriptor]:
-    """Parse a manifest capability list with a useful validation error."""
-    if not isinstance(value, list):
-        raise ValueError("capabilities must be a list of capability descriptors")
-    return [CapabilityDescriptor.model_validate(item) for item in value]