@mhome/app-facade-protocol 1.83.0 → 1.84.1

package/contract/plugin-install-v1.md

@@ -0,0 +1,46 @@
+# Plugin installation
+
+These platform-owned App operations run on the selected local Space's Hub. They
+are App-only, require a personal User with Space management access, and retain
+Host-owned authorization and identity pinning whenever Host management is needed.
+A verified available service can be commissioned without Host software-management
+permission or a Host installation receipt; it retains the existing Node admission
+and Space management checks. Agent/CLI/MCP do not acquire a new
+installation entrypoint. The shared schema describes business input and data;
+requests and responses still use the canonical App Facade envelopes.
+
+- `/app/plugin/install/prepare` accepts `{nodeType}`. It inspects Hosts reachable
+  from this Hub. It immediately returns a `preparing` session; status eventually
+  returns `prepared` with immutable per-Host actions or `failed` with an error.
+  Cardinality is unresolved (`null`) while preparing and selection is disabled.
+  `single` permits one selected Host; `multiple` permits one or more. An existing
+  single binding prevents another add. Unsupported or unknown observations are
+  ineligible, not treated as missing software. Compatible installed services are
+  reused without an implicit update or repair. Starting a stopped service is
+  explicit in the action shown to the User. Prepare never starts service work.
+- `/app/plugin/install/start` accepts `{sessionId,hostIds}` and submits once.
+  Repeated identical submission returns the existing session, including failure;
+  a different selection for a submitted ID is rejected. Plans expire; no silent
+  replanning occurs. Each Host independently installs if necessary, waits for the
+  exact service and release, then commissions into this Space. Failure stops that
+  Host's dependent stages. Other selected Hosts continue. Commissioning waits for
+  the existing Space mutation lock before one attempt.
+- `/app/plugin/install/status` accepts `{sessionId}` and reads the originating
+  User/tenant/Space session. It never executes or retries a stage. `running` is
+  acceptance/progress, not success. All selected targets must succeed for
+  `succeeded`; mixed success/failure is `partiallySucceeded`, zero success is
+  `failed`, and any unconfirmed target makes the overall state `unknown`.
+
+Each Host retains separate installation, readiness and commissioning outcomes,
+with errors and submitted task/session references. `notRequired` means the path
+omits a stage; `notRun` means its prerequisite failed or execution was interrupted.
+A service installed before commissioning failed remains installed. No rollback,
+automatic retry, retry endpoint, or automatic resumption is provided. Polling an
+existing task after a lost response is observation, never a repeated write. A Core
+restart records interrupted work and preserves completed facts; it never restarts
+installation/commissioning. Existing provisional-credential cleanup is retained.
+Host tasks already accepted may continue independently; interruption is not proof
+that installation failed. Warnings are preserved even when targets succeed.
+
+Results omit credentials, signing evidence and private execution plans. Completion
+of this operation does not force device/account/model setup.

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",
@@ -54,13 +54,18 @@
         "/app/plugin/enable/start",
         "/app/plugin/enable/status",
         "/app/plugin/disable",
-        "/app/plugin/profile/update"
+        "/app/plugin/profile/update",
+        "/app/plugin/install/prepare",
+        "/app/plugin/install/start",
+        "/app/plugin/install/status"
       ],
       "eventTargets": [
         "/app/plugin/settings/changed"
       ],
       "extensionFamily": "/app/plugin/{nodeType}/{route...}",
