@matter/node 0.16.0-alpha.0-20250820-24939dd26 → 0.16.0-alpha.0-20250821-dd03e1003

package/src/behavior/system/network/NetworkClient.ts

@@ -27,6 +27,7 @@ export class NetworkClient extends NetworkBehavior {
             minIntervalFloor: DEFAULT_MIN_INTERVAL_FLOOR,
             maxIntervalCeiling: 0,
             attributes: [{}],
+            events: [{ isUrgent: true }],
             ...startupSubscription,
         });
 

package/src/behavior/system/parts/PartsBehavior.ts

@@ -37,7 +37,7 @@ export class PartsBehavior extends Behavior implements MutableSet<Endpoint, Endp
 
     *[Symbol.iterator]() {
         for (const part of this.endpoint.parts) {
-            yield this.context.agentFor(part);
+            yield part.agentFor(this.context);
         }
     }
 }

package/src/behavior/system/product-description/ProductDescriptionServer.ts

@@ -116,7 +116,7 @@ function inferDeviceType(agent: Agent): DeviceTypeId | undefined {
     }
 
     for (const child of agent.endpoint.parts) {
-        const deviceType = inferDeviceType(agent.context.agentFor(child));
+        const deviceType = inferDeviceType(child.agentFor(agent.context));
         if (deviceType !== undefined) {
             return deviceType;
         }

package/src/behaviors/general-commissioning/ServerNodeFailsafeContext.ts

@@ -81,7 +81,7 @@ export class ServerNodeFailsafeContext extends FailsafeContext {
             await this.#node.visit(async endpoint => {
                 const networks = this.#storedState?.networks.get(endpoint);
                 if (networks) {
-                    context.agentFor(endpoint).get(NetworkCommissioningBehavior).state.networks = [...networks];
+                    endpoint.agentFor(context).get(NetworkCommissioningBehavior).state.networks = [...networks];
                 }
             });
         });

package/src/behaviors/groups/GroupsServer.ts

