@mhome/app-facade-protocol 1.72.0 → 1.82.1

package/README.md

@@ -20,6 +20,9 @@ identity. Core-to-Node routes and provider runtime models belong to
 See [resource definition, observation, history and relationship reads](contract/resource-read-v1.md)
 for shared business reads and the separate UI rendering boundary.
 
+See [Agent LLM settings](contract/agent-llm-v1.md) for active-mode reads,
+independent saved configuration and Provider Operation boundaries.
+
 ## Business DTO ownership
 
 A Facade owns the public business DTO for an operation. Native Agent tools, MCP,
@@ -238,9 +241,12 @@ Business operation permissions are declared once in [the authorization manifest]
 
 ## Matter management reads
 
-`/app/matter/device/list` is the management inventory, grouped by Fabric node. It is distinct from the Plugin's Integration enumeration `/matter/device/list`. Its `sourceDeviceId` values identify Plugin projections, not Twin entities. Nodes without projected devices remain visible; `membershipComplete`, `inventoryComplete`, per-node completeness and `errors` describe partial observations. Lists omit endpoints and attribute payloads.
-
-`/app/matter/fabric/node/detail` accepts 1–20 unique `matterNodeIds`, returning an ordered item result or error for each ID. The request uses string IDs without numeric coercion. See `schema/matter-management.v1.schema.json`. All `/app/matter/` operations execute through the Space's Hub irrespective of scope execution mode. Node removal is a manual UI/CLI capability, not a delegated Agent/MCP tool.
+Matter management uses the generic `/app/plugin/matter/*` transport with an exact
+Space-bound `nodeId`, `version`, and Plugin-owned `payload`. The former
+`/app/matter/*` Facade is retired. The business contract is owned by the Integration repository at
+`plugins/matter/contract.json`. Consumers pin plain JSON snapshots; Foundation
+contains only the generic transport contract. Binding/offline observations come from
+`/app/plugin/enabled/list`, independently of the runtime's status.
 
 UI Integration metadata uses `/app/integration/presentation/get`; see
 [the presentation contract](contract/integration-presentation-v1.md).

package/contract/client-screenshot-v1.md

@@ -0,0 +1,29 @@
+# Native app screenshot support
+
+`/app/client/screenshot/report` accepts `{ "supported": boolean }` and returns
+an empty business object in the standard Facade response. It reports only the
+calling authenticated app connection, in its current Space; caller identity is
+never supplied in the input. Agent, CLI and service callers cannot report for a
+client. Authorization is Space read plus an authenticated, live client binding.
+
+Support is ephemeral connection metadata, reset on reconnect. A positive report
+receives a server-derived 90-second expiry. A visible, ready UI renews every
+30 seconds and withdraws on hide or detach; ordinary socket heartbeats do not
+renew this support lease. An expired report is unavailable even if its daemon
+remains connected. Native clients
+report true only after their installed WebView bridge confirms viewport capture
+support. Web/PWA, messaging and headless clients never report true. Reporting
+support grants no permission to capture; `basic.app.command.getScreenshot` uses
+normal capability authorization and must independently resolve one live client.
+
+The command captures the visible MeowLink WebView viewport, including app-owned
+web overlays. It requires the foreground app to display the requested Space.
+It must recheck the session and Space revision around capture and storage, and
+must not bring the app to the foreground or return an older image on failure.
+Native platform overlays, OS UI, other windows and offscreen page content are
+outside the capture. Hardware media composition depends on the platform WebView.
+
+The client stores an image through `/app/artifact/put` (at most 1 MiB decoded),
+and returns `{ screenshot: { uri }, capturedAt: { _type: "Timestamp", value } }`.
+Timestamp value is Unix epoch milliseconds, matching the runtime value codec.
+The command's transport budget is 15 seconds; other App commands retain theirs.

package/contract/resource-read-v1.md

@@ -9,13 +9,23 @@ follow the Space execution authority on both local Core and cloud.
 
 | Target | Input | Business data |
 | --- | --- | --- |
-| `/app/device/detail/get` | `{ids}` | Existing ordered `items` with `device` definitions, capabilities, group membership, enabled/source metadata; no online or state fields |
+| `/app/device/detail/get` | `{ids}` | Existing ordered `items` with `device` definitions, capabilities, group membership, physical Twin enablement or Group application state, source metadata; no online or state fields |
 | `/app/device/state/get` | `{ids}` | Ordered `items` with `resource: {entityId, online?, onlineUpdatedAtSec?, latest}` |
