@clowder-ai/plugin-contract 0.2.0 → 0.3.0

package/src/schemas/behavior-fixture.schema.json

@@ -115,13 +115,6 @@
         "caller": {
           "$ref": "#/$defs/FixtureCaller"
         },
-        "grants": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/CapabilityName"
-          },
-          "uniqueItems": true
-        },
         "handles": {
           "type": "object",
           "additionalProperties": {
@@ -135,7 +128,6 @@
       },
       "required": [
         "caller",
-        "grants",
         "handles",
         "state"
       ],
@@ -239,38 +231,6 @@
           ],
           "additionalProperties": false
         },
-        {
-          "type": "object",
-          "properties": {
-            "operation": {
-              "const": "applyGrantPreset"
-            },
-            "input": {
-              "$ref": "#/$defs/GrantPresetInput"
-            }
-          },
-          "required": [
-            "operation",
-            "input"
-          ],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "operation": {
-              "const": "revokeGrant"
-            },
-            "input": {
-              "$ref": "#/$defs/RevokeGrantInput"
-            }
-          },
-          "required": [
-            "operation",
-            "input"
-          ],
-          "additionalProperties": false
-        },
         {
           "type": "object",
           "properties": {
@@ -287,22 +247,6 @@
           ],
           "additionalProperties": false
         },
-        {
-          "type": "object",
-          "properties": {
-            "operation": {
-              "const": "checkPermissionMatrix"
-            },
-            "input": {
-              "$ref": "#/$defs/PermissionMatrixInput"
-            }
-          },
-          "required": [
-            "operation",
-            "input"
-          ],
-          "additionalProperties": false
-        },
         {
           "type": "object",
           "properties": {
@@ -549,42 +493,6 @@
       ],
       "additionalProperties": false
     },
-    "CapabilityName": {
-      "$ref": "https://clowder-ai.dev/schemas/manifest/v0.1#/$defs/Capability"
-    },
-    "GrantPresetInput": {
-      "type": "object",
-      "properties": {
-        "presetKind": {
-          "const": "first_party"
-        },
-        "capabilities": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/CapabilityName"
-          },
-          "minItems": 1,
-          "uniqueItems": true
-        }
-      },
-      "required": [
-        "presetKind",
-        "capabilities"
-      ],
-      "additionalProperties": false
-    },
-    "RevokeGrantInput": {
-      "type": "object",
-      "properties": {
-        "capability": {
-          "$ref": "#/$defs/CapabilityName"
-        }
-      },
-      "required": [
-        "capability"
-      ],
-      "additionalProperties": false
-    },
     "OnMessageDeliveryInput": {
       "type": "object",
       "properties": {
@@ -602,48 +510,6 @@
       ],
       "additionalProperties": false
     },
-    "PermissionMatrixEntry": {
-      "type": "object",
-      "properties": {
-        "capability": {
-          "$ref": "#/$defs/CapabilityName"
-        },
-        "layer": {
-          "type": "string",
-          "enum": [
-            "L0",
-            "L1",
-            "L2"
-          ]
-        },
-        "firstPartyPreset": {
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "capability",
-        "layer",
-        "firstPartyPreset"
-      ],
-      "additionalProperties": false
-    },
-    "PermissionMatrixInput": {
-      "type": "object",
-      "properties": {
-        "entries": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/PermissionMatrixEntry"
-          },
-          "minItems": 22,
-          "maxItems": 22
-        }
-      },
-      "required": [
-        "entries"
-      ],
-      "additionalProperties": false
-    },
     "DeleteReplayEventsInput": {
       "type": "object",
       "properties": {
@@ -688,8 +554,6 @@
             "snapshot",
             "reply_preview",
             "provenance",
-            "grant_state",
-            "permission_matrix",
             "replay_events"
           ]
         },
