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

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

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.3
+
+- Make manifest schema 2.2 the only accepted plugin contract.
+- Require every manifest to declare typed capabilities and world providers.
+- Require explicit capability authority, audience, task-context, and exposure.
+- Replace model-callability and compatibility metadata with strict exposure and
+  safe non-callability reasons.
+- Require task context for task-owned resources and matching providers for all
+  connection-backed capabilities.
+- Tighten reviewable external writes, immutable envelope mappings,
+  idempotency, and completion receipt validation.
+
 ## 0.2.2
 
 - Add backward-compatible schema-2.1 capability exposure and safe non-callability metadata.

nutria_plugin-0.2.3/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: nutria-plugin
+Version: 0.2.3
+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
+Project-URL: Changelog, https://github.com/AlRos14/nutria-plugin-sdk/blob/main/CHANGELOG.md
+Author-email: Nutria <dev@nutria.ai>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: lxml>=4.9
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nutria-plugin SDK
+
+SDK for building, validating, signing, and packaging Nutria plugins.
+
+Release `0.2.3` is intentionally breaking. It accepts only manifest schema
+`2.2`, requires typed capabilities and world providers, and makes authority,
+audience, task-context requirements, and exposure explicit. There is no runtime
+migration for schema 2.0/2.1 manifests and no compatibility/model-callability
+field.
+
+ChatBotNutralia owns task context, reviewable drafts, revisions, approval,
+idempotency, and completion receipts. Plugins own authoritative provider reads
+and exact delivery of an approved snapshot.
+
+## Install
+
+```bash
+uv add nutria-plugin==0.2.3
+```
+
+## Scaffold and validate
+
+```bash
+nutria-plugin new my-workspace-plugin --name "My Workspace Plugin"
+nutria-plugin validate my-workspace-plugin
+nutria-plugin pack my-workspace-plugin --output my-workspace-plugin-0.1.0.zip
+```
+
+The generated directory contains `plugin.json`, component directories for
+connections, skills, context documents, specs and hooks, plus an optional
+settings schema and assets.
+
+## Minimal schema 2.2 manifest
+
+```json
+{
+  "schema_version": "2.2",
+  "id": "my-workspace-plugin",
+  "name": "My Workspace Plugin",
+  "version": "0.1.0",
+  "description": "Connects Nutria to an authoritative workspace.",
+  "author": "Your Name",
+  "runtime_types": ["declarative_api"],
+  "required_secrets": ["API_KEY"],
+  "remote_endpoints": ["https://api.myworkspace.com"],
+  "capabilities": [{
+    "id": "workspace.search",
+    "title": "Search workspace",
+    "description": "Read matching workspace resources.",
+    "effect": "read",
+    "tool": "search_workspace",
+    "connection_id": "workspace",
+    "requirements": {
+      "authority": "read",
+      "audience": ["team_internal"],
+      "task_context": "optional"
+    },
+    "exposure": "model"
+  }],
+  "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"
+    }]
+  }]
+}
+```
+
+Every capability must declare `requirements` and `exposure`. Host/admin-only
+capabilities also require a safe `non_callable_reason`. Task-owned resources
+(`task`, `artifact`, `prepared_action`) require `task_context: "required"`.
+Every connection referenced by a capability must be represented by a matching
+world provider.
+
+For customer messages, use a host-owned `reviewable_actions` contract. Do not
+create plugin draft tables or native saved-draft tools. See
+[`docs/reviewable-actions.md`](docs/reviewable-actions.md).
+
+## Python API
+
+```python
+from pathlib import Path
+from nutria_plugin import PluginManifest, pack_plugin, validate_plugin_dir
+
+manifest = PluginManifest.from_file(Path("plugin.json"))
+errors = validate_plugin_dir(Path("."))
+archive = pack_plugin(Path("."), Path("dist/plugin.zip"))
+```
+
+The package exports the strict manifest, capability, provider, reviewable-action,
+admin extension/flow, bundle, packaging, and signing models/functions documented
+in [`docs/python-api.md`](docs/python-api.md).
+
+## Bundle and security rules
+
+- `plugin.json` is required at the ZIP root.
+- Paths are relative; traversal, symlinks, hidden paths, and disallowed file
+  extensions are rejected.
+- Maximum compressed bundle size is 20 MB and decompressed size is bounded.
+- Secrets are configured after installation and never stored in the bundle.
+- Remote endpoints are checked for unsafe local/private targets.
+- Database-backed plugins bind user/model values as SQL parameters.
+
+Supported runtime types are `remote_mcp`, `declarative_api`, `openapi_bridge`,
+and `soap_bridge`.
+
+## License
+
+MIT