+| `/app/widget/list` | `{}` | Summaries: id, name, description, type, tag; Data adds dataType/repeated. No list mode or full-definition catalog |
 | `/app/widget/detail/get` | `{ids}` | Existing ordered `items` with `widget` configuration; no value, next or nextTimestamp |
 | `/app/widget/value/get` | `{ids}` | Ordered `items` with `resource: {widgetId, revision, value, next?, nextTimestamp?}` |
 | `/app/automation/status` | `{ids}` | Ordered `items` with `resource: {automationId, enabled, runnable, running, blocked, lastRunAt}` |
 | `/app/graph/relations/get` | `{resource: {kind, id}}` | `{resource, relations: [{from, relation, to, capabilityIds?}]}` |
 
+Device list and detail discriminate status using `group`: physical Devices (`false`)
+always include boolean `active` and omit `applyState`; Groups (`true`) always include
+`applyState` (`applying`, `ready`, `failed`, `deleting`) and omit `active`. Both Full
+and Essential preserve these fields. `active` describes physical Twin enablement,
+not on/off or reachability. Group state comes from its stored definition, never a
+Twin lookup; `ready` confirms application, not member reachability. Group diagnostics
+and application errors are available through Group detail. Device enable/disable
+accepts physical IDs only. This does not add Group enablement or alter lifecycle writes.
+
 Observation batches accept 1–100 IDs, reject blanks, trim and deduplicate preserving
 request order. Every normalized ID gets `{requestedId, found, resource?}`; missing
 resources have `found: false, reason: "not_found"`. A known Device with no observations
@@ -73,3 +83,14 @@ Generated Twin program inspection retains its internal `/automation/get`,
 `/automation/status` and `/automation/info` UI readers. These IDs are not accepted
 by the shared user-program Automation detail/status contract. User program detail
 pages use the shared definition, status and graph readers.
+
+## Widget presentation
+
+Widget detail uses an explicit public definition DTO on Core and cloud, including
+revision and a boolean repeated flag. It excludes runtime value/next/nextTimestamp.
+Essential omits displayName/global/baseId/steps/stepUnits; editable constraints,
+options and complete Circadian schedules remain. Full preserves the full definition DTO.
+History timestamps are epoch seconds; nextTimestamp and explicitly typed Timestamp
+values are epoch milliseconds in Full. Essential presents these dates in the Home
+IANA timezone, with UTC fallback for missing/invalid timezone configuration. Numeric
+values, Duration values and schedule wall-clock times are not inferred to be dates.

package/fixtures/agent-llm.conformance.json

