@mhome/app-facade-protocol 1.83.0 → 1.85.0

package/contract/host-provisioning-v1.md

@@ -75,11 +75,17 @@ Fallback characteristic UUIDs: the standard endpoints as for pods, `host-info`
     "productId": "camera",
     "firmwareVersion": "0.9.0",
     "fingerprint": "<hex SHA-256 of the bootstrap public key>",
-    "wifiConfigured": false
+    "wifiConfigured": false,
+    "onboardingRequired": true,
+    "networkOnline": false
   }
   ```
 
-  `productId` is optional.
+  `productId` is optional. `onboardingRequired` reports whether this Host still
+  awaits its first claim. `networkOnline` reports current LAN readiness. Both
+  are optional for older Hosts. A securely paired Host with `networkOnline: true`
+  and `onboardingRequired: true` can finish without resubmitting Wi-Fi. `finish` issues a fresh first-claim token after checking authoritative
+  Host ownership. Already claimed Hosts never issue a new first-claim token.
 - `{"op":"finish"}` → `{"ok":true,"claimToken":"…"}`. After a successful join
   during first provisioning the response carries the claim token: 32 random
   bytes as 43 unpadded base64url characters. It is created when the join
@@ -120,17 +126,26 @@ Candidates come from the shared discovery (`/local/pod/discovery/*`) with
 | `/local/host/provision/wifi` | `{"sessionId","ssid","password"?}` | session snapshot |
 | `/local/host/provision/wifi/scan` | `{"sessionId"}` | session snapshot |
 | `/local/host/provision/status` | `{}` | `{"session": snapshot or null}` |
+| `/local/host/provision/cancel` | `{"sessionId"}` | session snapshot |
 
 Event `/local/host/provision/changed` carries a session snapshot. One session
 per native Client, and none while a pod session is active; discovery scanning
 pauses during either. Rejected requests use the error envelope and the stable
 `details.reason` values of `pod-commissioning-v1.md` section 7. The session is
-owned by the native core until success, failure or the session deadline.
-There is no cancellation or renewal endpoint; leaving the UI does not end it.
+owned by the native core until success, failure or the session deadline. Host
+setup is bound to the signed-in native account context, including before a Space
+exists. An account change retires the session and its claim token; status and
+queued events cannot transfer an old handoff to the new login.
+Cancellation is explicit. It transitions through `cancelling` and reaches
+`cancelled` only after the link and radio are released. Repeated cancellation
+returns the same session; a different session ID is rejected. Cancellation during
+`joining_wifi` is rejected as busy: applying Wi-Fi and handing off the first-claim
+token form a bounded critical section. Leaving the UI does not cancel a session.
+There is no renewal endpoint.
 
 Session states, in order: `connecting`, `awaiting_code`, `securing`,
 `reading_info`, `awaiting_wifi`, `joining_wifi`, `completed`; terminal `failed`,
-`timed_out`. `completed` carries `host`, the reported `addresses`
+`timed_out`, `cancelled`; transitional `cancelling`. `completed` carries `host`, the reported `addresses`
 (IPv4 only, possibly empty) and `claimToken` from the `finish` response; the
 commissioner sends `finish` (up to 3 times while the secure session lasts)
 before reporting it. `claimToken` is absent when `finish` could not be
@@ -158,6 +173,10 @@ The schema is `schema/host-provision.v1.schema.json`.
 ## 5. Host-side entry points
 
 - First provisioning starts BLE at boot when the Host has no known network.
+  BLE-capable Hosts whose authoritative local claim is still absent also restore
+  setup after restart, keeping saved Wi-Fi. Network readiness is not ownership.
+  An existing local claim, including one awaiting cloud confirmation, must never
+  reopen first-claim authority. An unreadable ownership store refuses recovery.
 - Re-provision window: opened from the Host's local interface (display settings
   or `meowhostd provision open`). Mutating local provisioning commands (`open`,
   `close`, `factory-reset`) require root or membership in the `meow-admin`

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.85.0",
   "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.85.0",
   "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,13 +1,14 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.85.0",
   "contract": "contract/host-provisioning-v1.md",
   "localTargets": [
     "/local/host/provision/start",
     "/local/host/provision/code",
     "/local/host/provision/wifi",
     "/local/host/provision/wifi/scan",
-    "/local/host/provision/status"
+    "/local/host/provision/status",
+    "/local/host/provision/cancel"
   ],
   "eventTargets": [
     "/local/host/provision/changed"

package/manifest/hub-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.hub.targets.v1",
-  "contractVersion": "1.83.0",
+  "contractVersion": "1.85.0",
   "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.85.0",
   "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.85.0",
   "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.85.0",
   "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.85.0",
   "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.85.0",
   "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/host-provision.v1.schema.json

@@ -16,6 +16,8 @@
         "reading_info",
         "awaiting_wifi",
         "joining_wifi",
+        "cancelling",
+        "cancelled",
         "completed",
         "failed",
         "timed_out"

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"
+    }
+  ]
+}