nutria_plugin-0.2.3/README.md

@@ -0,0 +1,116 @@
+# nutria-plugin SDK
+
+SDK for building, validating, signing, and packaging Nutria plugins.
+
+Release `0.2.3` is intentionally breaking. It accepts only manifest schema
+`2.2`, requires typed capabilities and world providers, and makes authority,
+audience, task-context requirements, and exposure explicit. There is no runtime
+migration for schema 2.0/2.1 manifests and no compatibility/model-callability
+field.
+
+ChatBotNutralia owns task context, reviewable drafts, revisions, approval,
+idempotency, and completion receipts. Plugins own authoritative provider reads
+and exact delivery of an approved snapshot.
+
+## Install
+
+```bash
+uv add nutria-plugin==0.2.3
+```
+
+## Scaffold and validate
+
+```bash
+nutria-plugin new my-workspace-plugin --name "My Workspace Plugin"
+nutria-plugin validate my-workspace-plugin
+nutria-plugin pack my-workspace-plugin --output my-workspace-plugin-0.1.0.zip
+```
+
+The generated directory contains `plugin.json`, component directories for
+connections, skills, context documents, specs and hooks, plus an optional
+settings schema and assets.
+
+## Minimal schema 2.2 manifest
+
+```json
+{
+  "schema_version": "2.2",
+  "id": "my-workspace-plugin",
+  "name": "My Workspace Plugin",
+  "version": "0.1.0",
+  "description": "Connects Nutria to an authoritative workspace.",
+  "author": "Your Name",
+  "runtime_types": ["declarative_api"],
+  "required_secrets": ["API_KEY"],
+  "remote_endpoints": ["https://api.myworkspace.com"],
+  "capabilities": [{
+    "id": "workspace.search",
+    "title": "Search workspace",
+    "description": "Read matching workspace resources.",
+    "effect": "read",
+    "tool": "search_workspace",
+    "connection_id": "workspace",
+    "requirements": {
+      "authority": "read",
+      "audience": ["team_internal"],
+      "task_context": "optional"
+    },
+    "exposure": "model"
+  }],
+  "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"
+    }]
+  }]
+}
+```
+
+Every capability must declare `requirements` and `exposure`. Host/admin-only
+capabilities also require a safe `non_callable_reason`. Task-owned resources
+(`task`, `artifact`, `prepared_action`) require `task_context: "required"`.
+Every connection referenced by a capability must be represented by a matching
+world provider.
+
+For customer messages, use a host-owned `reviewable_actions` contract. Do not
+create plugin draft tables or native saved-draft tools. See
+[`docs/reviewable-actions.md`](docs/reviewable-actions.md).
+
+## Python API
+
+```python
+from pathlib import Path
+from nutria_plugin import PluginManifest, pack_plugin, validate_plugin_dir
+
+manifest = PluginManifest.from_file(Path("plugin.json"))
+errors = validate_plugin_dir(Path("."))
+archive = pack_plugin(Path("."), Path("dist/plugin.zip"))
+```
+
+The package exports the strict manifest, capability, provider, reviewable-action,
+admin extension/flow, bundle, packaging, and signing models/functions documented
+in [`docs/python-api.md`](docs/python-api.md).
+
+## Bundle and security rules
+
+- `plugin.json` is required at the ZIP root.
+- Paths are relative; traversal, symlinks, hidden paths, and disallowed file
+  extensions are rejected.
+- Maximum compressed bundle size is 20 MB and decompressed size is bounded.
+- Secrets are configured after installation and never stored in the bundle.
+- Remote endpoints are checked for unsafe local/private targets.
+- Database-backed plugins bind user/model values as SQL parameters.
+
+Supported runtime types are `remote_mcp`, `declarative_api`, `openapi_bridge`,
+and `soap_bridge`.
+
+## License
+
+MIT

nutria_plugin-0.2.3/docs/index.md

@@ -0,0 +1,21 @@
+# nutria-plugin SDK documentation
+
+Developer reference for SDK `0.2.3` and manifest schema `2.2`.
+
+| Document | Purpose |
+|---|---|
+| [quickstart.md](quickstart.md) | Build a strict schema 2.2 plugin |
+| [manifest.md](manifest.md) | Manifest, capability, and provider contracts |
+| [reviewable-actions.md](reviewable-actions.md) | Host-owned drafts and external delivery |
+| [python-api.md](python-api.md) | Public Python API |
+| [connection-types.md](connection-types.md) | Supported runtime/connection types |
+| [skill-format.md](skill-format.md) | Skill frontmatter and authoring |
+| [admin-extensions.md](admin-extensions.md) | Host-rendered admin views |
+| [admin-flows.md](admin-flows.md) | Host-rendered operator flows |
+| [security.md](security.md) | Signing, ZIP safety, endpoints, and secrets |
+| [cli.md](cli.md) | CLI commands |
+
+A plugin bundle can contain connections, skills, context documents, hooks,
+settings, specs, and declarative admin assets. Its schema 2.2 manifest must also
+declare at least one typed capability and world provider. Older schemas are not
+loaded or migrated.

