@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.14

package/dist/{devices/device-gateway.js → local-devices/local-device-gateway.js}

@@ -20,13 +20,13 @@ import { LIST_TTL_MARGIN_MS } from "./relay.js";
 export const DEVICE_CLOSE = {
     /** The kernel is shutting down: reconnect (another gateway replica takes over). */
     shutdown: 1001,
-    /** A frame larger than `environments.device.maxFrameBytes` (sent by `ws` itself). */
+    /** A frame larger than `devices.local.maxFrameBytes` (sent by `ws` itself). */
     tooBig: 1009,
     /** The kernel failed (e.g. the database): reconnect. */
     internal: 1011,
     /** The lease was lost (renewal kept failing or the key was taken): reconnect. */
     leaseLost: 4001,
-    /** A newer connection of the environment took over: the program exits. */
+    /** A newer connection of the device took over: the program exits. */
     replaced: 4002,
     /** The machine's credential was revoked: the program exits. */
     revoked: 4003,
@@ -45,7 +45,7 @@ export const CLAIM_TIMEOUT_MS = 5_000;
 export const CLAIM_RETRY_MS = 250;
 /** Traffic marks the machine seen at most this often per connection (the row has its own gate). */
 const TOUCH_EVERY_MS = 30_000;
-/** How often a held connection re-checks its credential (membership, org, environment). */
+/** How often a held connection re-checks its credential (membership, org, device). */
 const REAUTH_EVERY_MS = 60_000;
 /**
  * Puts a frame the holder popped but could not send back at the head of the list, keeping the
@@ -60,7 +60,7 @@ return 1
 `;
 /**
  * Pops the next frame of the request list (`KEYS[1]`) and, when it is a `req`, marks it taken in
- * the same step: `<ARGV[1]><id>` → the environment id `ARGV[2]`, for the reconnect grace
+ * the same step: `<ARGV[1]><id>` → the device id `ARGV[2]`, for the reconnect grace
  * `ARGV[3]` ms plus the request's deadline plus the margin `ARGV[4]` ms (ruling R20). Returns the
  * frame, or false when the list is empty. A frame that is not JSON is returned as is (the caller
  * drops it). The taken key cannot be declared in KEYS (its id is known only after the pop): like
@@ -79,7 +79,7 @@ return raw
 `;
 /**
  * Accepts a result (ruling R20): only when its request is marked taken (`KEYS[1]`) for the
- * environment `ARGV[1]`. Stores the frame `ARGV[2]` under `KEYS[2]` for what is left of the taken
+ * device `ARGV[1]`. Stores the frame `ARGV[2]` under `KEYS[2]` for what is left of the taken
  * mark's TTL (the caller's whole window, also after a reconnect) and clears the mark. Returns 1
  * when stored, 0 otherwise.
  */
@@ -120,8 +120,8 @@ class DeviceConnection {
         this.identity = identity;
         this.credential = credential;
     }
-    get environmentId() {
-        return this.identity.environmentId;
+    get deviceId() {
+        return this.identity.deviceId;
     }
     start() {
         const { socket } = this;
@@ -157,7 +157,7 @@ class DeviceConnection {
         }
         catch (e) {
             this.gw.log.warn("device sent an invalid frame", {
-                environmentId: this.environmentId,
+                deviceId: this.deviceId,
                 error: errMsg(e),
             });
             this.close(DEVICE_CLOSE.protocol, "invalid frame");
@@ -181,7 +181,7 @@ class DeviceConnection {
             }
             catch (e) {
                 this.gw.log.warn("could not record a device hello", {
-                    environmentId: this.environmentId,
+                    deviceId: this.deviceId,
                     error: errMsg(e),
                 });
             }
@@ -197,14 +197,14 @@ class DeviceConnection {
     }
     /**
      * Stores one result and announces it (the relay's wire, relay.ts), only for a request taken for
-     * this environment (ruling R20); anything else is dropped.
+     * this device (ruling R20); anything else is dropped.
      */
     async store(res) {
         try {
-            const stored = await this.gw.redis.eval(ACCEPT, 2, deviceTakenKey(res.id), deviceResKey(res.id), this.environmentId, JSON.stringify(res));
+            const stored = await this.gw.redis.eval(ACCEPT, 2, deviceTakenKey(res.id), deviceResKey(res.id), this.deviceId, JSON.stringify(res));
             if (Number(stored) !== 1) {
-                this.gw.log.warn("dropping a device result for a request not taken for its environment", {
-                    environmentId: this.environmentId,
+                this.gw.log.warn("dropping a device result for a request not taken for its device", {
+                    deviceId: this.deviceId,
                 });
                 return;
             }
@@ -212,19 +212,19 @@ class DeviceConnection {
         }
         catch (e) {
             this.gw.log.warn("could not store a device result", {
-                environmentId: this.environmentId,
+                deviceId: this.deviceId,
                 error: errMsg(e),
             });
         }
     }
     /**
-     * Claims the environment's lease; true when this connection holds it. The newest connection
+     * Claims the device's lease; true when this connection holds it. The newest connection
      * wins (ruling R21): when another connection holds the lease, a takeover is published (the
      * holder yields to any takeover) and the lease retried every {@link CLAIM_RETRY_MS} for
      * {@link CLAIM_TIMEOUT_MS}, then 4409 (the program reconnects). A claimer never yields.
      */
     async claim() {
-        const env = this.environmentId;
+        const env = this.deviceId;
         try {
             // subscribed before claiming, so a takeover right after the claim is not missed
             await this.subscribe(deviceTakeoverTopic(env), (p) => {
@@ -253,7 +253,7 @@ class DeviceConnection {
                 return false;
             }
             if (!lease) {
-                this.close(DEVICE_CLOSE.claimTimeout, "the environment is held by another connection");
+                this.close(DEVICE_CLOSE.claimTimeout, "the device is held by another connection");
                 return false;
             }
             this.lease = lease;
@@ -276,7 +276,7 @@ class DeviceConnection {
             if (this.state !== "holding")
                 return false;
             this.gw.log.info("device connected", {
-                environmentId: env,
+                deviceId: env,
                 machineId: this.identity.machineId,
             });
             // what was queued while nobody held the machine
@@ -285,7 +285,7 @@ class DeviceConnection {
         }
         catch (e) {
             this.gw.log.warn("could not claim a device connection", {
-                environmentId: env,
+                deviceId: env,
                 error: errMsg(e),
             });
             this.close(DEVICE_CLOSE.internal, "internal error");
@@ -306,17 +306,17 @@ class DeviceConnection {
             .then(() => this.drainOnce())
             .catch((e) => {
             this.gw.log.warn("device request drain failed", {
-                environmentId: this.environmentId,
+                deviceId: this.deviceId,
                 error: errMsg(e),
             });
         });
     }
     async drainOnce() {
-        const key = deviceReqKey(this.environmentId);
+        const key = deviceReqKey(this.deviceId);
         while (this.state === "holding") {
             // no lease fencing needed: the pop is atomic, so each frame reaches one connection only, and
-            // a holder that lost its lease still talks to the environment's own machine (or puts it back)
-            const raw = (await this.gw.redis.eval(TAKE, 1, key, DEVICE_TAKEN_PREFIX, this.environmentId, String(this.gw.graceMs()), String(LIST_TTL_MARGIN_MS)));
+            // a holder that lost its lease still talks to the device's own machine (or puts it back)
+            const raw = (await this.gw.redis.eval(TAKE, 1, key, DEVICE_TAKEN_PREFIX, this.deviceId, String(this.gw.graceMs()), String(LIST_TTL_MARGIN_MS)));
             if (raw === null)
                 return;
             let frame;
@@ -325,7 +325,7 @@ class DeviceConnection {
             }
             catch (e) {
                 this.gw.log.warn("dropping an invalid device request", {
-                    environmentId: this.environmentId,
+                    deviceId: this.deviceId,
                     error: errMsg(e),
                 });
                 continue;
@@ -343,7 +343,7 @@ class DeviceConnection {
                     ok: false,
                     error: {
                         kind: "error",
-                        message: "The request is larger than environments.device.maxFrameBytes",
+                        message: "The request is larger than devices.local.maxFrameBytes",
                     },
                 });
                 continue;
@@ -363,7 +363,7 @@ class DeviceConnection {
         if (this.state === "closed")
             return;
         if (this.missedPongs >= 2) {
-            this.gw.log.info("device connection missed two pongs", { environmentId: this.environmentId });
+            this.gw.log.info("device connection missed two pongs", { deviceId: this.deviceId });
             this.socket.terminate();
             void this.shutdown();
             return;
@@ -378,7 +378,7 @@ class DeviceConnection {
             void this.reauthenticate();
         }
     }
-    /** The credential still stands (membership, org and environment are read live). */
+    /** The credential still stands (membership, org and device are read live). */
     async reauthenticate() {
         try {
             const id = await this.gw.machines.authenticate(this.credential);
@@ -388,7 +388,7 @@ class DeviceConnection {
         }
         catch (e) {
             this.gw.log.warn("could not re-check a device credential", {
-                environmentId: this.environmentId,
+                deviceId: this.deviceId,
                 error: errMsg(e),
             });
         }
@@ -400,7 +400,7 @@ class DeviceConnection {
         this.lastTouch = now;
         this.gw.machines.touch(this.identity.machineId).catch((e) => {
             this.gw.log.warn("could not mark a machine seen", {
-                environmentId: this.environmentId,
+                deviceId: this.deviceId,
                 error: errMsg(e),
             });
         });
@@ -436,7 +436,7 @@ class DeviceConnection {
             }
             catch (e) {
                 this.gw.log.warn("could not release a device lease", {
-                    environmentId: this.environmentId,
+                    deviceId: this.deviceId,
                     error: errMsg(e),
                 });
             }
@@ -444,7 +444,7 @@ class DeviceConnection {
             this.gw.forget(this);
             if (lease) {
                 this.gw.log.info("device disconnected", {
-                    environmentId: this.environmentId,
+                    deviceId: this.deviceId,
                     machineId: this.identity.machineId,
                 });
             }
@@ -455,17 +455,17 @@ class DeviceConnection {
 /**
  * The gateway role's half of the device relay (environments spec §13.4): holds the WebSocket
  * connections of connected machines (`GET /device/connect`, device-routes.ts). One connection per
- * environment across replicas, under the lease `capk:device-lease:<environmentId>` (the newest
- * connection wins: it publishes `device.takeover.<environmentId>` and the holder lets go). The
- * holder drains `capk:device-req:<environmentId>` on every `device.req.<environmentId>` nudge,
- * once after claiming and on every ping, marking each forwarded request taken for its environment
+ * device across replicas, under the lease `capk:device-lease:<deviceId>` (the newest
+ * connection wins: it publishes `device.takeover.<deviceId>` and the holder lets go). The
+ * holder drains `capk:device-req:<deviceId>` on every `device.req.<deviceId>` nudge,
+ * once after claiming and on every ping, marking each forwarded request taken for its device
  * (`capk:device-taken:<id>`, TTL the reconnect grace plus the request's deadline plus a margin).
- * A `res` is accepted only for a request taken for the socket's environment: it is stored under
+ * A `res` is accepted only for a request taken for the socket's device: it is stored under
  * `capk:device-res:<id>` for the rest of that TTL and published on `device.res.<id>`.
- * `device.revoked.<environmentId>` closes the connection of that machine only (ruling R16). The
+ * `device.revoked.<deviceId>` closes the connection of that machine only (ruling R16). The
  * sockets are this process's own; everything other replicas need is in Redis.
  */
-let DeviceGateway = class DeviceGateway {
+let LocalDeviceGateway = class LocalDeviceGateway {
     machines;
     locks;
     bus;
@@ -486,13 +486,13 @@ let DeviceGateway = class DeviceGateway {
         this.log = log;
     }
     graceMs() {
-        return this.config.get().environments.device.reconnectGraceSeconds * 1000;
+        return this.config.get().devices.local.reconnectGraceSeconds * 1000;
     }
     leaseTtlMs() {
-        return this.config.get().environments.device.leaseTtlMs;
+        return this.config.get().devices.local.leaseTtlMs;
     }
     maxFrameBytes() {
-        return this.config.get().environments.device.maxFrameBytes;
+        return this.config.get().devices.local.maxFrameBytes;
     }
     /** Who a `Bearer` machine credential stands for, or null (checked before the upgrade). */
     authenticate(credential) {
@@ -518,7 +518,7 @@ let DeviceGateway = class DeviceGateway {
         await Promise.all([...this.connections].map((c) => c.close(DEVICE_CLOSE.shutdown, "shutting down")));
     }
 };
-DeviceGateway = __decorate([
+LocalDeviceGateway = __decorate([
     Injectable(),
     __param(0, Inject(MachinesService)),
     __param(1, Inject(LockService)),
@@ -526,5 +526,5 @@ DeviceGateway = __decorate([
     __param(3, Inject(REDIS)),
     __param(4, Inject(KernelConfigService)),
     __param(5, Inject(KERNEL_LOGGER))
-], DeviceGateway);
-export { DeviceGateway };
+], LocalDeviceGateway);
+export { LocalDeviceGateway };

package/dist/{devices/device-provider.d.ts → local-devices/local-device-provider.d.ts}

@@ -1,7 +1,7 @@
 import type { ExecResult, FileSystemHandle, SandboxHandle, SandboxLimits, SandboxProvider, SandboxRoots } from "@capybara-hq/plugin-sdk";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
-import { DeviceRelay } from "./relay.js";
+import { LocalDeviceRelay } from "./relay.js";
 import { DeviceTargets } from "./targets.js";
 /** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
 export declare const EXEC_DEADLINE_MARGIN_MS = 5000;
@@ -9,42 +9,42 @@ export declare const EXEC_DEADLINE_MARGIN_MS = 5000;
 export declare const OP_DEADLINE_MS = 30000;
 /**
  * Room left in a frame for everything around a `readFile` result's base64 data (the `res`
- * envelope): a read is clamped so the machine's answer fits `environments.device.maxFrameBytes`
+ * envelope): a read is clamped so the machine's answer fits `devices.local.maxFrameBytes`
  * (ruling R26).
  */
 export declare const FRAME_ENVELOPE_BYTES: number;
 /** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
 export declare const maxReadBytes: (maxFrameBytes: number) => number;
 /**
- * The handle of an instance on a machine: the environment id (ruling R1: the relay is keyed by
- * environment), the roots the machine reported at `create`, and the org's effective limits at
+ * The handle of an instance on a machine: the device id (ruling R1: the relay is keyed by
+ * device), the roots the machine reported at `create`, and the org's effective limits at
  * creation (for the record: every `exec` carries the org's limits read at that moment, ruling
  * R27, so the machine intersects its local policy with the current egress).
  */
-export interface DeviceSandboxHandle extends SandboxHandle {
+export interface LocalDeviceHandle extends SandboxHandle {
     roots: SandboxRoots;
     limits: SandboxLimits;
 }
-/** The environment id of a `cap-env-<environmentId>` name; undefined for any other name. */
-export declare const environmentIdOfName: (name: string) => string | undefined;
+/** The device id of a `cap-device-<deviceId>` name; undefined for any other name. */
+export declare const deviceIdOfName: (name: string) => string | undefined;
 /**
- * The kernel-internal provider `@device` (environments spec §13.5): every operation runs on the
- * environment's connected machine through the {@link DeviceRelay}. The file system is the
- * machine's environment directory (the program creates it on first use), so `createFileSystem`
+ * The kernel-internal provider `@local` (environments spec §13.5): every operation runs on the
+ * device's connected machine through the {@link LocalDeviceRelay}. The file system is the
+ * machine's device directory (the program creates it on first use), so `createFileSystem`
  * touches nothing; `suspend` and `destroy` do nothing (the machine is not the platform's to stop);
- * deleting the environment leaves the files on the machine where they are. Nothing here throws `environment.offline` on the cleanup paths (ruling R9).
+ * deleting the device leaves the files on the machine where they are. Nothing here throws `device.offline` on the cleanup paths (ruling R9).
  *
  * The files on a machine are its owner's: `destroyFileSystem` (a files reset, the deletion sweep)
  * does nothing; the deletion's `stop` comes from `MachinesService.revokeActive` (ruling R24).
  */
-export declare class DeviceSandboxProvider implements SandboxProvider {
+export declare class LocalDeviceProvider implements SandboxProvider {
     private readonly relay;
     private readonly targets;
     private readonly sandbox;
     private readonly config;
     readonly concurrentExec: true;
     readonly sessionIsolation = false;
-    constructor(relay: DeviceRelay, targets: Pick<DeviceTargets, "orgOf" | "machineRoots">, sandbox: Pick<SandboxService, "orgLimits">, config: Pick<KernelConfigService, "get">);
+    constructor(relay: LocalDeviceRelay, targets: Pick<DeviceTargets, "orgOf" | "machineRoots">, sandbox: Pick<SandboxService, "orgLimits">, config: Pick<KernelConfigService, "get">);
     createFileSystem(args: {
         name: string;
         limits: SandboxLimits;
@@ -59,7 +59,7 @@ export declare class DeviceSandboxProvider implements SandboxProvider {
         limits: SandboxLimits;
         fileSystem: FileSystemHandle;
         signal: AbortSignal;
-    }): Promise<DeviceSandboxHandle>;
+    }): Promise<LocalDeviceHandle>;
     /**
      * Needs the machine online. `gone` (the kernel recreates the instance) when the active machine
      * last reported other roots than the instance was created with (a new login into another
@@ -84,6 +84,6 @@ export declare class DeviceSandboxProvider implements SandboxProvider {
         size: number;
         isDir: boolean;
     } | null>;
-    /** The org's effective limits now (ruling R27); a deleted environment is not found. */
+    /** The org's effective limits now (ruling R27); a deleted device is not found. */
     private currentLimits;
 }

package/dist/{devices/device-provider.js → local-devices/local-device-provider.js}

@@ -9,8 +9,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable } from "@nestjs/common";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
-import { environmentNotFound, SandboxService } from "../sandbox/sandbox.service.js";
-import { DeviceRelay, environmentOffline } from "./relay.js";
+import { deviceNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { deviceOffline, LocalDeviceRelay } from "./relay.js";
 import { DeviceTargets, sameRoots } from "./targets.js";
 /** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
 export const EXEC_DEADLINE_MARGIN_MS = 5000;
@@ -18,30 +18,30 @@ export const EXEC_DEADLINE_MARGIN_MS = 5000;
 export const OP_DEADLINE_MS = 30_000;
 /**
  * Room left in a frame for everything around a `readFile` result's base64 data (the `res`
- * envelope): a read is clamped so the machine's answer fits `environments.device.maxFrameBytes`
+ * envelope): a read is clamped so the machine's answer fits `devices.local.maxFrameBytes`
  * (ruling R26).
  */
 export const FRAME_ENVELOPE_BYTES = 64 * 1024;
 /** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
 export const maxReadBytes = (maxFrameBytes) => Math.max(0, Math.floor((maxFrameBytes - FRAME_ENVELOPE_BYTES) / 4) * 3);
-const NAME_PREFIX = "cap-env-";
-/** The environment id of a `cap-env-<environmentId>` name; undefined for any other name. */
-export const environmentIdOfName = (name) => name.startsWith(NAME_PREFIX) && name.length > NAME_PREFIX.length
+const NAME_PREFIX = "cap-device-";
+/** The device id of a `cap-device-<deviceId>` name; undefined for any other name. */
+export const deviceIdOfName = (name) => name.startsWith(NAME_PREFIX) && name.length > NAME_PREFIX.length
     ? name.slice(NAME_PREFIX.length)
     : undefined;
 const rootsOf = (h) => h.roots;
 const bytesOf = (b64) => new Uint8Array(Buffer.from(b64, "base64"));
 /**
- * The kernel-internal provider `@device` (environments spec §13.5): every operation runs on the
- * environment's connected machine through the {@link DeviceRelay}. The file system is the
- * machine's environment directory (the program creates it on first use), so `createFileSystem`
+ * The kernel-internal provider `@local` (environments spec §13.5): every operation runs on the
+ * device's connected machine through the {@link LocalDeviceRelay}. The file system is the
+ * machine's device directory (the program creates it on first use), so `createFileSystem`
  * touches nothing; `suspend` and `destroy` do nothing (the machine is not the platform's to stop);
- * deleting the environment leaves the files on the machine where they are. Nothing here throws `environment.offline` on the cleanup paths (ruling R9).
+ * deleting the device leaves the files on the machine where they are. Nothing here throws `device.offline` on the cleanup paths (ruling R9).
  *
  * The files on a machine are its owner's: `destroyFileSystem` (a files reset, the deletion sweep)
  * does nothing; the deletion's `stop` comes from `MachinesService.revokeActive` (ruling R24).
  */
-let DeviceSandboxProvider = class DeviceSandboxProvider {
+let LocalDeviceProvider = class LocalDeviceProvider {
     relay;
     targets;
     sandbox;
@@ -56,9 +56,9 @@ let DeviceSandboxProvider = class DeviceSandboxProvider {
     }
     async createFileSystem(args) {
         args.signal.throwIfAborted();
-        const id = environmentIdOfName(args.name);
+        const id = deviceIdOfName(args.name);
         if (id === undefined)
-            throw new Error(`not an environment name: ${args.name}`);
+            throw new Error(`not a device name: ${args.name}`);
         return { id };
     }
     /** The files are the machine owner's: nothing to do (ruling R24; never a `stop`). */
@@ -81,7 +81,7 @@ let DeviceSandboxProvider = class DeviceSandboxProvider {
     async resume(h, signal) {
         signal.throwIfAborted();
         if (!(await this.relay.holderLive(h.id)))
-            throw environmentOffline();
+            throw deviceOffline();
         const had = rootsOf(h);
         const now = await this.targets.machineRoots(h.id);
         if (had === undefined || (now !== null && !sameRoots(had, now)))
@@ -122,7 +122,7 @@ let DeviceSandboxProvider = class DeviceSandboxProvider {
     }
     async readFile(h, path, opts) {
         // the answer must fit one frame: a larger file comes back truncated (Deliver: too large)
-        const maxBytes = Math.min(opts.maxBytes, maxReadBytes(this.config.get().environments.device.maxFrameBytes));
+        const maxBytes = Math.min(opts.maxBytes, maxReadBytes(this.config.get().devices.local.maxFrameBytes));
         const r = await this.relay.call(h.id, "readFile", { path, maxBytes }, { deadlineMs: OP_DEADLINE_MS, signal: opts.signal });
         return r === null ? null : { data: bytesOf(r.dataB64), truncated: r.truncated };
     }
@@ -133,19 +133,19 @@ let DeviceSandboxProvider = class DeviceSandboxProvider {
     async stat(h, path, signal) {
         return this.relay.call(h.id, "stat", { path }, { deadlineMs: OP_DEADLINE_MS, signal });
     }
-    /** The org's effective limits now (ruling R27); a deleted environment is not found. */
-    async currentLimits(environmentId) {
-        const orgId = await this.targets.orgOf(environmentId);
+    /** The org's effective limits now (ruling R27); a deleted device is not found. */
+    async currentLimits(deviceId) {
+        const orgId = await this.targets.orgOf(deviceId);
         if (orgId === null)
-            throw environmentNotFound();
+            throw deviceNotFound();
         return this.sandbox.orgLimits(orgId);
     }
 };
-DeviceSandboxProvider = __decorate([
+LocalDeviceProvider = __decorate([
     Injectable(),
-    __param(0, Inject(DeviceRelay)),
+    __param(0, Inject(LocalDeviceRelay)),
     __param(1, Inject(DeviceTargets)),
     __param(2, Inject(SandboxService)),
     __param(3, Inject(KernelConfigService))
-], DeviceSandboxProvider);
-export { DeviceSandboxProvider };
+], LocalDeviceProvider);
+export { LocalDeviceProvider };

package/dist/local-devices/local-devices.module.d.ts

@@ -0,0 +1,16 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { LocalDeviceProvider } from "./local-device-provider.js";
+/**
+ * Connected machines (environments spec §6, §13): the caller side of the device relay and the
+ * kernel-internal `@local` sandbox provider, registered with {@link SandboxProviders} on init, and
+ * the machines and their credentials ({@link MachinesService}).
+ * Imported on every role: any replica may run a sandbox operation on a local device
+ * (the socket itself is held by the gateway role).
+ */
+export declare class LocalDevicesModule implements OnModuleInit {
+    private readonly providers;
+    private readonly provider;
+    constructor(providers: SandboxProviders, provider: LocalDeviceProvider);
+    onModuleInit(): void;
+}

package/dist/local-devices/local-devices.module.js

@@ -0,0 +1,44 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Module } from "@nestjs/common";
+import { LOCAL_PROVIDER, SandboxProviders } from "../sandbox/providers.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { LocalDeviceProvider } from "./local-device-provider.js";
+import { MachinesService } from "./machines.js";
+import { LocalDeviceRelay } from "./relay.js";
+import { DeviceTargets } from "./targets.js";
+/**
+ * Connected machines (environments spec §6, §13): the caller side of the device relay and the
+ * kernel-internal `@local` sandbox provider, registered with {@link SandboxProviders} on init, and
+ * the machines and their credentials ({@link MachinesService}).
+ * Imported on every role: any replica may run a sandbox operation on a local device
+ * (the socket itself is held by the gateway role).
+ */
+let LocalDevicesModule = class LocalDevicesModule {
+    providers;
+    provider;
+    constructor(providers, provider) {
+        this.providers = providers;
+        this.provider = provider;
+    }
+    onModuleInit() {
+        this.providers.register({ plugin: LOCAL_PROVIDER, impl: this.provider });
+    }
+};
+LocalDevicesModule = __decorate([
+    Module({
+        imports: [SandboxModule],
+        providers: [DeviceTargets, LocalDeviceRelay, LocalDeviceProvider, MachinesService],
+        exports: [LocalDeviceRelay, LocalDeviceProvider, MachinesService],
+    }),
+    __param(0, Inject(SandboxProviders)),
+    __param(1, Inject(LocalDeviceProvider))
+], LocalDevicesModule);
+export { LocalDevicesModule };