@matter/node 0.16.0-alpha.0-20250819-0a388db8b → 0.16.0-alpha.0-20250821-dd03e1003

package/src/behavior/context/server/OfflineContext.ts

@@ -5,15 +5,12 @@
  */
 
 import type { Agent } from "#endpoint/Agent.js";
-import type { Endpoint } from "#endpoint/Endpoint.js";
-import type { EndpointType } from "#endpoint/type/EndpointType.js";
 import { Diagnostic, InternalError, MaybePromise, Transaction } from "#general";
 import { AccessLevel } from "#model";
 import { AccessControl } from "#protocol";
 import type { ActionContext } from "../ActionContext.js";
 import { Contextual } from "../Contextual.js";
 import type { NodeActivity } from "../NodeActivity.js";
-import { ContextAgents } from "./ContextAgents.js";
 
 export let nextInternalId = 1;
 
@@ -70,7 +67,6 @@ export const OfflineContext = {
 
         try {
             frame = options?.activity?.begin(via);
-            let agents: undefined | ContextAgents;
 
             transaction = Transaction.open(via, options?.isolation);
 
@@ -94,13 +90,6 @@ export const OfflineContext = {
                         : AccessControl.Authority.Unauthorized;
                 },
 
-                agentFor<const T extends EndpointType>(endpoint: Endpoint<T>): Agent.Instance<T> {
-                    if (!agents) {
-                        agents = ContextAgents(context);
-                    }
-                    return agents?.agentFor(endpoint);
-                },
-
                 get [Contextual.context]() {
                     return this;
                 },

package/src/behavior/context/server/OnlineContext.ts

@@ -4,9 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Agent } from "#endpoint/Agent.js";
-import { Endpoint } from "#endpoint/Endpoint.js";
-import { EndpointType } from "#endpoint/type/EndpointType.js";
 import { AsyncObservable, Diagnostic, ImplementationError, InternalError, MaybePromise, Transaction } from "#general";
 import { AccessLevel } from "#model";
 import type { Node } from "#node/Node.js";
@@ -23,7 +20,6 @@ import { FabricIndex, NodeId } from "#types";
 import { ActionContext } from "../ActionContext.js";
 import { Contextual } from "../Contextual.js";
 import { NodeActivity } from "../NodeActivity.js";
-import { ContextAgents } from "./ContextAgents.js";
 
 /**
  * Caches completion events per exchange. Uses if multiple OnlineContext instances are created for an exchange.
@@ -150,7 +146,6 @@ export function OnlineContext(options: OnlineContext.Options) {
         if (session) {
             SecureSession.assert(session);
         }
-        let agents: undefined | ContextAgents;
         let interactionComplete: AsyncObservable<[session?: ActionContext | undefined]> | undefined;
         if (exchange !== undefined) {
             interactionComplete = exchangeCompleteEvents.get(exchange);
@@ -211,13 +206,6 @@ export function OnlineContext(options: OnlineContext.Options) {
                     : AccessControl.Authority.Unauthorized;
             },
 
-            agentFor<T extends EndpointType>(endpoint: Endpoint<T>): Agent.Instance<T> {
-                if (!agents) {
-                    agents = ContextAgents(context);
-                }
-                return agents.agentFor(endpoint);
-            },
-
             get [Contextual.context](): ActionContext {
                 return this;
             },

package/src/behavior/internal/Reactors.ts

@@ -411,7 +411,7 @@ class ReactorBacking<T extends any[], R> {
      * Bind the reactor to a behavior instance once locks are held.
      */
     #bindReactor(context: ActionContext, backing: BehaviorBacking): Reactor<T, Awaited<R>> {
-        const agent = context.agentFor(this.#endpoint);
+        const agent = this.#endpoint.agentFor(context);
 
         // Do not use Agent.get because it will throw during initialization
         const behavior = backing.createBehavior(agent, backing.type);

package/src/behavior/system/commissioning/CommissioningClient.ts

@@ -217,65 +217,67 @@ export class CommissioningClient extends Behavior {
     /**
      * Define logical schema.  This enables runtime validation, make fields persistent and makes subfields editable.
      */
-    static override readonly schema = new DatatypeModel({
-        name: "CommissioningState",
-        type: "struct",
-
-        children: [
-            FieldElement({
-                name: "peerAddress",
-                type: "struct",
-                quality: "N",
-                children: [
-                    FieldElement({ name: "fabricIndex", type: "fabric-id" }),
-                    FieldElement({ name: "nodeId", type: "node-id" }),
-                ],
-            }),
-            FieldElement({
-                name: "addresses",
-                type: "list",
-                quality: "N",
-                children: [
-                    FieldElement({
-                        name: "entry",
-                        type: "struct",
-                        children: [
-                            FieldElement({ name: "type", type: "string" }),
-                            FieldElement({ name: "ip", type: "string" }),
-                            FieldElement({ name: "port", type: "uint16" }),
-                            FieldElement({ name: "peripheralAddress", type: "string" }),
-                        ],
-                    }),
-                ],
-            }),
-            FieldElement({ name: "discoveredAt", type: "systime-ms", quality: "N", conformance: "M" }),
-            FieldElement({ name: "onlineAt", type: "systime-ms" }),
-            FieldElement({ name: "offlineAt", type: "systime-ms" }),
-            FieldElement({ name: "ttl", type: "uint32", quality: "N" }),
-            FieldElement({ name: "deviceIdentifier", type: "string", quality: "N" }),
-            FieldElement({ name: "discriminator", type: "uint16", quality: "N" }),
-            FieldElement({ name: "commissioningMode", type: "uint8", quality: "N" }),
-            FieldElement({ name: "vendorId", type: "vendor-id", quality: "N" }),
-            FieldElement({ name: "productId", type: "uint16", quality: "N" }),
-            FieldElement({ name: "deviceType", type: "uint16", quality: "N" }),
-            FieldElement({ name: "deviceName", type: "string", quality: "N" }),
-            FieldElement({ name: "rotatingIdentifier", type: "string", quality: "N" }),
-            FieldElement({ name: "pairingHint", type: "uint32", quality: "N" }),
-            FieldElement({ name: "pairingInstructions", type: "string", quality: "N" }),
-            FieldElement({
-                name: "sessionParameters",
-                type: "struct",
-                quality: "N",
-                children: [
-                    FieldElement({ name: "idleInterval", type: "duration", constraint: "max 3600000" }),
-                    FieldElement({ name: "activeInterval", type: "duration", constraint: "max 3600000" }),
-                    FieldElement({ name: "activeThreshold", type: "duration", constraint: "max 65535" }),
-                ],
-            }),
-            FieldElement({ name: "tcpSupport", type: "uint8", quality: "N" }),
-            FieldElement({ name: "longIdleOperatingMode", type: "bool", quality: "N" }),
-        ],
-    });
+    static override readonly schema = new DatatypeModel(
+        {
+            name: "CommissioningState",
+            type: "struct",
+        },
+
+        FieldElement({
+            name: "peerAddress",
+            type: "struct",
+            quality: "N",
+            children: [
+                FieldElement({ name: "fabricIndex", type: "fabric-id" }),
+                FieldElement({ name: "nodeId", type: "node-id" }),
+            ],
+        }),
+
+        FieldElement({
+            name: "addresses",
+            type: "list",
+            quality: "N",
+            children: [
+                FieldElement({
+                    name: "entry",
+                    type: "struct",
+                    children: [
+                        FieldElement({ name: "type", type: "string" }),
+                        FieldElement({ name: "ip", type: "string" }),
+                        FieldElement({ name: "port", type: "uint16" }),
+                        FieldElement({ name: "peripheralAddress", type: "string" }),
+                    ],
+                }),
+            ],
+        }),
+
+        FieldElement({ name: "discoveredAt", type: "systime-ms", quality: "N", conformance: "M" }),
+        FieldElement({ name: "onlineAt", type: "systime-ms" }),
+        FieldElement({ name: "offlineAt", type: "systime-ms" }),
+        FieldElement({ name: "ttl", type: "uint32", quality: "N" }),
+        FieldElement({ name: "deviceIdentifier", type: "string", quality: "N" }),
+        FieldElement({ name: "discriminator", type: "uint16", quality: "N" }),
+        FieldElement({ name: "commissioningMode", type: "uint8", quality: "N" }),
+        FieldElement({ name: "vendorId", type: "vendor-id", quality: "N" }),
+        FieldElement({ name: "productId", type: "uint16", quality: "N" }),
+        FieldElement({ name: "deviceType", type: "uint16", quality: "N" }),
+        FieldElement({ name: "deviceName", type: "string", quality: "N" }),
+        FieldElement({ name: "rotatingIdentifier", type: "string", quality: "N" }),
+        FieldElement({ name: "pairingHint", type: "uint32", quality: "N" }),
+        FieldElement({ name: "pairingInstructions", type: "string", quality: "N" }),
+        FieldElement({
+            name: "sessionParameters",
+            type: "struct",
+            quality: "N",
+            children: [
+                FieldElement({ name: "idleInterval", type: "duration", constraint: "max 3600000" }),
+                FieldElement({ name: "activeInterval", type: "duration", constraint: "max 3600000" }),
+                FieldElement({ name: "activeThreshold", type: "duration", constraint: "max 65535" }),
+            ],
+        }),
+        FieldElement({ name: "tcpSupport", type: "uint8", quality: "N" }),
+        FieldElement({ name: "longIdleOperatingMode", type: "bool", quality: "N" }),
+    );
 }
 
 export namespace CommissioningClient {

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

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { InternalError, Logger, MatterError } from "#general";
+import { InternalError, Logger, MatterError, ObserverGroup } from "#general";
 import type { ClientNode } from "#node/ClientNode.js";
-import { ClientInteraction, ExchangeProvider, PeerSet } from "#protocol";
+import { ClientInteraction, ExchangeProvider, PeerAddress, PeerSet, SessionManager } from "#protocol";
 import { CommissioningClient } from "../commissioning/CommissioningClient.js";
 import { RemoteDescriptor } from "../commissioning/RemoteDescriptor.js";
 import { NetworkRuntime } from "./NetworkRuntime.js";
@@ -21,30 +21,81 @@ const logger = Logger.get("ClientNetworkRuntime");
  */
 export class ClientNetworkRuntime extends NetworkRuntime {
     #client?: ClientInteraction;
+    #observers = new ObserverGroup();
 
     constructor(owner: ClientNode) {
         super(owner);
     }
 
+    override get owner() {
+        return super.owner as ClientNode;
+    }
+
     protected async start() {
+        // Ensure we can connect to the node
         if (!this.owner.lifecycle.isCommissioned) {
             throw new UncommissionedError(`Cannot interact with ${this.owner} because it is uncommissioned`);
         }
 
-        const commissioningState = this.owner.stateOf(CommissioningClient);
+        if (this.owner.state.network.isDisabled) {
+            throw new UncommissionedError(`Cannot interact with ${this.owner} because it is disabled`);
+        }
+
         const address = this.owner.stateOf(CommissioningClient).peerAddress;
-        const peers = this.owner.env.get(PeerSet);
 
         if (address === undefined) {
             throw new InternalError(`Commissioned node ${this.owner} has no peer address`);
         }
 
+        // Install the exchange provider for the node
+        const { env, lifecycle } = this.owner;
+        const peers = env.get(PeerSet);
+        const commissioningState = this.owner.stateOf(CommissioningClient);
+
         const exchangeProvider = await peers.exchangeProviderFor(address, {
             discoveryData: RemoteDescriptor.fromLongForm(commissioningState),
         });
-        this.owner.env.set(ExchangeProvider, exchangeProvider);
+        env.set(ExchangeProvider, exchangeProvider);
+
+        // Monitor sessions to maintain online state.  We consider the node "online" if there is an active session.  If
+        // not, we consider the node offline.  This is the only real way we have of determining whether the node is
+        // healthy without actively polling
+        this.#client = env.get(ClientInteraction);
+        const { sessions } = env.get(SessionManager);
+
+        if (sessions.find(session => session.peerIs(address))) {
+            this.owner.act(({ context }) => lifecycle.online.emit(context));
+        }
 
-        this.#client = this.owner.env.get(ClientInteraction);
+        this.#observers.on(sessions.added, session => {
+            if (lifecycle.isOnline) {
+                return;
+            }
+
+            const address = PeerAddress(commissioningState.peerAddress);
+            if (!address || session.peerAddress !== address) {
+                return;
+            }
+
+            this.owner.act(({ context }) => lifecycle.online.emit(context));
+        });
+
+        this.#observers.on(sessions.deleted, session => {
+            if (!lifecycle.isOnline) {
+                return;
+            }
+
+            const address = PeerAddress(commissioningState.peerAddress);
+            if (session.peerAddress !== address) {
+                return;
+            }
+
+            if (address && sessions.find(({ peerAddress }) => peerAddress === address)) {
+                return;
+            }
+
+            this.owner.act(({ context }) => lifecycle.offline.emit(context));
+        });
     }
 
     protected async stop() {
@@ -55,6 +106,8 @@ export class ClientNetworkRuntime extends NetworkRuntime {
         } catch (e) {
             logger.error(`Error closing connection to ${this.owner}`, e);
         }
+
+        this.#observers.close();
     }
 
     blockNewActivity() {

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

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { STANDARD_MATTER_PORT } from "#general";
+import { MaybePromise, STANDARD_MATTER_PORT } from "#general";
 import { Behavior } from "../../Behavior.js";
 import type { NetworkRuntime } from "./NetworkRuntime.js";
 
@@ -24,6 +24,11 @@ export class NetworkBehavior extends Behavior {
     override [Symbol.asyncDispose]() {
         return this.internal.runtime?.close();
     }
+
+    /**
+     * Invoked by node when networking is ready.
+     */
+    startup(): MaybePromise {}
 }
 
 export namespace NetworkBehavior {

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

@@ -14,14 +14,10 @@ export class NetworkClient extends NetworkBehavior {
     declare internal: NetworkClient.Internal;
     declare state: NetworkClient.State;
 
-    override initialize() {
-        this.reactTo(this.#node.lifecycle.online, this.startup);
-    }
-
-    protected async startup() {
-        const { startupSubscription } = this.state;
+    override async startup() {
+        const { startupSubscription, isDisabled } = this.state;
 
-        if (startupSubscription === null) {
+        if (startupSubscription === null || isDisabled) {
             return;
         }
 
@@ -31,6 +27,7 @@ export class NetworkClient extends NetworkBehavior {
             minIntervalFloor: DEFAULT_MIN_INTERVAL_FLOOR,
             maxIntervalCeiling: 0,
             attributes: [{}],
+            events: [{ isUrgent: true }],
             ...startupSubscription,
         });
 
@@ -59,6 +56,12 @@ export class NetworkClient extends NetworkBehavior {
                 default: { type: "properties", properties: {} },
                 quality: "XN",
             }),
+
+            FieldElement({
+                name: "isDisabled",
+                type: "bool",
+                quality: "N",
+            }),
         ],
     });
 }
@@ -72,11 +75,16 @@ export namespace NetworkClient {
         /**
          * A subscription installed when the node is first commissioned and when the service is restarted.
          *
-         * The default subscription is a wildcard for all attributes and of the node.  You can set to undefined or
-         * filter the fields and values but only values selected by this subscription will update automatically.
+         * The default subscription is a wildcard for all attributes of the node.  You can set to undefined or filter
+         * the fields and values but only values selected by this subscription will update automatically.
          *
          * Set to null to disable automatic subscription.
          */
         startupSubscription?: Subscribe | null;
+
+        /**
+         * If true, the matter.js will not perform network communication with the node.
+         */
+        isDisabled = false;
     }
 }

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