nutria_plugin-0.2.3/docs/manifest.md

@@ -0,0 +1,84 @@
+# plugin.json manifest reference
+
+`plugin.json` is the single source of truth for plugin identity, runtime,
+capability authority, and provider topology. SDK 0.2.3 accepts exactly schema
+`2.2`; older schemas and unknown fields fail validation.
+
+## Required top-level fields
+
+| Field | Contract |
+|---|---|
+| `schema_version` | Literal `"2.2"` |
+| `id` | Lowercase plugin slug |
+| `name`, `description`, `author` | Non-empty display metadata |
+| `version` | Semantic version |
+| `runtime_types` | One or more supported runtime types |
+| `capabilities` | At least one typed capability |
+| `world_providers` | At least one typed provider |
+
+Optional fields include `default_scope`, `paths`, `required_secrets`,
+`optional_secrets`, `remote_endpoints`, `tags`, `reviewable_actions`,
+`admin_extensions`, `admin_flows`, `mcp_server_entry`, `homepage`, `license`,
+and `signature`. A `compatibility` field is not part of schema 2.2.
+
+## Capability descriptor
+
+Each capability declares:
+
+- stable `id`, `title`, and `description`;
+- `effect`: `read`, `prepare`, `write`, or `external_write`;
+- concrete `tool` and optional `connection_id`;
+- typed `inputs`, `consumes`, and `produces` bindings;
+- required `requirements.authority`, `requirements.audience`, and
+  `requirements.task_context`;
+- required `exposure`: `model`, `host`, or `admin`.
+
+`host` and `admin` exposure require `non_callable_reason` with a stable code and
+safe summary. `model` exposure must not declare it. Task-owned resource bindings
+require `task_context: "required"`.
+
+A model-exposed `external_write` must declare `prepared_action`, `idempotency`,
+and `completion`. Reviewable delivery capabilities are instead host-only and
+are linked through `reviewable_action_id`.
+
+## World provider descriptor
+
+Every provider declares a stable ID, title, description, optional connection
+and health capability, and one or more resource types. Each resource type has:
+
+- a stable built-in or plugin-namespaced `id`;
+- one or more `identity_fields`;
+- optional search/inspect capability references;
+- optional version field, TTL, and named safe/authorized projections.
+
+Capability connections must have a matching provider connection. Referenced
+search, inspect, health, prepare, and execute capabilities must exist in the
+same manifest.
+
+## Reviewable actions
+
+The host owns the encrypted draft and approval lifecycle. A reviewable action
+maps stable semantic fields to one host-only external-write capability. Every
+delivery maps `recipient`, `body`, and `idempotency_key`; required capability
+inputs must be mapped. Preparation capabilities use `effect: "prepare"` and
+must be pure/read-only. See [reviewable-actions.md](reviewable-actions.md).
+
+## Paths and settings
+
+All component paths are relative and cannot contain empty, `.` or `..`
+segments. `settings.schema.json` may use the host extensions
+`x-nutria-store-scoped` and `x-nutria-store-default-key` for values that truly
+vary by store.
+
+## Secrets and endpoints
+
+Secret arrays contain names only. Remote endpoints must be absolute HTTP(S)
+URLs and cannot target localhost, loopback, link-local, private, or reserved IP
+ranges.
+
+## Validation
+
+```bash
+uv run nutria-plugin validate .
+uv run nutria-plugin pack . --output dist/plugin.zip
+```

nutria_plugin-0.2.3/docs/python-api.md