@@ -0,0 +1,340 @@
+{
+  "valid": [
+    {
+      "type": "ListProvidersInput",
+      "value": {}
+    },
+    {
+      "type": "ListProvidersInput",
+      "value": {
+        "llmMode": "local"
+      }
+    },
+    {
+      "type": "GetProviderInput",
+      "value": {
+        "llmMode": "local",
+        "provider": "local_example"
+      }
+    },
+    {
+      "type": "ProviderList",
+      "value": {
+        "llmMode": "cloud",
+        "providers": [
+          {
+            "provider": "cloud_example",
+            "displayName": "Example",
+            "runtime": "cloud",
+            "modelSource": "catalog",
+            "authKind": "none",
+            "useCases": [
+              "chat"
+            ],
+            "allowedAgentModes": {
+              "chat": [
+                "cloud"
+              ]
+            },
+            "providerMetadata": null,
+            "configuration": null
+          }
+        ],
+        "providerModels": [
+          {
+            "provider": "cloud_example",
+            "models": [
+              {
+                "id": "chat-example",
+                "displayName": "Example Chat",
+                "modelType": "llm",
+                "available": true,
+                "deprecated": false,
+                "successor": null,
+                "supportsTools": true,
+                "supportsVision": false,
+                "contextWindowTokens": 128000,
+                "inputModalities": [
+                  "text"
+                ],
+                "outputModalities": [
+                  "text"
+                ],
+                "chatConfig": {
+                  "temperatureDefault": null
+                },
+                "generationControls": {
+                  "temperature": false,
+                  "thinking": false,
+                  "fastMode": false
+                },
+                "metadata": null
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "ProviderList",
+      "value": {
+        "llmMode": "local",
+        "providers": [
+          {
+            "provider": "local_example",
+            "displayName": "Example",
+            "runtime": "local",
+            "modelSource": "catalog",
+            "authKind": "api_key",
+            "useCases": [
+              "chat"
+            ],
+            "allowedAgentModes": {
+              "chat": [
+                "local"
+              ]
+            },
+            "providerMetadata": null,
+            "configuration": {
+              "requiresCredential": true,
+              "hasCredential": true,
+              "ready": false,
+              "status": "unavailable",
+              "statusLabel": "Unavailable",
+              "reason": "Retry discovery",
+              "nodeType": null,
+              "nodeBound": null,
+              "nodeOnline": null,
+              "accountId": null,
+              "expiresAtMs": null,
+              "metadata": {
+                "region": "example",
+                "credentialProfile": null,
+                "workspaceId": null
+              },
+              "supportedUseCases": [],
+              "readinessByUseCase": {
+                "chat": {
+                  "ready": false,
+                  "modelCount": 0,
+                  "reason": "Retry discovery"
+                }
+              }
+            }
+          }
+        ],
+        "providerModels": [
+          {
+            "provider": "local_example",
+            "models": []
+          }
+        ]
+      }
+    },
+    {
+      "type": "Summary",
+      "value": {
+        "llmMode": "cloud",
+        "providers": [
+          {
+            "provider": "cloud_example",
+            "displayName": "Example",
+            "runtime": "cloud",
+            "modelSource": "catalog",
+            "authKind": "none",
+            "useCases": [
+              "chat"
+            ],
+            "allowedAgentModes": {
+              "chat": [
+                "cloud"
+              ]
+            },
+            "providerMetadata": null,
+            "configuration": null
+          }
+        ],
+        "providerModels": [
+          {
+            "provider": "cloud_example",
+            "models": [
+              {
+                "id": "chat-example",
+                "displayName": "Example Chat",
+                "modelType": "llm",
+                "available": true,
+                "deprecated": false,
+                "successor": null,
+                "supportsTools": true,
+                "supportsVision": false,
+                "contextWindowTokens": 128000,
+                "inputModalities": [
+                  "text"
+                ],
+                "outputModalities": [
+                  "text"
+                ],
+                "chatConfig": {
+                  "temperatureDefault": null
+                },
+                "generationControls": {
+                  "temperature": false,
+                  "thinking": false,
+                  "fastMode": false
+                },
+                "metadata": null
+              }
+            ]
+          }
+        ],
+        "effectiveMappings": [
+          {
+            "temperature": null,
+            "reasoningEffort": null,
+            "thinking": null,
+            "fastMode": null,
+            "useCase": "chat",
+            "agentModelMode": "auto",
+            "provider": "cloud_example",
+            "model": "chat-example",
+            "source": "default",
+            "configuredModel": "chat-example"
+          }
+        ],
+        "defaultProviders": [
+          {
+            "useCase": "chat",
+            "llmMode": "cloud",
+            "provider": "cloud_example",
+            "updatedAtMs": 0
+          }
+        ],
+        "llmUseCases": [
+          {
+            "useCase": "chat",
+            "displayName": "Chat",
+            "description": null,
+            "ownerType": null,
+            "ownerId": null,
+            "executionUseCase": null,
+            "configurable": true,
+            "active": true,
+            "modes": [
+              {
+                "mode": "auto",
+                "displayName": "Auto",
+                "description": null,
+                "requirements": {
+                  "modelType": "llm",
+                  "requiredInputModalities": [
+                    "text"
+                  ],
+                  "optionalInputModalities": [],
+                  "requiredOutputModalities": [
+                    "text"
+                  ],
+                  "preferredFeatures": []
+                }
+              }
+            ],
+            "updatedAtMs": null,
+            "lastSeenAtMs": null
+          }
+        ]
+      }
+    },
+    {
+      "type": "ProviderDetail",
+      "value": {
+        "llmMode": "local",
+        "provider": {
+          "provider": "local_example",
+          "displayName": "Example",
+          "runtime": "local",
+          "modelSource": "catalog",
+          "authKind": "api_key",
+          "useCases": [
+            "chat"
+          ],
+          "allowedAgentModes": {
+            "chat": [
+              "local"
+            ]
+          },
+          "providerMetadata": null,
+          "configuration": {
+            "requiresCredential": true,
+            "hasCredential": true,
+            "ready": false,
+            "status": "unavailable",
+            "statusLabel": "Unavailable",
+            "reason": "Retry discovery",
+            "nodeType": null,
+            "nodeBound": null,
+            "nodeOnline": null,
+            "accountId": null,
+            "expiresAtMs": null,
+            "metadata": {
+              "region": "example",
+              "credentialProfile": null,
+              "workspaceId": null
+            },
+            "supportedUseCases": [],
+            "readinessByUseCase": {
+              "chat": {
+                "ready": false,
+                "modelCount": 0,
+                "reason": "Retry discovery"
+              }
+            }
+          }
+        },
+        "models": []
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "type": "ListProvidersInput",
+      "value": {
+        "llmMode": "auto"
+      }
+    },
+    {
+      "type": "GetProviderInput",
+      "value": {
+        "provider": "local_example"
+      }
+    },
+    {
+      "type": "ProviderConfiguration",
+      "value": {
+        "requiresCredential": true,
+        "hasCredential": true,
+        "ready": false,
+        "status": "unavailable",
+        "statusLabel": "Unavailable",
+        "reason": "Retry discovery",
+        "nodeType": null,
+        "nodeBound": null,
+        "nodeOnline": null,
+        "accountId": null,
+        "expiresAtMs": null,
+        "metadata": {
+          "region": "example",
+          "credentialProfile": null,
+          "workspaceId": null
+        },
+        "supportedUseCases": [],
+        "readinessByUseCase": {
+          "chat": {
+            "ready": false,
+            "modelCount": 0,
+            "reason": "Retry discovery"
+          }
+        },
+        "apiKey": "must-never-cross-boundary"
+      }
+    }
+  ]
+}

package/fixtures/authorization/decisions.json

@@ -1,6 +1,6 @@
 [
   {
-    "name": "owner:/app/device/brief/list",
+    "name": "owner:/app/device/list",
     "principal": {
       "kind": "user",
       "userId": "owner"
@@ -8,7 +8,7 @@
     "memberRole": "OWNER",
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": true
   },
   {
@@ -84,7 +84,7 @@
     "allowed": false
   },
   {
-    "name": "member:/app/device/brief/list",
+    "name": "member:/app/device/list",
     "principal": {
       "kind": "user",
       "userId": "member"
@@ -92,7 +92,7 @@
     "memberRole": "MEMBER",
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": true
   },
   {
@@ -168,7 +168,7 @@
     "allowed": false
   },
   {
-    "name": "removed:/app/device/brief/list",
+    "name": "removed:/app/device/list",
     "principal": {
       "kind": "user",
       "userId": "former"
@@ -176,7 +176,7 @@
     "memberRole": null,
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": false
   },
   {
@@ -252,7 +252,7 @@
     "allowed": false
   },
   {
-    "name": "space:/app/device/brief/list",
+    "name": "space:/app/device/list",
     "principal": {
       "kind": "space",
       "tenantId": "tenant",
@@ -261,7 +261,7 @@
     "memberRole": null,
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": true
   },
   {
@@ -343,7 +343,7 @@
     "allowed": false
   },
   {
-    "name": "space-cannot-borrow-owner:/app/device/brief/list",
+    "name": "space-cannot-borrow-owner:/app/device/list",
     "principal": {
       "kind": "space",
       "tenantId": "tenant",
@@ -352,7 +352,7 @@
     "memberRole": "OWNER",
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": true
   },
   {
@@ -434,7 +434,7 @@
     "allowed": false
   },
   {
-    "name": "foreign-space:/app/device/brief/list",
+    "name": "foreign-space:/app/device/list",
     "principal": {
       "kind": "space",
       "tenantId": "tenant",
@@ -443,7 +443,7 @@
     "memberRole": null,
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": false
   },
   {
@@ -525,7 +525,7 @@
     "allowed": false
   },
   {
-    "name": "foreign-tenant:/app/device/brief/list",
+    "name": "foreign-tenant:/app/device/list",
     "principal": {
       "kind": "space",
       "tenantId": "other",
@@ -534,7 +534,7 @@
     "memberRole": null,
     "tenantId": "tenant",
     "scopeId": "space",
-    "target": "/app/device/brief/list",
+    "target": "/app/device/list",
     "allowed": false
   },
   {