@mhome/plugin-protocol 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) MHOME AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# mhome-plugin-api
+
+Typed, transport-neutral wire contracts for controlling mHome Plugins.
+
+The crate owns the common control/runtime envelopes, the reusable settings protocol, and the
+public request contracts for built-in Plugin types. It deliberately contains no transport,
+dispatch, authorization, persistence, runtime lifecycle, or Plugin implementation logic.
+
+The LLM v1 contract also owns the runtime target prefix, resumable custom-model import control
+routes, snapshots, upload grant, chunk acknowledgement, and LAN HTTP upload path prefix.
+File-system paths are intentionally absent from the Node-facing contract: a client-side service
+reads the local artifact and transfers only its bytes and public metadata.
+
+Cargo package versions and wire contract versions are independent. Each built-in Plugin contract
+declares its own wire version so that one Plugin can evolve without forcing unrelated Plugins to
+change version.
+
+`contract/node-protocol-v1.json` is the language-neutral v1 manifest used by Rust and browser
+adapters. Consumers vendor the exact manifest as a pinned build dependency and verify their
+generated constants or serialized wire shapes in tests. During pre-release development, v1 is
+replaced in lockstep across all consumers; after the protocol is released, incompatible changes
+require a new manifest version. The backend-status entries describe the common transport envelope
+consumed alongside Plugin control, but ownership of its Rust runtime model remains in Baycat
+`service-api`.

package/contract/node-protocol-v1.json

@@ -0,0 +1,72 @@
+{
+  "manifest": "mhome.node.protocol.v1",
+  "pluginApi": {
+    "version": "v1",
+    "controlTargetPrefix": "/app/plugin/control",
+    "controlRequestFields": ["pluginId", "version", "payload"],
+    "controlResponseFields": ["pluginId", "pluginType", "version", "data"],
+    "settingsChangedTarget": "/plugin/settings/changed",
+    "settingsChangedEventFields": [
+      "version",
+      "pluginId",
+      "pluginType",
+      "eventSeq",
+      "section",
+      "revision"
+    ]
+  },
+  "llm": {
+    "version": "v1",
+    "runtimeTargetPrefix": "/llm/app/",
+    "routes": {
+      "modelImportStart": "model/import/start",
+      "modelImportStatus": "model/import/status",
+      "modelImportFinalize": "model/import/finalize",
+      "modelImportCancel": "model/import/cancel"
+    },
+    "modelImportUploadPathPrefix": "/llm/model/import/upload",
+    "modelImportUploadHeaders": {
+      "authorization": "authorization",
+      "offset": "x-upload-offset",
+      "chunkSha256": "x-chunk-sha256"
+    },
+    "modelImportStartRequestFields": [
+      "displayName",
+      "fileName",
+      "artifactSha256",
+      "sizeBytes",
+      "idempotencyKey"
+    ],
+    "modelImportOperationRequestFields": ["operationId"],
+    "modelImportChunkResponseFields": [
+      "ok",
+      "operationId",
+      "receivedBytes",
+      "reason",
+      "detail"
+    ]
+  },
+  "backendStatus": {
+    "nodeContract": "baycat.node.status.v1",
+    "contract": "baycat.backend.status.v1",
+    "queryTarget": "/backend/status",
+    "changedTarget": "/backend/status/changed",
+    "resourceEnvelopeFields": [
+      "contract",
+      "scopeId",
+      "hubGeneration",
+      "hubRevision",
+      "observedAtMs",
+      "resource",
+      "deleted",
+      "snapshot"
+    ],
+    "resourceTypes": [
+      "nodeInstance",
+      "nodeRuntime",
+      "managedService",
+      "hubConnection",
+      "scopeConnection"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mhome/plugin-protocol",
+  "version": "0.2.0",
+  "description": "Build-time protocol artifacts for mhome.plugin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhome-ai/foundation.git",
+    "directory": "crates/plugin-api"
+  },
+  "homepage": "https://github.com/mhome-ai/foundation#readme",
+  "bugs": {
+    "url": "https://github.com/mhome-ai/foundation/issues"
+  },
+  "keywords": [
+    "mhome",
+    "protocol",
+    "json-schema",
+    "fixtures"
+  ],
+  "private": false,
+  "files": [
+    "protocol.json",
+    "manifest",
+    "contract",
+    "schema",
+    "fixtures",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./protocol.json": "./protocol.json",
+    "./manifest/*": "./manifest/*",
+    "./contract/*": "./contract/*",
+    "./schema/*": "./schema/*",
+    "./fixtures/*": "./fixtures/*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/protocol.json

@@ -0,0 +1,7 @@
+{
+  "protocol": "mhome.plugin",
+  "contractVersion": "0.2.0",
+  "manifest": "contract/node-protocol-v1.json",
+  "schemas": {},
+  "fixtures": {}
+}