@@ -1119,9 +983,6 @@
                 "properties": {
                   "operation": {
                     "enum": [
-                      "applyGrantPreset",
-                      "revokeGrant",
-                      "checkPermissionMatrix",
                       "deleteReplayEvents"
                     ]
                   }

package/src/schemas/manifest.schema.json

@@ -2,37 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://clowder-ai.dev/schemas/manifest/v0.1",
   "title": "Clowder AI Plugin Manifest (v0.1)",
-  "description": "Machine-readable truth source for the current static plugin.yaml access protocol: declarations, capabilities, operation row actions, runtime dataDirectory, and contribution schemas. Runtime data paths need no separate capability; attachment readers use streams.read.",
-  "x-clowder-capability-layers": {
-    "L0": [
-      "plugin.config.read",
-      "plugin.state.get",
-      "plugin.state.set"
-    ],
-    "L1": [
-      "messaging.send",
-      "schedule.register",
-      "messaging.appendElements",
-      "streams.read"
-    ],
-    "L2": [
-      "onMessage",
-      "message.event.subscribe",
-      "secret.read",
-      "thread.listMetadata",
-      "thread.readContent",
-      "thread.write",
-      "task.read",
-      "task.write",
-      "task.admitEntrusted",
-      "memory.query",
-      "memory.append",
-      "memory.retrieve",
-      "windows.create",
-      "whisper.extend",
-      "cloud.conversation.host"
-    ]
-  },
+  "description": "Machine-readable plugin declarations, configuration, runtime and contributions.",
   "x-clowder-data-class-strategies": {
     "cache": [
       "lifecycle",
@@ -123,33 +93,6 @@
         "ask-on-uninstall"
       ]
     },
-    "Capability": {
-      "type": "string",
-      "enum": [
-        "plugin.config.read",
-        "plugin.state.get",
-        "plugin.state.set",
-        "messaging.send",
-        "schedule.register",
-        "messaging.appendElements",
-        "streams.read",
-        "onMessage",
-        "message.event.subscribe",
-        "secret.read",
-        "thread.listMetadata",
-        "thread.readContent",
-        "thread.write",
-        "task.read",
-        "task.write",
-        "task.admitEntrusted",
-        "memory.query",
-        "memory.append",
-        "memory.retrieve",
-        "windows.create",
-        "whisper.extend",
-        "cloud.conversation.host"
-      ]
-    },
     "DataDeclaration": {
       "type": "object",
       "properties": {
@@ -197,7 +140,7 @@
                   "retained",
                   "ask-on-uninstall"
                 ],
-                "description": "User-visible/relationship data MUST be retained or ask-on-uninstall. lifecycle is structurally forbidden (\u94c1\u5f8b #5: user state defaults to persistent)."
+                "description": "User-visible/relationship data MUST be retained or ask-on-uninstall. lifecycle is structurally forbidden (铁律 #5: user state defaults to persistent)."
               }
             }
           }
@@ -1089,20 +1032,6 @@
       ],
       "additionalProperties": false
     },