-      "extensionPriority": "after_exact"
+      "extensionPriority": "after_exact",
+      "installSchema": "schema/plugin-install.v1.schema.json",
+      "installContract": "contract/plugin-install-v1.md"
     },
     "runtime": {
       "contract": "mhome.runtime.status.v1",

package/manifest/authorization.v1.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "operations": {
     "/app/agent/context/get": "spaceRead",
     "/app/agent/credit/usage": "spaceRead",
@@ -196,6 +196,9 @@
     "/app/plugin/disable": "spaceManage",
     "/app/plugin/enable/start": "spaceManage",
     "/app/plugin/enable/status": "spaceManage",
+    "/app/plugin/install/prepare": "spaceManage",
+    "/app/plugin/install/start": "spaceManage",
+    "/app/plugin/install/status": "spaceManage",
     "/app/plugin/enabled/list": "spaceRead",
     "/app/plugin/profile/update": "spaceManage",
     "/app/pod/enrollment/get": "userRead",

package/manifest/host-provision-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "contract": "contract/host-provisioning-v1.md",
   "localTargets": [
     "/local/host/provision/start",

package/manifest/hub-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.hub.targets.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "appTargets": [
     "/app/hub/get",
     "/app/hub/remove",

package/manifest/pod-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.pod.targets.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "contract": "contract/pod-commissioning-v1.md",
   "localTargets": [
     "/local/pod/discovery/start",

package/manifest/routing.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.routing.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "targetPrefix": "/app/",
   "default": {
     "execution": "scopeMode"

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "requestTargets": [
     "/app/messaging/provider/list",
     "/app/messaging/provider-account/list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/app-facade-protocol",
-  "version": "1.83.0",
+  "version": "1.84.1",
   "description": "Build-time protocol artifacts for mhome.app-facade",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,8 +1,9 @@
 {
   "protocol": "mhome.app-facade",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.84.1",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
+    "pluginInstall": "schema/plugin-install.v1.schema.json",
     "hostAuthorization": "schema/host-authorization.v1.schema.json",
     "hostAccess": "schema/host-access.v1.schema.json",
     "agentLlm": "schema/agent-llm.v1.schema.json",

package/schema/plugin-install.v1.schema.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.mhome.ai/app-facade/plugin-install.v1.schema.json",
+  "$defs": {
+    "prepare": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "nodeType"
+      ],
+      "properties": {
+        "nodeType": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "start": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sessionId",
+        "hostIds"
+      ],
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hostIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true
+        }
+      }
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sessionId"
+      ],
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "state"
+      ],
+      "properties": {
+        "state": {
+          "enum": [
+            "pending",
+            "running",
+            "succeeded",
+            "failed",
+            "notRequired",
+            "notRun",
+            "unknown"
+          ]
+        },
+        "error": {
+          "type": "string"
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "hostId",
+        "hostName",
+        "action",
+        "eligible",
+        "reason",
+        "selected",
+        "state",
+        "installed",
+        "expectedVersion",
+        "installation",
+        "readiness",
+        "commissioning",
+        "operationId",
+        "enableSessionId",
+        "nodeId",
+        "warnings"
+      ],
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hostName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "action": {
+          "enum": [
+            "unavailable",
+            "alreadyAdded",
+            "add",
+            "startAndAdd",
+            "installAndAdd"
+          ]
+        },
+        "eligible": {
+          "type": "boolean"
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "selected": {
+          "type": "boolean"
+        },
+        "state": {
+          "enum": [
+            "pending",
+            "running",
+            "succeeded",
+            "failed",
+            "unknown"
+          ]
+        },
+        "installed": {
+          "type": "boolean"
+        },
+        "expectedVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "installation": {
+          "$ref": "#/$defs/stage"
+        },
+        "readiness": {
+          "$ref": "#/$defs/stage"
+        },
+        "commissioning": {
+          "$ref": "#/$defs/stage"
+        },
+        "operationId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "enableSessionId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "nodeId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "contract",
+        "sessionId",
+        "spaceId",
+        "nodeType",
+        "pluginName",
+        "bindingCardinality",
+        "state",
+        "revision",
+        "expiresAtMs",
+        "hosts",
+        "warnings",
+        "error"
+      ],
+      "properties": {
+        "contract": {
+          "const": "mhome.plugin.install.v1"
+        },
+        "sessionId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "spaceId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "nodeType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pluginName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "bindingCardinality": {
+          "enum": [
+            "single",
+            "multiple",
+            null
+          ]
+        },
+        "state": {
+          "enum": [
+            "preparing",
+            "prepared",
+            "running",
+            "succeeded",
+            "partiallySucceeded",
+            "failed",
+            "unknown"
+          ]
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "expiresAtMs": {
+          "type": "integer"
+        },
+        "hosts": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/target"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "$ref": "#/$defs/prepare"
+    },
+    {
+      "$ref": "#/$defs/start"
+    },
+    {
+      "$ref": "#/$defs/status"
+    },
+    {
+      "$ref": "#/$defs/response"
+    }
+  ]
+}