@clowder-ai/plugin-contract 0.1.0-beta.2 → 0.1.0-beta.20

package/src/schemas/manifest.schema.json

@@ -2,7 +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 plugin manifest (§3.4/§3.5). v0.1 covers core manifest + features + data classification. Signals/events (C-2) and schedule/state (C-3) are schema deltas in future contract versions.",
+  "description": "Machine-readable truth source for the static plugin.yaml access protocol (§3.4/§3.5). beta.16 adds the Host-governed desktop-window contribution. Window, media and conversation authorities remain separate Host runtime decisions; the signed broker wire is unchanged.",
   "x-clowder-capability-layers": {
     "L0": ["plugin.config.read", "plugin.state.get", "plugin.state.set"],
     "L1": ["messaging.send", "schedule.register", "events.publish", "messaging.appendElements"],
@@ -100,6 +100,476 @@
       "additionalProperties": false
     },
 
+    "ContributionReference": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["identity", "schedule", "tool", "mcp", "skill", "limb", "webhook", "message-subscription", "service", "connector", "ui", "content-editor-provider", "desktop-window"]
+        },
+        "id": { "type": "string", "minLength": 1 }
+      },
+      "required": ["type", "id"],
+      "additionalProperties": false
+    },
+
+    "PackageRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$"
+    },
+
+    "ConfigurationOption": {
+      "type": "object",
+      "properties": {
+        "value": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "hint": { "type": "string" },
+        "docsUrl": { "type": "string", "format": "uri" }
+      },
+      "required": ["value", "label"],
+      "additionalProperties": false
+    },
+
+    "ConfigurationField": {
+      "type": "object",
+      "properties": {
+        "key": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9._-]*$" },
+        "label": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "kind": { "type": "string", "enum": ["string", "secret", "select", "boolean", "number", "url"] },
+        "required": { "type": "boolean" },
+        "default": { "type": ["string", "number", "boolean"] },
+        "options": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ConfigurationOption" },
+          "minItems": 1
+        }
+      },
+      "required": ["key", "label", "kind", "required"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": { "properties": { "kind": { "const": "select" } }, "required": ["kind"] },
+          "then": { "required": ["options"] },
+          "else": { "properties": { "options": false } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "secret" } }, "required": ["kind"] },
+          "then": { "properties": { "default": false } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "boolean" } }, "required": ["kind"] },
+          "then": { "properties": { "default": { "type": "boolean" } } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "number" } }, "required": ["kind"] },
+          "then": { "properties": { "default": { "type": "number" } } }
+        },
+        {
+          "if": { "properties": { "kind": { "enum": ["string", "select"] } }, "required": ["kind"] },
+          "then": { "properties": { "default": { "type": "string" } } }
+        },
+        {
+          "if": { "properties": { "kind": { "const": "url" } }, "required": ["kind"] },
+          "then": { "properties": { "default": { "type": "string", "format": "uri" } } }
+        }
+      ]
+    },
+
+    "EnvironmentBinding": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "config" },
+            "key": { "type": "string", "minLength": 1 }
+          },
+          "required": ["source", "key"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "secret" },
+            "key": { "type": "string", "minLength": 1 }
+          },
+          "required": ["source", "key"],
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "ContributionRuntime": {
+      "type": "object",
+      "properties": {
+        "transport": { "type": "string", "enum": ["stdio", "ipc"] },
+        "entrypoint": { "$ref": "#/$defs/PackageRelativePath" },
+        "args": { "type": "array", "items": { "type": "string" } }
+      },
+      "required": ["transport", "entrypoint"],
+      "additionalProperties": false
+    },
+
+    "CallbackAction": {
+      "type": "object",
+      "properties": {
+        "method": { "type": "string", "minLength": 1 },
+        "params": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["method"],
+      "additionalProperties": false
+    },
+
+    "IdentityContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "identity" },
+        "id": { "type": "string", "minLength": 1 },
+        "displayName": { "type": "string", "minLength": 1 },
+        "icon": { "type": "string" },
+        "color": { "type": "string" }
+      },
+      "required": ["type", "id", "displayName"],
+      "additionalProperties": false
+    },
+
+    "ScheduleContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "schedule" },
+        "id": { "type": "string", "minLength": 1 },
+        "schedule": {
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": { "kind": { "const": "interval" }, "everyMs": { "type": "integer", "minimum": 1000 } },
+              "required": ["kind", "everyMs"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": { "kind": { "const": "cron" }, "expression": { "type": "string", "minLength": 1 } },
+              "required": ["kind", "expression"],
+              "additionalProperties": false
+            }
+          ]
+        },
+        "action": { "$ref": "#/$defs/CallbackAction" },
+        "policy": {
+          "type": "object",
+          "properties": {
+            "overlap": { "const": "skip" },
+            "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 86400000 }
+          },
+          "required": ["overlap", "timeoutMs"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["type", "id", "schedule", "action", "policy"],
+      "additionalProperties": false
+    },
+
+    "DirectToolContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "tool" },
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "inputSchema": { "type": "object", "additionalProperties": true },
+        "action": { "$ref": "#/$defs/CallbackAction" }
+      },
+      "required": ["type", "id", "name", "inputSchema", "action"],
+      "additionalProperties": false
+    },
+
+    "McpContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "mcp" },
+        "id": { "type": "string", "minLength": 1 },
+        "runtime": { "$ref": "#/$defs/ContributionRuntime" },
+        "environment": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/EnvironmentBinding" }
+        }
+      },
+      "required": ["type", "id", "runtime"],
+      "additionalProperties": false
+    },
+
+    "SkillContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "skill" },
+        "id": { "type": "string", "minLength": 1 },
+        "path": { "$ref": "#/$defs/PackageRelativePath" }
+      },
+      "required": ["type", "id", "path"],
+      "additionalProperties": false
+    },
+
+    "LimbContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "limb" },
+        "id": { "type": "string", "minLength": 1 },
+        "manifestPath": { "$ref": "#/$defs/PackageRelativePath" }
+      },
+      "required": ["type", "id", "manifestPath"],
+      "additionalProperties": false
+    },
+
+    "WebhookContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "webhook" },
+        "id": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(/[A-Za-z0-9][A-Za-z0-9_-]*)*$" },
+        "methods": { "type": "array", "items": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE"] }, "minItems": 1, "uniqueItems": true },
+        "action": { "$ref": "#/$defs/CallbackAction" },
+        "verificationSecretRef": { "type": "string", "minLength": 1 }
+      },
+      "required": ["type", "id", "path", "methods", "action"],
+      "additionalProperties": false
+    },
+
+    "MessageSubscriptionContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "message-subscription" },
+        "id": { "type": "string", "minLength": 1 },
+        "binding": { "type": "string", "minLength": 1 },
+        "filter": { "type": "object", "additionalProperties": true },
+        "action": { "$ref": "#/$defs/CallbackAction" }
+      },
+      "required": ["type", "id", "binding", "action"],
+      "additionalProperties": false
+    },
+
+    "ServiceContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "service" },
+        "id": { "type": "string", "minLength": 1 },
+        "runtime": { "$ref": "#/$defs/ContributionRuntime" },
+        "healthMethod": { "type": "string", "minLength": 1 },
+        "environment": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/EnvironmentBinding" }
+        }
+      },
+      "required": ["type", "id", "runtime", "healthMethod"],
+      "additionalProperties": false
+    },
+
+    "ConnectorContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "connector" },
+        "id": { "type": "string", "minLength": 1 },
+        "identityRef": { "type": "string", "minLength": 1 },
+        "inboundMethod": { "type": "string", "minLength": 1 },
+        "outboundMethod": { "type": "string", "minLength": 1 }
+      },
+      "required": ["type", "id", "identityRef", "inboundMethod", "outboundMethod"],
+      "additionalProperties": false
+    },
+
+    "UiWhenClause": {
+      "type": "object",
+      "properties": {
+        "featureEnabled": { "type": "boolean" },
+        "requiresCapabilities": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Capability" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "minProperties": 1,
+      "additionalProperties": false
+    },
+
+    "UiAnchor": {
+      "type": "object",
+      "properties": {
+        "position": { "type": "string", "enum": ["before", "after"] },
+        "target": { "type": "string", "minLength": 1 }
+      },
+      "required": ["position", "target"],
+      "additionalProperties": false
+    },
+
+    "UiCommandContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "ui" },
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "const": "command" },
+        "label": { "type": "string", "minLength": 1 },
+        "action": { "$ref": "#/$defs/CallbackAction" },
+        "when": { "$ref": "#/$defs/UiWhenClause" }
+      },
+      "required": ["type", "id", "kind", "label", "action"],
+      "additionalProperties": false
+    },
+
+    "UiSlotItemContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "ui" },
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "const": "slot-item" },
+        "label": { "type": "string", "minLength": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "group": { "type": "string", "minLength": 1 },
+        "anchor": { "$ref": "#/$defs/UiAnchor" },
+        "order": { "type": "integer", "minimum": -10000, "maximum": 10000 },
+        "when": { "$ref": "#/$defs/UiWhenClause" }
+      },
+      "required": ["type", "id", "kind", "label", "command", "group"],
+      "additionalProperties": false
+    },
+
+    "UiMessageElementContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "ui" },
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "const": "message-element" },
+        "label": { "type": "string", "minLength": 1 },
+        "elementKind": { "type": "string", "minLength": 1 },
+        "renderer": { "type": "string", "minLength": 1 },
+        "when": { "$ref": "#/$defs/UiWhenClause" }
+      },
+      "required": ["type", "id", "kind", "label", "elementKind", "renderer"],
+      "additionalProperties": false
+    },
+
+    "UiContribution": {
+      "oneOf": [
+        { "$ref": "#/$defs/UiCommandContribution" },
+        { "$ref": "#/$defs/UiSlotItemContribution" },
+        { "$ref": "#/$defs/UiMessageElementContribution" }
+      ]
+    },
+
+    "SemanticMaterializerDeclaration": {
+      "type": "object",
+      "description": "Optional independent DOCX computation. The Host admits one closed worker bundle under the installed package and live feature authority, in a fresh sandboxed private browser process with no ambient effects. This is not permission to execute package code in the Host or renderer.",
+      "properties": {
+        "executionClass": { "const": "dedicated-browser-worker" },
+        "entrypoint": { "$ref": "#/$defs/PackageRelativePath", "pattern": "\\.js$" },
+        "integrity": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/]{43}=$" },
+        "protocolVersion": { "const": "1.0.0" }
+      },
+      "required": ["executionClass", "entrypoint", "integrity", "protocolVersion"],
+      "additionalProperties": false
+    },
+
+    "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.",
+      "properties": {
+        "type": { "const": "desktop-window" },
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "role": { "const": "companion" },
+        "surface": {
+          "type": "object",
+          "properties": {
+            "entrypoint": { "$ref": "#/$defs/PackageRelativePath", "pattern": "\\.html$" },
+            "integrity": { "type": "string", "pattern": "^sha256-[A-Za-z0-9+/]{43}=$" }
+          },
+          "required": ["entrypoint", "integrity"],
+          "additionalProperties": false
+        },
+        "bridgeVersion": { "enum": ["1.0.0", "1.1.0", "1.2.0", "1.3.0"] },
+        "presentation": {
+          "type": "object",
+          "properties": {
+            "width": { "type": "integer", "minimum": 160, "maximum": 600 },
+            "height": { "type": "integer", "minimum": 160, "maximum": 1000 },
+            "transparent": { "const": true },
+            "frame": { "const": false },
+            "alwaysOnTop": { "type": "boolean" },
+            "skipTaskbar": { "type": "boolean" }
+          },
+          "required": ["width", "height", "transparent", "frame", "alwaysOnTop", "skipTaskbar"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["type", "id", "role", "surface", "bridgeVersion", "presentation"],
+      "additionalProperties": false
+    },
+
+    "ContentEditorProviderContribution": {
+      "type": "object",
+      "properties": {
+        "type": { "const": "content-editor-provider" },
+        "id": { "type": "string", "minLength": 1 },
+        "mediaTypes": {
+          "type": "array",
+          "items": {
+            "const": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+          },
+          "minItems": 1,
+          "maxItems": 1,
+          "uniqueItems": true
+        },
+        "surface": {
+          "type": "object",
+          "properties": {
+            "entrypoint": { "$ref": "#/$defs/PackageRelativePath" },
+            "integrity": {
+              "type": "string",
+              "pattern": "^sha256-[A-Za-z0-9+/]{43}=$"
+            },
+            "sandbox": {
+              "const": "dedicated-origin-iframe",
+              "description": "Host serves the renderer from an origin that has no Host cookies or Host APIs, applies sandbox=allow-scripts allow-same-origin, and sends a frame-ancestors response header restricted to the exact Host origin."
+            },
+            "navigationPolicy": {
+              "const": "navigation-api-deny",
+              "description": "The renderer must install a fail-closed Navigation API listener before upstream code and prevent every self-navigation before its request starts."
+            }
+          },
+          "required": ["entrypoint", "integrity", "sandbox", "navigationPolicy"],
+          "additionalProperties": false
+        },
+        "bridgeVersion": { "const": "1.0.0" },
+        "semanticMaterializer": { "$ref": "#/$defs/SemanticMaterializerDeclaration" },
+        "operations": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["load", "settle", "comment", "tracked-change"] },
+          "minItems": 4,
+          "maxItems": 4,
+          "uniqueItems": true
+        }
+      },
+      "required": ["type", "id", "mediaTypes", "surface", "bridgeVersion", "operations"],
+      "additionalProperties": false
+    },
+
+    "StaticContribution": {
+      "oneOf": [
+        { "$ref": "#/$defs/IdentityContribution" },
+        { "$ref": "#/$defs/ScheduleContribution" },
+        { "$ref": "#/$defs/DirectToolContribution" },
+        { "$ref": "#/$defs/McpContribution" },
+        { "$ref": "#/$defs/SkillContribution" },
+        { "$ref": "#/$defs/LimbContribution" },
+        { "$ref": "#/$defs/WebhookContribution" },
+        { "$ref": "#/$defs/MessageSubscriptionContribution" },
+        { "$ref": "#/$defs/ServiceContribution" },
+        { "$ref": "#/$defs/ConnectorContribution" },
+        { "$ref": "#/$defs/UiContribution" },
+        { "$ref": "#/$defs/ContentEditorProviderContribution" },
+        { "$ref": "#/$defs/DesktopWindowContribution" }
+      ]
+    },
+
     "PluginFeature": {
       "type": "object",
       "properties": {
@@ -109,6 +579,10 @@
           "type": "array",
           "items": { "$ref": "#/$defs/ResourceReference" }
         },
+        "contributions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ContributionReference" }
+        },
         "capabilities": {
           "type": "array",
           "items": { "$ref": "#/$defs/Capability" },
@@ -133,7 +607,7 @@
       "type": "object",
       "properties": {
         "transport": { "$ref": "#/$defs/ExternalRuntimeTransport" },
-        "entrypoint": { "type": "string", "minLength": 1 }
+        "entrypoint": { "$ref": "#/$defs/PackageRelativePath" }
       },
       "required": ["transport", "entrypoint"],
       "additionalProperties": false
@@ -169,7 +643,16 @@
       "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", "minLength": 1 },
-    "description": { "type": "string" },
+    "description": { "$ref": "https://clowder-ai.dev/schemas/plugin-metadata/v1#/$defs/LocalizedDescription" },
+    "icon": { "$ref": "https://clowder-ai.dev/schemas/plugin-metadata/v1#/$defs/PluginIcon" },
+    "configuration": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ConfigurationField" }
+    },
+    "contributions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/StaticContribution" }
+    },
     "features": {
       "type": "array",
       "items": { "$ref": "#/$defs/PluginFeature" },
@@ -179,7 +662,10 @@
       "type": "array",
       "items": { "$ref": "#/$defs/DataDeclaration" }
     },
-    "runtime": { "$ref": "#/$defs/RuntimeDeclaration" }
+    "runtime": { "$ref": "#/$defs/RuntimeDeclaration" },
+    "signals": {
+      "$ref": "https://clowder-ai.dev/schemas/signals/v0.2#/$defs/SignalContribution"
+    }
   },
   "required": ["pluginId", "version", "contractVersion", "name", "features", "runtime"],
   "additionalProperties": false