-    "McpActionMethod": {
-      "description": "A native MCP method allowlist entry, without fixed business parameters.",
-      "type": "object",
-      "properties": {
-        "method": {
-          "type": "string",
-          "minLength": 1
-        }
-      },
-      "required": [
-        "method"
-      ],
-      "additionalProperties": false
-    },
     "McpContribution": {
       "type": "object",
       "properties": {
@@ -1116,15 +1045,6 @@
         "runtime": {
           "$ref": "#/$defs/ContributionRuntime"
         },
-        "actions": {
-          "description": "Module methods callable by this native MCP server; these do not publish direct tools.",
-          "type": "array",
-          "minItems": 1,
-          "uniqueItems": true,
-          "items": {
-            "$ref": "#/$defs/McpActionMethod"
-          }
-        },
         "environment": {
           "type": "object",
           "additionalProperties": {
@@ -1365,7 +1285,7 @@
     },
     "CloudConversationHostContribution": {
       "type": "object",
-      "description": "Declares that this package hosts one cloud conversation provider: the Host sends owner cloud-cat messages through appendMessage and pulls assistant returns through assistantReturns.list / ack. Method semantics come from the manifest only; runtime data can never introduce new methods. Error codes are data (external-process transports flatten thrown errors): NEEDS_BINDING / BOUND_CONVERSATION_MISMATCH -> needs-binding (incl. h4); HOST_UNAVAILABLE -> treated as no adapter (null); every other code (the STALE_* revisions, AMBIGUOUS_EFFECT, IDEMPOTENCY_CONFLICT, NEEDS_AUTHORIZATION, HOST_STOPPED, PAIRING_REJECTED, ...) and any unknown code -> host-append-failed. HOST_UNAVAILABLE must only describe failures before a request could have had any effect (no pairing record, missing socket, connection refused); any error after the request was written is AMBIGUOUS_EFFECT. The owning feature must be granted cloud.conversation.host; one provider accepts at most one enabled package.",
+      "description": "Declares that this package hosts one cloud conversation provider: the Host sends owner cloud-cat messages through appendMessage and pulls assistant returns through assistantReturns.list / ack. Method semantics come from the manifest only; runtime data can never introduce new methods. Error codes are data (external-process transports flatten thrown errors): NEEDS_BINDING / BOUND_CONVERSATION_MISMATCH -> needs-binding (incl. h4); HOST_UNAVAILABLE -> treated as no adapter (null); every other code (the STALE_* revisions, AMBIGUOUS_EFFECT, IDEMPOTENCY_CONFLICT, NEEDS_AUTHORIZATION, HOST_STOPPED, PAIRING_REJECTED, ...) and any unknown code -> host-append-failed. HOST_UNAVAILABLE must only describe failures before a request could have had any effect (no pairing record, missing socket, connection refused); any error after the request was written is AMBIGUOUS_EFFECT. One provider accepts at most one enabled package.",
       "properties": {
         "type": {
           "const": "cloud-conversation-host"
@@ -1778,14 +1698,6 @@
       "properties": {
         "featureEnabled": {
           "type": "boolean"
-        },
-        "requiresCapabilities": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/Capability"
-          },
-          "minItems": 1,
-          "uniqueItems": true
         }
       },
       "minProperties": 1,
@@ -1973,7 +1885,7 @@
     },
     "DesktopWindowContribution": {
       "type": "object",
-      "description": "Host-created desktop surface under its owning feature's windows.create grant. surface.integrity verifies only the entry HTML bytes. The Host must separately verify the complete installed package and serve a verified snapshot of all referenced assets. This declares no executable, Host origin, identity, or capture permission. The Host owns window execution, media/session admission and the isolated receive-only provider channel.",
+      "description": "Host-created desktop surface owned by its declared feature. surface.integrity verifies only the entry HTML bytes. The Host must separately verify the complete installed package and serve a verified snapshot of all referenced assets. This declares no executable, Host origin, identity, or capture permission. The Host owns window execution, media/session admission and the isolated receive-only provider channel.",
       "properties": {
         "type": {
           "const": "desktop-window"
@@ -2211,20 +2123,12 @@
           "items": {
             "$ref": "#/$defs/ContributionReference"
           }
-        },
-        "capabilities": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/Capability"
-          },
-          "description": "@signed(G-0 2026-07-15) \u2014 capability vocabulary is contract-versioned (P15). Adding a new capability = new contract version. Unknown strings are structurally rejected at schema level; authorization is a separate host runtime layer. Lifecycle callbacks are protocol-intrinsic baseline behavior, so they are not grantable or revocable capability IDs."
         }
       },
       "required": [
         "id",
         "name",
-        "resources",
-        "capabilities"
+        "resources"
       ],
       "additionalProperties": false
     },
@@ -2299,11 +2203,11 @@
     },
     "version": {
       "$ref": "#/$defs/SemVer",
-      "description": "Plugin version \u2014 must be valid semver (\u00a79: numeric prerelease identifiers MUST NOT have leading zeroes)."
+      "description": "Plugin version — must be valid semver (§9: numeric prerelease identifiers MUST NOT have leading zeroes)."
     },
     "contractVersion": {
       "$ref": "#/$defs/SemVer",
-      "description": "Must be an exact published semver version \u2014 no ranges, wildcards, or operator prefixes (five-step freeze: pin exact version). \u00a79: numeric prerelease identifiers MUST NOT have leading zeroes."
+      "description": "Must be an exact published semver version — no ranges, wildcards, or operator prefixes (five-step freeze: pin exact version). §9: numeric prerelease identifiers MUST NOT have leading zeroes."
     },
     "name": {
       "type": "string",

package/dist/types/capability.d.ts

@@ -1,4 +0,0 @@
-import { type AuthorizationLayer } from '../generated/contract.generated.js';
-/** Return the schema-owned authorization layer for a capability identifier. */
-export declare function getCapabilityLayer(capability: string): AuthorizationLayer | undefined;
-//# sourceMappingURL=capability.d.ts.map

package/dist/types/capability.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/types/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAE5C,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAOrF"}

package/dist/types/capability.js

@@ -1,11 +0,0 @@
-import { CAPABILITY_TABLE, } from '../generated/contract.generated.js';
-/** Return the schema-owned authorization layer for a capability identifier. */
-export function getCapabilityLayer(capability) {
-    for (const layer of Object.keys(CAPABILITY_TABLE)) {
-        if (CAPABILITY_TABLE[layer].includes(capability)) {
-            return layer;
-        }
-    }
-    return undefined;
-}
-//# sourceMappingURL=capability.js.map

package/dist/types/capability.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/types/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAEjB,MAAM,oCAAoC,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAyB,EAAE,CAAC;QAC1E,IAAK,gBAAgB,CAAC,KAAK,CAAuB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACxE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/wire/grants.d.ts

@@ -1,57 +0,0 @@
-/**
- * Grant snapshot types — GrantSnapshot for SessionBinding and host.grants.changed.
- * Mechanized verbatim from #1165 frozen shape.
- *
- * GrantSnapshot represents the effective capability set at a point in time.
- * It appears in two locations:
- *   - SessionBinding (initial grant state at handshake)
- *   - host.grants.changed notification (runtime grant mutations)
- *
- * grantRevision is strictly monotonic per plugin instance — the Host
- * increments it on every grant mutation. A plugin that observes
- * revision N may discard any notification with revision < N.
- */
-import type { Capability } from '../generated/contract.generated.js';
-/**
- * Maximum number of items in effectiveGrants.
- * Derived from the signed Capability enum — a plugin cannot hold
- * more capabilities than exist.
- */
-export declare const MAX_GRANT_ITEMS: 28;
-/**
- * GrantSnapshot captures a versioned capability set.
- *
- * Used in SessionBinding (handshake) and host.grants.changed (notification).
- * The two fields are always paired and always travel together.
- */
-export interface GrantSnapshot {
-    /**
-     * WireUInt53(0, 9_007_199_254_740_991).
-     * Monotonically increasing per plugin instance.
-     * The Host is the sole writer; plugins observe only.
-     */
-    readonly grantRevision: number;
-    /**
-     * Unique Capability[], 0..20 items.
-     * Duplicates are a protocol violation (Host guarantees uniqueness).
-     * Empty array is valid (plugin has no capabilities).
-     */
-    readonly effectiveGrants: readonly Capability[];
-}
-/**
- * Frozen set of all valid Capability values, derived from the generated
- * L0/L1/L2 capability arrays. Used for closed-enum membership checks.
- */
-export declare const VALID_CAPABILITIES: ReadonlySet<string>;
-/**
- * Validate that effectiveGrants:
- *   1. Does not exceed MAX_GRANT_ITEMS (28).
- *   2. Contains no duplicates.
- *   3. Contains only valid Capability enum members (closed-enum check).
- *
- * Fail-closed: any unrecognized capability value returns false.
- * This is an authorization boundary — fail-open would allow
- * uncontrolled privilege escalation.
- */
-export declare function validateEffectiveGrants(grants: readonly string[]): boolean;
-//# sourceMappingURL=grants.d.ts.map

package/dist/wire/grants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/wire/grants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAWrE;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAG,EAAW,CAAC;AAM3C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,UAAU,EAAE,CAAC;CACjD;AAMD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAIjD,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAS1E"}

package/dist/wire/grants.js

@@ -1,59 +0,0 @@
-/**
- * Grant snapshot types — GrantSnapshot for SessionBinding and host.grants.changed.
- * Mechanized verbatim from #1165 frozen shape.
- *
- * GrantSnapshot represents the effective capability set at a point in time.
- * It appears in two locations:
- *   - SessionBinding (initial grant state at handshake)
- *   - host.grants.changed notification (runtime grant mutations)
- *
- * grantRevision is strictly monotonic per plugin instance — the Host
- * increments it on every grant mutation. A plugin that observes
- * revision N may discard any notification with revision < N.
- */
-import { L0_CAPABILITIES, L1_CAPABILITIES, L2_CAPABILITIES, } from '../generated/contract.generated.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/**
- * Maximum number of items in effectiveGrants.
- * Derived from the signed Capability enum — a plugin cannot hold
- * more capabilities than exist.
- */
-export const MAX_GRANT_ITEMS = 28;
-// ---------------------------------------------------------------------------
-// Validators
-// ---------------------------------------------------------------------------
-/**
- * Frozen set of all valid Capability values, derived from the generated
- * L0/L1/L2 capability arrays. Used for closed-enum membership checks.
- */
-export const VALID_CAPABILITIES = new Set([
-    ...L0_CAPABILITIES,
-    ...L1_CAPABILITIES,
-    ...L2_CAPABILITIES,
-]);
-/**
- * Validate that effectiveGrants:
- *   1. Does not exceed MAX_GRANT_ITEMS (28).
- *   2. Contains no duplicates.
- *   3. Contains only valid Capability enum members (closed-enum check).
- *
- * Fail-closed: any unrecognized capability value returns false.
- * This is an authorization boundary — fail-open would allow
- * uncontrolled privilege escalation.
- */
-export function validateEffectiveGrants(grants) {
-    if (grants.length > MAX_GRANT_ITEMS)
-        return false;
-    const seen = new Set();
-    for (const g of grants) {
-        if (!VALID_CAPABILITIES.has(g))
-            return false; // unknown capability
-        if (seen.has(g))
-            return false; // duplicate
-        seen.add(g);
-    }
-    return true;
-}
-//# sourceMappingURL=grants.js.map

package/dist/wire/grants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/wire/grants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,oCAAoC,CAAC;AAE5C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAAW,CAAC;AA2B3C,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAS;IACrE,GAAG,eAAe;IAClB,GAAG,eAAe;IAClB,GAAG,eAAe;CACnB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB;IAC/D,IAAI,MAAM,CAAC,MAAM,GAAG,eAAe;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,qBAAqB;QACnE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAgB,YAAY;QAC1D,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/fixtures/manifest/invalid/unknown-capability.json

@@ -1,19 +0,0 @@
-{
-  "pluginId": "dev.clowder.fixture.unknown-capability",
-  "version": "0.1.0",
-  "contractVersion": "0.1.0",
-  "name": "Unknown capability fixture",
-  "features": [
-    {
-      "id": "escape",
-      "name": "Escape",
-      "resources": [],
-      "capabilities": [
-        "host.unrestricted"
-      ]
-    }
-  ],
-  "runtime": {
-    "transport": "builtin"
-  }
-}