@@ -67,7 +67,7 @@ export class GroupsServer extends GroupsBase {
 
     // We need to search the root here ourselves because we cannot include ServerNode because else we generate a
     // circular dependency
-    #rootEndpoint(): Endpoint<RootEndpoint> {
+    get #rootEndpoint(): Endpoint<RootEndpoint> {
         const rootEndpoint = this.endpoint.ownerOfType(RootEndpoint);
         if (rootEndpoint === undefined) {
             throw new InternalError("RootEndpoint not found");
@@ -76,7 +76,7 @@ export class GroupsServer extends GroupsBase {
     }
 
     async #actOnGroupKeyManagement<T>(act: (groupKeyManagement: GroupKeyManagementServer) => T): Promise<T> {
-        const agent = this.context.agentFor(this.#rootEndpoint());
+        const agent = this.#rootEndpoint.agentFor(this.context);
         const gkm = agent.get(GroupKeyManagementServer);
         await agent.context.transaction.addResources(gkm);
         await agent.context.transaction.begin();
@@ -122,7 +122,7 @@ export class GroupsServer extends GroupsBase {
         const fabricIndex = fabric.fabricIndex;
         const endpointNumber = this.endpoint.number;
 
-        const { groupTable } = this.#rootEndpoint().stateOf(GroupKeyManagementServer);
+        const { groupTable } = this.#rootEndpoint.stateOf(GroupKeyManagementServer);
         const groupEntry = groupTable.find(entry => entry.groupId === groupId && entry.fabricIndex === fabricIndex);
         if (groupEntry === undefined || !groupEntry.endpoints.includes(endpointNumber)) {
             return { status: StatusCode.NotFound, groupId, groupName: "" };
@@ -137,7 +137,7 @@ export class GroupsServer extends GroupsBase {
         const fabricIndex = fabric.fabricIndex;
         const endpointNumber = this.endpoint.number;
 
-        const { groupTable } = this.#rootEndpoint().stateOf(GroupKeyManagementServer);
+        const { groupTable } = this.#rootEndpoint.stateOf(GroupKeyManagementServer);
         const endpointGroups = groupTable.filter(
             entry => entry.endpoints.includes(endpointNumber) && entry.fabricIndex === fabricIndex,
         );

package/src/endpoint/Agent.ts

@@ -51,7 +51,7 @@ export class Agent {
         if (this.#endpoint.owner === undefined) {
             return undefined;
         }
-        return this.context.agentFor(this.#endpoint.owner);
+        return this.#endpoint.owner.agentFor(this.context);
     }
 
     /**

package/src/endpoint/Endpoint.ts

@@ -5,7 +5,9 @@
  */
 
 import { Behavior } from "#behavior/Behavior.js";
+import { ActionContext } from "#behavior/context/ActionContext.js";
 import { NodeActivity } from "#behavior/context/NodeActivity.js";
+import { ContextAgents } from "#behavior/context/server/ContextAgents.js";
 import { OfflineContext } from "#behavior/context/server/OfflineContext.js";
 import {
     Construction,
@@ -112,6 +114,17 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
         return this.#owner;
     }
 
+    /**
+     * Access an {@link Agent} for this endpoint.
+     *
+     * An {@link Agent} allows you to interact directly with the behaviors supported by the endpoint.  Normally you
+     * would use {@link act} to obtain an agent but {@link agentFor} is useful if you need to interact with multiple
+     * endpoints in the same context.
+     */
+    agentFor<T extends EndpointType>(this: Endpoint<T>, context: ActionContext) {
+        return ContextAgents(context).agentFor(this);
+    }
+
     get endpointProtocol() {
         if (this.#number === undefined || !this.env.has(ProtocolService)) {
             return undefined;
@@ -599,7 +612,7 @@ export class Endpoint<T extends EndpointType = EndpointType.Empty> {
         return OfflineContext.act(
             purpose,
             context => {
-                return actor(context.agentFor(this));
+                return actor(this.agentFor(context));
             },
             { activity: this.#activity },
         );

package/src/endpoint/properties/Behaviors.ts

@@ -186,7 +186,7 @@ export class Behaviors {
 
         // Initialization action.  We initialize all behaviors in the same transaction
         const initializeBehaviors = (context: ActionContext): MaybePromise => {
-            const agent = context.agentFor(this.#endpoint);
+            const agent = this.#endpoint.agentFor(context);
 
             // Activate behaviors
             //
@@ -377,7 +377,7 @@ export class Behaviors {
      */
     async close() {
         const dispose = async (context: ActionContext) => {
-            const agent = context.agentFor(this.#endpoint);
+            const agent = this.#endpoint.agentFor(context);
 
             let destroyNow = new Set(Object.keys(this.#backings));
             while (destroyNow.size) {
@@ -565,7 +565,7 @@ export class Behaviors {
         const result = OfflineContext.act(
             "behavior-late-activation",
             context => {
-                this.activate(type, context.agentFor(this.#endpoint));
+                this.activate(type, this.#endpoint.agentFor(context));
 
                 // Agent must remain active until backing is initialized
                 const backing = this.#backingFor(type);

package/src/endpoint/properties/Commands.ts

@@ -67,7 +67,7 @@ function Implementation(endpoint: Endpoint, type: Behavior.Type, name: string):
 
             // Create function to perform invocation
             function invokerFor(context: ActionContext) {
-                const agent = context.agentFor(endpoint);
+                const agent = endpoint.agentFor(context);
                 const behavior = agent.get(type);
                 const method = (behavior as unknown as Record<string, Commands.Command>)[name];
                 if (typeof method !== "function") {

package/src/node/ClientNode.ts

@@ -12,7 +12,7 @@ import { NetworkRuntime } from "#behavior/system/network/NetworkRuntime.js";
 import { Agent } from "#endpoint/Agent.js";
 import { EndpointInitializer } from "#endpoint/properties/EndpointInitializer.js";
 import { Identity, Lifecycle, MaybePromise } from "#general";
-import { Interactable } from "#protocol";
+import { Interactable, OccurrenceManager } from "#protocol";
 import { ClientNodeStore } from "#storage/client/ClientNodeStore.js";
 import { RemoteWriter } from "#storage/client/RemoteWriter.js";
 import { ServerNodeStore } from "#storage/server/ServerNodeStore.js";
@@ -41,6 +41,9 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
 
         super(opts);
 
+        // Block the OccurranceManager from parent environment so we don't attempt to record events from peers
+        this.env.block(OccurrenceManager);
+
         this.env.set(Node, this);
         this.env.set(ClientNode, this);
 

package/src/node/client/ClientBehavior.ts

@@ -75,6 +75,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
     }
 
     let { schema } = analysis;
+    let isCloned = false;
     const { extraAttrs, extraCommands } = analysis;
 
     // Obtain a ClusterType.  This provides TLV for known elements
@@ -99,8 +100,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
         .map(([k]) => k);
     if (featureNames.length) {
         // Update ClusterModel
-        schema = schema.clone();
-        schema.supportedFeatures = featureNames;
+        cloneSchema();
 
         // Update the cluster.  Note that we do not validate feature combinations.  What the device sends we work with
         cluster = new ClusterComposer(cluster, true).compose(featureNames.map(capitalize));
@@ -109,7 +109,7 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
     // If the schema does not match what the device actually returned, further augment both the ClusterModel and
     // ClusterType with unknown attributes and/or commands
     if (schema.revision !== analysis.shape.revision || extraAttrs.size || extraCommands.size) {
-        schema = schema.clone();
+        cloneSchema();
 
         cluster = {
             ...cluster,
@@ -118,8 +118,6 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
             commands: { ...cluster.commands },
         };
 
-        schema.supportedFeatures = supportedFeatures;
-
         for (const id of extraAttrs) {
             const name = createUnknownName("attr", id);
             cluster.attributes[camelize(name, false)] = Attribute(id, TlvAny);
@@ -145,6 +143,15 @@ function generateType(analysis: ShapeAnalysis, baseType: Behavior.Type): Cluster
 
     return type;
 
+    function cloneSchema() {
+        if (isCloned) {
+            return;
+        }
+        schema = schema.clone();
+        schema.supportedFeatures = featureNames;
+        isCloned = true;
+    }
+
     function implementCommand(command: ClusterType.Command) {
         return async function (this: ClusterBehavior, fields?: {}) {
             const node = this.env.get(Node) as ClientNode;

package/src/node/client/ClientEventEmitter.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ElementEvent, Events } from "#behavior/Events.js";
+import { camelize, Logger } from "#general";
+import { ClusterModel, EventModel, MatterModel } from "#model";
+import { ClientNode } from "#node/ClientNode.js";
+import { ReadResult } from "#protocol";
+import { ClusterId, EndpointNumber, EventId } from "#types";
+import { ClientStructure } from "./ClientStructure.js";
+
+const logger = Logger.get("ClientEventEmitter");
+
+/**
+ * Event handler for Matter events transmitted by a peer.
+ *
+ * TODO - set priority on context when split for server vs. client
+ * TODO - record latest event number for each subscription shape (or just wildcard?)
+ */
+export interface ClientEventEmitter {
+    (event: ReadResult.EventValue): void;
+}
+
+/**
+ * Cache of MatterModel + cluster + event ID -> event name.
+ */
+const nameCache = new WeakMap<
+    MatterModel,
+    Record<`${ClusterId}-${EventId}`, undefined | { cluster: string; event: string }>
+>();
+
+/**
+ * We warn for each cluster or cluster+event that we don't support.
+ */
+const warnedForUnknown = new Set<ClusterId | `${ClusterId}-${EventId}`>();
+
+export function ClientEventEmitter(node: ClientNode, structure: ClientStructure) {
+    return emitClientEvent;
+
+    function emitClientEvent(occurrence: ReadResult.EventValue) {
+        const names = getNames(node.matter, occurrence);
+        if (!names) {
+            return;
+        }
+
+        const event = getEvent(occurrence.path.endpointId, names.cluster, names.event);
+        if (event) {
+            node.act(agent => {
+                // Current ActionContext is not writable, could skip act() but meh, see TODO above
+                //agent.context.priority = occurrence.priority;
+                event.emit(occurrence.value, agent.context);
+            });
+        }
+    }
+
+    function getEvent(endpointId: EndpointNumber, clusterName: string, eventName: string) {
+        const endpoint = structure.endpointFor(endpointId);
+        if (endpoint === undefined) {
+            logger.error(`Received event for unsupported endpoint #${endpointId}`);
+            return;
+        }
+
+        const events = (endpoint.events as Events.Generic<ElementEvent>)[clusterName];
+        if (events === undefined) {
+            logger.error(`Received event ${eventName} for unsupported cluster ${clusterName} on ${endpoint}`);
+            return;
+        }
+
+        const event = events[eventName];
+        if (event === undefined) {
+            logger.error(`Received unsupported event ${eventName} for cluster ${clusterName} on ${endpoint}`);
+            return;
+        }
+
+        return event;
+    }
+}
+
+function getNames(matter: MatterModel, { path: { clusterId, eventId } }: ReadResult.EventValue) {
+    let matterCache = nameCache.get(matter);
+    if (matterCache === undefined) {
+        matterCache = {};
+        nameCache.set(matter, matterCache);
+    }
+
+    const key = `${clusterId}-${eventId}` as const;
+    if (key in matterCache) {
+        return matterCache[key];
+    }
+
+    const cluster = matter.get(ClusterModel, clusterId);
+    if (cluster === undefined) {
+        if (!warnedForUnknown.has(clusterId)) {
+            logger.warn(`Ignoring events for unknown cluster #${clusterId}`);
+            warnedForUnknown.add(clusterId);
+            matterCache[key] = undefined;
+        }
+        return;
+    }
+
+    const event = cluster.get(EventModel, eventId);
+    if (event === undefined) {
+        if (!warnedForUnknown.has(key)) {
+            logger.warn(`Ignoring unknown event #${eventId} for ${cluster.name} cluster`);
+            warnedForUnknown.add(key);
+            matterCache[key] = undefined;
+        }
+        return;
+    }
+
+    return (matterCache[key] = { cluster: camelize(cluster.name), event: camelize(event.name) });
+}

package/src/node/client/ClientStructure.ts

@@ -17,6 +17,7 @@ import { DatasourceCache } from "#storage/client/DatasourceCache.js";
 import { ClientNodeStore } from "#storage/index.js";
 import type { AttributeId, ClusterId, ClusterType, CommandId, DeviceTypeId, EndpointNumber } from "#types";
 import { ClientBehavior } from "./ClientBehavior.js";
+import { ClientEventEmitter } from "./ClientEventEmitter.js";
 
 const DEVICE_TYPE_LIST_ATTR_ID = DescriptorCluster.attributes.deviceTypeList.id;
 const SERVER_LIST_ATTR_ID = DescriptorCluster.attributes.serverList.id;
@@ -28,6 +29,7 @@ const PARTS_LIST_ATTR_ID = DescriptorCluster.attributes.partsList.id;
 export class ClientStructure {
     #nodeStore: ClientNodeStore;
     #endpoints: Record<EndpointNumber, EndpointStructure> = {};
+    #emitEvent: ClientEventEmitter;
 
     constructor(node: ClientNode) {
         this.#nodeStore = node.env.get(ClientNodeStore);
@@ -35,6 +37,7 @@ export class ClientStructure {
             endpoint: node,
             clusters: {},
         };
+        this.#emitEvent = ClientEventEmitter(node, this);
     }
 
     /**
@@ -76,9 +79,9 @@ export class ClientStructure {
     }
 
     /**
+     * Obtain the store for a non-cluster behavior.
      *
-     * @param request
-     * @returns
+     * The data for these behaviors is managed locally and not synced from the peer.
      */
     storeForLocal(endpoint: Endpoint, type: Behavior.Type) {
         return this.#nodeStore.storeForEndpoint(endpoint).createStoreForLocalBehavior(type.id);
@@ -132,39 +135,17 @@ export class ClientStructure {
 
         for await (const chunk of changes) {
             for (const change of chunk) {
-                if (change.kind !== "attr-value") {
-                    continue;
-                }
-
-                const { endpointId, clusterId, attributeId } = change.path;
+                switch (change.kind) {
+                    case "attr-value":
+                        currentUpdates = await this.#mutateAttribute(change, scope, currentUpdates);
+                        break;
 
-                // If we are building updates to a cluster and the cluster/endpoint changes, apply the current update
-                // set
-                if (
-                    currentUpdates &&
-                    (currentUpdates.endpointId !== endpointId || currentUpdates.clusterId !== clusterId)
-                ) {
-                    await this.#updateCluster(currentUpdates);
-                    currentUpdates = undefined;
+                    case "event-value":
+                        this.#emitEvent(change);
+                        break;
                 }
-
-                if (currentUpdates === undefined) {
-                    // Updating a new endpoint/cluster
-                    currentUpdates = {
-                        endpointId,
-                        clusterId,
-                        values: {
-                            [attributeId]: change.value,
-                        },
-                    };
-
-                    // Update version but only if this was a wildcard read
-                    if (scope.isWildcard(endpointId, clusterId)) {
-                        currentUpdates.values[DatasourceCache.VERSION_KEY] = change.version;
-                    }
-                } else {
-                    // Add value to change set for current endpoint/cluster
-                    currentUpdates.values[attributeId] = change.value;
+                if (change.kind !== "attr-value") {
+                    continue;
                 }
             }
 
@@ -176,8 +157,44 @@ export class ClientStructure {
         }
     }
 
+    async #mutateAttribute(
+        change: ReadResult.AttributeValue,
+        scope: ReadScope,
+        currentUpdates: undefined | AttributeUpdates,
+    ) {
+        const { endpointId, clusterId, attributeId } = change.path;
+
+        // If we are building updates to a cluster and the cluster/endpoint changes, apply the current update
+        // set
+        if (currentUpdates && (currentUpdates.endpointId !== endpointId || currentUpdates.clusterId !== clusterId)) {
+            await this.#updateCluster(currentUpdates);
+            currentUpdates = undefined;
+        }
+
+        if (currentUpdates === undefined) {
+            // Updating a new endpoint/cluster
+            currentUpdates = {
+                endpointId,
+                clusterId,
+                values: {
+                    [attributeId]: change.value,
+                },
+            };
+
+            // Update version but only if this was a wildcard read
+            if (scope.isWildcard(endpointId, clusterId)) {
+                currentUpdates.values[DatasourceCache.VERSION_KEY] = change.version;
+            }
+        } else {
+            // Add value to change set for current endpoint/cluster
+            currentUpdates.values[attributeId] = change.value;
+        }
+
+        return currentUpdates;
+    }
+
     /**
-     * Obtain the {@link ClusterType} for an endpoint number and cluster ID.
+     * Obtain the {@link ClusterType} for an {@link EndpointNumber} and {@link ClusterId}.
      */
     clusterFor(endpoint: EndpointNumber, cluster: ClusterId) {
         const ep = this.#endpointFor(endpoint);
@@ -188,6 +205,13 @@ export class ClientStructure {
         return this.#clusterFor(ep, cluster)?.behavior?.cluster;
     }
 
+    /**
+     * Obtain the {@link Endpoint} for a {@link EndpointNumber}.
+     */
+    endpointFor(endpoint: EndpointNumber): Endpoint | undefined {
+        return this.#endpoints[endpoint]?.endpoint;
+    }
+
     /**
      * Apply new attribute values for specific endpoint/cluster.
      *

package/src/node/server/IdentityService.ts

@@ -44,7 +44,7 @@ export class IdentityService {
             other = this.#node;
         } else {
             if (this.#partsById === undefined) {
-                this.#partsById = OfflineContext.ReadOnly.agentFor(this.#node).get(IndexBehavior).partsById;
+                this.#partsById = this.#node.agentFor(OfflineContext.ReadOnly).get(IndexBehavior).partsById;
             }
             other = this.#partsById?.[number];
         }

package/src/node/server/ProtocolService.ts

@@ -602,7 +602,7 @@ function invokeCommand(
         requestDiagnostic,
     );
 
-    const agent = context.agentFor(endpoint);
+    const agent = endpoint.agentFor(context);
     const behavior = agent.get(backing.type);
 
     let isAsync = false;