@@ -34,7 +34,6 @@ export abstract class NetworkRuntime {
 
     async [Construction.construct]() {
         await this.start();
-        await this.#owner.act(agent => this.owner.lifecycle.online.emit(agent.context));
     }
 
     async [Construction.destruct]() {

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

@@ -293,6 +293,8 @@ export class ServerNetworkRuntime extends NetworkRuntime {
         if (this.owner.stateOf(CommissioningServer).commissioned) {
             this.enableMdnsAdvertising();
         }
+
+        await this.owner.act(agent => this.owner.lifecycle.online.emit(agent.context));
     }
 
     override async [Construction.construct]() {

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);
 
@@ -108,6 +111,36 @@ export class ClientNode extends Node<ClientNode.RootEndpoint> {
         await this.lifecycle.mutex.produce(this.eraseWithMutex.bind(this));
     }
 
+    /**
+     * Disable the node.
+     *
+     * This shuts down any active connections and prevents future connections until re-enabled.
+     */
+    async disable() {
+        if (this.state.network.isDisabled) {
+            return;
+        }
+
+        await this.lifecycle.mutex.produce(async () => {
+            await this.cancelWithMutex();
+            await this.setStateOf(NetworkClient, { isDisabled: true });
+        });
+    }
+
+    /**
+     * Enable the node.
+     *
+     * If the node is disabled but reachable, this brings it online.
+     */
+    async enable() {
+        if (!this.state.network.isDisabled) {
+            return;
+        }
+
+        await this.setStateOf(NetworkClient, { isDisabled: false });
+        await this.start();
+    }
+
     protected async eraseWithMutex() {
         // First ensure we're offline
         await this.cancelWithMutex();

package/src/node/Node.ts

@@ -7,6 +7,7 @@
 import { ActionContext } from "#behavior/context/ActionContext.js";
 import { NodeActivity } from "#behavior/context/NodeActivity.js";
 import { IndexBehavior } from "#behavior/system/index/IndexBehavior.js";
+import { NetworkBehavior } from "#behavior/system/network/NetworkBehavior.js";
 import { NetworkRuntime } from "#behavior/system/network/NetworkRuntime.js";
 import { PartsBehavior } from "#behavior/system/parts/PartsBehavior.js";
 import { Endpoint } from "#endpoint/Endpoint.js";
@@ -116,6 +117,7 @@ export abstract class Node<T extends Node.CommonRootEndpoint = Node.CommonRootEn
             this.#runtime.construction.start();
             this.#environment.set(NetworkRuntime, this.#runtime);
             await this.#runtime.construction.ready;
+            await this.act("network startup", agent => agent.get(NetworkBehavior).startup());
         } catch (e) {
             this.env.runtime.delete(this);
             throw e;