@@ -0,0 +1,78 @@
+# Python API reference
+
+SDK 0.2.3 exposes the strict schema 2.2 API.
+
+```python
+from nutria_plugin import (
+    __version__,
+    PluginManifest, PluginPaths, PluginScope, PluginRuntimeType,
+    CapabilityDescriptor, CapabilityEffect, CapabilityExposure,
+    CapabilityRequirement, CapabilityInputBinding, CapabilityOutputBinding,
+    ResourceBinding, ResourceType, ResourceTypeDescriptor,
+    WorldProjectionDescriptor, WorldProviderDescriptor,
+    PreparedActionDescriptor, IdempotencyDescriptor, CompletionDescriptor,
+    NonCallableReason,
+    ReviewableActionContract, ReviewableActionField, ReviewableActionMode,
+    PreparationToolContract,
+    PluginAdminExtension, PluginAdminExtensionKind,
+    PluginAdminExtensionPlacement,
+    PluginAdminFlow, PluginAdminFlowKind, PluginAdminFlowPlacement,
+    PluginBundleError, load_plugin_bundle, extract_plugin_bundle, validate_zip,
+    PackagingError, scaffold_plugin, pack_plugin, validate_plugin_dir,
+    SignatureStatus, generate_keypair, sign_manifest, verify_manifest,
+)
+```
+
+`PluginCompatibility` and `model_callable` are not part of this API.
+Callability is represented by `CapabilityExposure`; host/admin exposure also
+requires `NonCallableReason`.
+
+## Manifest
+
+```python
+from pathlib import Path
+from nutria_plugin import PluginManifest
+
+manifest = PluginManifest.from_file(Path("plugin.json"))
+same = PluginManifest.from_json_bytes(Path("plugin.json").read_bytes())
+manifest.to_file(Path("plugin.json"))
+payload = manifest.model_dump(mode="json", exclude_none=True)
+```
+
+Validation is strict: schema version must be `2.2`, top-level extras are
+rejected, and capability/provider/action references are checked together.
+
+## Bundles and packaging
+
+```python
+from pathlib import Path
+from nutria_plugin import (
+    load_plugin_bundle, extract_plugin_bundle, validate_zip,
+    scaffold_plugin, validate_plugin_dir, pack_plugin,
+)
+
+raw = Path("plugin.zip").read_bytes()
+manifest = load_plugin_bundle(raw)
+warnings = validate_zip(raw)
+extract_plugin_bundle(raw, Path("installed/plugin"))
+
+scaffold_plugin("my-plugin", "My Plugin", Path("."))
+errors = validate_plugin_dir(Path("my-plugin"))
+archive = pack_plugin(Path("my-plugin"), Path("dist/my-plugin.zip"))
+```
+
+Unsafe bundles raise `PluginBundleError`; invalid source directories or pack
+operations raise `PackagingError`.
+
+## Signing
+
+```python
+from nutria_plugin import generate_keypair, sign_manifest, verify_manifest
+
+private_pem, public_pem = generate_keypair()
+payload = manifest.model_dump(mode="json", exclude_none=True)
+payload["signature"] = sign_manifest(payload, private_pem)
+status = verify_manifest(payload)
+```
+
+Signing uses ECDSA P-256 over canonical JSON with the `signature` field removed.

nutria_plugin-0.2.3/docs/quickstart.md

@@ -0,0 +1,66 @@
+# Quickstart: a schema 2.2 plugin
+
+## Install and scaffold
+
+```bash
+uv add nutria-plugin==0.2.3
+nutria-plugin new inventory-lookup --name "Inventory Lookup"
+```
+
+## Define plugin.json
+
+```json
+{
+  "schema_version": "2.2",
+  "id": "inventory-lookup",
+  "name": "Inventory Lookup",
+  "version": "0.1.0",
+  "description": "Reads authoritative warehouse stock.",
+  "author": "Acme Corp",
+  "runtime_types": ["declarative_api"],
+  "required_secrets": ["WAREHOUSE_API_KEY"],
+  "remote_endpoints": ["https://api.warehouse.example"],
+  "capabilities": [{
+    "id": "warehouse.stock.read",
+    "title": "Read stock",
+    "description": "Read current stock for one SKU.",
+    "effect": "read",
+    "tool": "get_stock",
+    "connection_id": "warehouse",
+    "requirements": {
+      "authority": "read",
+      "audience": ["team_internal", "public_customer"],
+      "task_context": "optional"
+    },
+    "exposure": "model"
+  }],
+  "world_providers": [{
+    "id": "warehouse",
+    "title": "Warehouse",
+    "description": "Authoritative warehouse inventory.",
+    "connection_id": "warehouse",
+    "resource_types": [{
+      "id": "warehouse.stock",
+      "title": "Stock item",
+      "description": "Current stock identity and state.",
+      "identity_fields": ["sku"],
+      "search_capability": "warehouse.stock.read"
+    }]
+  }]
+}
+```
+
+Add the matching declarative connection and skill files generated by the
+scaffold. Assign the connection through the persona's `allowed_connections`;
+the manifest does not own persona assignment.
+
+## Validate and package
+
+```bash
+uv run nutria-plugin validate inventory-lookup
+uv run nutria-plugin pack inventory-lookup \
+  --output inventory-lookup-0.1.0.zip
+```
+
+Any schema 2.0/2.1 field, unknown property, missing provider, or incomplete
+authority/exposure contract fails validation and must be corrected explicitly.

nutria_plugin-0.2.3/docs/reviewable-actions.md

@@ -0,0 +1,90 @@
+# Reviewable actions and external writes
+
+SDK 0.2.3 schema 2.2 defines one reviewable-action architecture:
+
+```text
+ChatBotNutralia -> task context, encrypted draft, revision, approval, idempotency, receipts
+Plugin           -> provider reads, pure preparation, exact approved delivery
+SDK              -> strict capability/provider/reviewable-action contracts
+```
+
+Plugins do not save drafts and do not expose native saved-draft operations.
+
+## Delivery capability
+
+A reviewable delivery capability uses `effect: "external_write"`,
+`exposure: "host"`, a `non_callable_reason`, explicit authority/audience/task
+requirements, input bindings, and `reviewable_action_id`:
+
+```json
+{
+  "id": "whatsapp.send.text",
+  "title": "Send WhatsApp text",
+  "description": "Deliver the exact approved message.",
+  "effect": "external_write",
+  "tool": "send_whatsapp_text",
+  "connection_id": "whatsapp",
+  "requirements": {
+    "authority": "write_external",
+    "audience": ["team_internal", "private_internal"],
+    "task_context": "required"
+  },
+  "exposure": "host",
+  "non_callable_reason": {
+    "code": "host_approval_boundary",
+    "safe_summary": "Executed only by the host after exact-snapshot approval."
+  },
+  "reviewable_action_id": "whatsapp-text",
+  "inputs": [
+    {"semantic_field": "recipient", "argument_name": "recipient"},
+    {"semantic_field": "body", "argument_name": "body"},
+    {"semantic_field": "idempotency_key", "argument_name": "idempotency_key"}
+  ]
+}
+```
+
+The matching top-level action maps stable semantic fields to those exact tool
+arguments:
+
+```json
+{
+  "id": "whatsapp-text",
+  "kind": "customer_message",
+  "channel": "whatsapp",
+  "modes": ["new", "reply"],
+  "connection_id": "whatsapp",
+  "execute_capability": "whatsapp.send.text",
+  "argument_map": {
+    "recipient": "recipient",
+    "body": "body",
+    "idempotency_key": "idempotency_key"
+  },
+  "required_fields": ["recipient", "body"],
+  "editable_fields": ["body"]
+}
+```
+
+Every delivery maps `idempotency_key`. Required execution inputs must appear in
+the action map. Recipient, source/thread/order identities, channel, and mode are
+immutable; only explicitly editable fields can change.
+
+## Pure preparation
+
+An optional reply-envelope preparation capability uses `effect: "prepare"`.
+It may resolve authoritative recipient/thread/source fingerprints but cannot
+persist a draft or write externally. The action's `prepare_capability` and
+`execute_capability` must be distinct and use the same connection.
+
+## Host lifecycle
+
+The host exposes generic prepare, inspect, revise, and send operations. A
+revision creates a new action identity and approval. Delivery executes the
+approved body and immutable envelope exactly once. Success requires the
+declared authoritative completion receipt; unavailable providers keep the local
+draft but cannot produce a successful effect.
+
+Validate the whole cross-reference graph with:
+
+```bash
+uv run nutria-plugin validate .
+```

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

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

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

@@ -3,7 +3,7 @@
 Public API
 ----------
 Models:
-    PluginManifest, PluginPaths, PluginCompatibility, PluginScope, PluginRuntimeType
+    PluginManifest, PluginPaths, PluginScope, PluginRuntimeType
 
 Bundle operations:
     load_plugin_bundle, extract_plugin_bundle, validate_zip
@@ -15,7 +15,7 @@ Signing:
     generate_keypair, sign_manifest, verify_manifest, SignatureStatus
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 from .capabilities import (
     CapabilityDescriptor,
@@ -43,7 +43,6 @@ from .manifest import (
     PluginAdminFlow,
     PluginAdminFlowKind,
     PluginAdminFlowPlacement,
-    PluginCompatibility,
     PluginManifest,
     PluginPaths,
     PreparationToolContract,
@@ -62,7 +61,6 @@ __all__ = [
     # Manifest
     "PluginManifest",
     "PluginPaths",
-    "PluginCompatibility",
     "PluginScope",
     "PluginRuntimeType",
     "PluginAdminExtension",