@capybara-hq/kernel 0.1.0-rc.7 → 0.1.0-rc.9

package/dist/environments/conversation-environments.js

@@ -12,7 +12,7 @@ import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
-import { SandboxProviders } from "../sandbox/providers.js";
+import { isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
 import { environmentNotFound, sandboxUnavailable } from "../sandbox/sandbox.service.js";
 import { EnvironmentAccess } from "./access.js";
 import { EnvironmentsService } from "./environments.service.js";
@@ -45,13 +45,14 @@ let ConversationEnvironments = class ConversationEnvironments {
      * The environment a new conversation of `accountId` is bound to: the chosen one when it is
      * usable by the person (else `environment.not_found` / `environment.unavailable`, and nothing
      * is created); without a choice the IM default (IM only) or the person's default environment.
-     * Null (unbound) without a sandbox provider and for anonymous IM senders.
+     * Null (unbound) for anonymous IM senders, and without a cloud sandbox provider when no usable
+     * IM default (a connected machine's environment, say) applies.
      */
     async forNew(orgId, accountId, pick = {}) {
         if (pick.environmentId !== undefined) {
             return (await this.access.usable(orgId, accountId, pick.environmentId)).id;
         }
-        if (this.providers.current() === undefined)
+        if (pick.im !== true && this.providers.cloud() === undefined)
             return null;
         if (await this.isAnonymous(orgId, accountId))
             return null;
@@ -62,12 +63,12 @@ let ConversationEnvironments = class ConversationEnvironments {
      * enters, checked for its owner now. A conversation still unbound (created before
      * environments, or while no provider existed) is bound first, to the owner's IM default when it
      * is an IM thread, else to the owner's default environment; a racing call binds it once.
-     * Throws `sandbox.unavailable` without a provider or for an anonymous IM conversation, and
-     * `environment.not_found` / `environment.unavailable` when the owner may not use it now.
+     * Throws `sandbox.unavailable` for a cloud environment (or none to bind) without a cloud
+     * provider and for an anonymous IM conversation, and `environment.not_found` /
+     * `environment.unavailable` when the owner may not use it now. A conversation bound to a
+     * connected machine's environment (`@device`) does not need a cloud provider.
      */
     async forTool(orgId, rootConversationId) {
-        if (this.providers.current() === undefined)
-            throw sandboxUnavailable();
         const conv = await this.db
             .selectFrom("conversations")
             .select(["account_id", "environment_id"])
@@ -82,14 +83,62 @@ let ConversationEnvironments = class ConversationEnvironments {
         if (environmentId === null) {
             const im = await this.isImThread(rootConversationId);
             const chosen = await this.defaultFor(orgId, conv.account_id, im);
+            if (chosen === null)
+                throw sandboxUnavailable();
             environmentId = await this.bind(rootConversationId, chosen);
         }
+        if (this.providers.cloud() === undefined && !(await this.isInternal(environmentId))) {
+            throw sandboxUnavailable();
+        }
         return (await this.access.usable(orgId, conv.account_id, environmentId)).id;
     }
+    /**
+     * Whether a sandbox tool call of the tree rooted at `rootConversationId` has a provider to run
+     * on, for tool listings (ruling R8; no binding, no access check, never throws): a cloud
+     * provider is loaded, or the environment the conversation is bound to (an unbound IM thread:
+     * its owner's IM default) runs on a registered kernel provider (`@device`). A forbidden or gone
+     * environment still counts: the call then says why.
+     */
+    async usableNow(orgId, rootConversationId) {
+        if (this.providers.cloud() !== undefined)
+            return true;
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select(["account_id", "environment_id"])
+            .where("id", "=", rootConversationId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!conv)
+            return false;
+        let environmentId = conv.environment_id;
+        if (environmentId === null) {
+            if (!(await this.isImThread(rootConversationId)))
+                return false;
+            const row = await this.db
+                .selectFrom("environment_defaults")
+                .select("environment_id")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", conv.account_id)
+                .executeTakeFirst();
+            if (!row)
+                return false;
+            environmentId = row.environment_id;
+        }
+        const env = await this.db
+            .selectFrom("environments")
+            .select("provider")
+            .where("id", "=", environmentId)
+            .executeTakeFirst();
+        const provider = env?.provider ?? null;
+        return (provider !== null &&
+            isInternalProvider(provider) &&
+            this.providers.forName?.(provider) !== undefined);
+    }
     /**
      * The person's IM default when `im` and it is still theirs, live, in this org and usable (the
-     * table has no such guard), else their default environment (created when missing). The owner
-     * having left the org reads as `environment.not_found`.
+     * table has no such guard), else their default environment (created when missing); null when
+     * that is needed and there is no cloud provider to make or use it. The owner having left the org
+     * reads as `environment.not_found`.
      */
     async defaultFor(orgId, accountId, im) {
         if (im) {
@@ -109,6 +158,8 @@ let ConversationEnvironments = class ConversationEnvironments {
                 }
             }
         }
+        if (this.providers.cloud() === undefined)
+            return null;
         try {
             return await this.environments.ensureDefault(orgId, accountId);
         }
@@ -133,6 +184,16 @@ let ConversationEnvironments = class ConversationEnvironments {
             .executeTakeFirstOrThrow();
         return row.environment_id ?? environmentId;
     }
+    /** The environment runs on a kernel-internal provider (`@device`). */
+    async isInternal(environmentId) {
+        const row = await this.db
+            .selectFrom("environments")
+            .select("provider")
+            .where("id", "=", environmentId)
+            .executeTakeFirst();
+        const provider = row?.provider ?? null;
+        return provider !== null && isInternalProvider(provider);
+    }
     /** The account is the org's anonymous IM guest (no person behind it). */
     async isAnonymous(orgId, accountId) {
         const row = await this.db

package/dist/environments/environments.controller.d.ts

@@ -13,7 +13,9 @@ import { type EnvironmentList, EnvironmentsService, type EnvironmentView } from
  * - `POST / { name }` → 201 `{ environment }`; `GET /:id`, `PATCH /:id { name }` → `{ environment }`;
  * - `DELETE /:id` → 202 (destroyed by a job after the response);
  * - `POST /:id/files/reset` → 202 (the reset is enqueued: a worker empties the files, the next use
- *   starts empty).
+ *   starts empty);
+ * - `DELETE /:id/machine` → 204: a device environment's machine is disconnected (its credential
+ *   revoked; it must sign in again).
  */
 export declare class EnvironmentsController {
     private readonly environments;
@@ -30,4 +32,5 @@ export declare class EnvironmentsController {
     }>;
     remove(principal: Principal, org: OrgContext, params: z.infer<typeof EnvironmentParams>): Promise<void>;
     resetFiles(principal: Principal, org: OrgContext, params: z.infer<typeof EnvironmentParams>): Promise<void>;
+    revokeMachine(principal: Principal, org: OrgContext, params: z.infer<typeof EnvironmentParams>): Promise<void>;
 }

package/dist/environments/environments.controller.js

@@ -23,7 +23,9 @@ import { EnvironmentsService, } from "./environments.service.js";
  * - `POST / { name }` → 201 `{ environment }`; `GET /:id`, `PATCH /:id { name }` → `{ environment }`;
  * - `DELETE /:id` → 202 (destroyed by a job after the response);
  * - `POST /:id/files/reset` → 202 (the reset is enqueued: a worker empties the files, the next use
- *   starts empty).
+ *   starts empty);
+ * - `DELETE /:id/machine` → 204: a device environment's machine is disconnected (its credential
+ *   revoked; it must sign in again).
  */
 let EnvironmentsController = class EnvironmentsController {
     environments;
@@ -58,6 +60,10 @@ let EnvironmentsController = class EnvironmentsController {
         const p = requireUser(principal);
         await this.environments.resetFiles(org.orgId, p.account.id, params.id, patTokenId(p));
     }
+    async revokeMachine(principal, org, params) {
+        const p = requireUser(principal);
+        await this.environments.revokeMachine(org.orgId, p.account.id, params.id, patTokenId(p));
+    }
 };
 __decorate([
     Get(),
@@ -103,6 +109,14 @@ __decorate([
     __param(1, CurrentOrg()),
     __param(2, ZParam(EnvironmentParamsDto))
 ], EnvironmentsController.prototype, "resetFiles", null);
+__decorate([
+    Delete(":id/machine"),
+    HttpCode(204),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(EnvironmentParamsDto))
+], EnvironmentsController.prototype, "revokeMachine", null);
 EnvironmentsController = __decorate([
     Controller("api/v1/orgs/:orgId/environments"),
     __param(0, Inject(EnvironmentsService))

package/dist/environments/environments.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { DevicesModule } from "../devices/devices.module.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { EnvironmentAccess } from "./access.js";
 import { ConversationEnvironments } from "./conversation-environments.js";
@@ -19,7 +20,8 @@ let EnvironmentsModule = class EnvironmentsModule {
 };
 EnvironmentsModule = __decorate([
     Module({
-        imports: [SandboxModule],
+        // DevicesModule: deleting a device environment revokes its machine
+        imports: [SandboxModule, DevicesModule],
         providers: [EnvironmentAccess, EnvironmentsService, ConversationEnvironments],
         exports: [EnvironmentAccess, EnvironmentsService, ConversationEnvironments],
     })

package/dist/environments/environments.service.d.ts

@@ -1,7 +1,9 @@
 import type { SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { MachinesService } from "../devices/machines.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
 import { SandboxProviders } from "../sandbox/providers.js";
@@ -14,11 +16,16 @@ export interface EnvironmentView {
     name: string | null;
     isDefault: boolean;
     ownerKind: "personal";
-    source: "cloud";
+    /** `device`: a connected machine (provider `@device`). */
+    source: "cloud" | "device";
     /** The provider keeping its files, or the one its first use will create them with. */
     provider: string | null;
-    /** Its provider is the deployment's current sandbox provider. */
+    /** Its provider is there: the deployment's current cloud provider, or `@device` registered. */
     available: boolean;
+    /** A device environment: some replica holds its machine's connection now; null for cloud. */
+    online: boolean | null;
+    /** A device environment's connected machine (its unrevoked one); null for cloud or none. */
+    machine: EnvironmentMachineView | null;
     sessionIsolation: boolean;
     /** Its file system is gone at the provider; reset the files to use it again. */
     filesLost: boolean;
@@ -30,6 +37,15 @@ export interface EnvironmentView {
     limits: SandboxLimits;
     createdAt: string;
 }
+/** The machine connected to a device environment, as its owner sees it. */
+export interface EnvironmentMachineView {
+    id: string;
+    name: string;
+    os: string;
+    mode: "os" | "docker" | null;
+    programVersion: string | null;
+    lastSeenAt: string | null;
+}
 /** The list response: the person's live environments in the org. */
 export interface EnvironmentList {
     items: EnvironmentView[];
@@ -41,7 +57,8 @@ export interface EnvironmentList {
     cloudAvailable: boolean;
 }
 /**
- * Personal cloud environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §9): a
+ * Personal environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §6; §9):
+ * cloud ones on the deployment's sandbox provider and `device` ones on a connected machine; a
  * person's environments in an org, visible and usable only by their owner (anyone else gets
  * `environment.not_found`). Deleting one soft-deletes it and destroys its instance and files in a
  * `sandbox-destroy-for` job after the commit.
@@ -55,7 +72,12 @@ export declare class EnvironmentsService {
     private readonly sandboxJobs;
     private readonly access;
     private readonly log;
-    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, providers: Pick<SandboxProviders, "current">, sandbox: Pick<SandboxService, "orgLimits">, sandboxJobs: Pick<SandboxJobs, "destroy" | "resetFiles">, access: Pick<EnvironmentAccess, "usable">, log: Pick<KernelLogger, "warn">);
+    /** Reads the device relay's lease (`online`). */
+    private readonly locks;
+    private readonly machines;
+    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, providers: Pick<SandboxProviders, "cloud" | "forName">, sandbox: Pick<SandboxService, "orgLimits">, sandboxJobs: Pick<SandboxJobs, "destroy" | "resetFiles">, access: Pick<EnvironmentAccess, "usable">, log: Pick<KernelLogger, "warn">, 
+    /** Reads the device relay's lease (`online`). */
+    locks: Pick<LockService, "holderOf">, machines: Pick<MachinesService, "revoke" | "revokeActive">);
     /**
      * The person's live environments in the org, the default first, then by creation. With a
      * current sandbox provider the default environment is created first if missing (its first need,
@@ -74,6 +96,20 @@ export declare class EnvironmentsService {
         name: string;
     }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<EnvironmentView>;
     private insert;
+    /**
+     * A new personal `device` environment for a machine being connected (provider `@device`; the
+     * machine row is the caller's). Joins the caller's transaction (the device authorization's).
+     * Counted against `environments.maxPersonal` (`environment.limit_reached`); a live name of the
+     * person's → `environment.name_taken`. Needs no cloud provider.
+     */
+    createDevice(orgId: string, accountId: string, name: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Inserts a named personal environment under the person's membership lock, after the limit
+     * and name checks, and audits `environment.created`. Runs in the caller's transaction.
+     */
+    private insertNamed;
     /**
      * The refusals {@link create} would raise, read without locks or writes (a precheck before a
      * confirmation card): no sandbox provider, the person's limit, a name already taken. Throws the
@@ -82,7 +118,10 @@ export declare class EnvironmentsService {
     checkCreate(orgId: string, accountId: string, name: string): Promise<void>;
     /** How many of the person's conversations work in the environment (read only). */
     boundConversations(orgId: string, accountId: string, id: string): Promise<number>;
-    /** The refusals {@link resetFiles} would raise (not found, its provider not current), read only. */
+    /**
+     * The refusals {@link resetFiles} would raise (not found, its provider not current, a connected
+     * environment), read only.
+     */
     checkReset(orgId: string, accountId: string, id: string): Promise<void>;
     /** The refusals {@link rename} would raise, read without locks (see {@link checkCreate}). */
     checkRename(orgId: string, accountId: string, id: string, name: string): Promise<void>;
@@ -93,15 +132,23 @@ export declare class EnvironmentsService {
      * Deletes one of the person's live environments: soft delete, its IM default row cleared, and
      * after the commit a `sandbox-destroy-for` job (the worker waits for running commands, then
      * destroys the instance and the files). Conversations bound to it keep pointing at it; their
-     * sandbox tools then fail with `environment.not_found`.
+     * sandbox tools then fail with `environment.not_found`. A device environment's machine is
+     * revoked in the same transaction; after the commit it is told `stop { reason: "deleted" }`
+     * (while connected) and its connection is closed.
      */
     remove(orgId: string, accountId: string, id: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
+    /**
+     * Disconnects the machine of one of the person's own device environments (it must sign in
+     * again); see {@link MachinesService.revoke}.
+     */
+    revokeMachine(orgId: string, accountId: string, id: string, actorTokenId?: string): Promise<void>;
     /**
      * Starts one of the person's environments over with empty files (after
      * `environment.files_lost`): records the request (audit), then, after the commit, enqueues the
      * `sandbox-reset-files` job (deterministic id per environment), whose worker waits for running
      * commands and destroys any instance and the file system; the next use creates new ones. Its
-     * provider must be the current one (`environment.unavailable`). An enqueue failure is thrown
+     * provider must be the current one (`environment.unavailable`); a connected environment's files
+     * are its machine owner's (`environment.files_on_device`). An enqueue failure is thrown
      * (the request can be repeated: the reset is idempotent).
      */
     resetFiles(orgId: string, accountId: string, id: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;

package/dist/environments/environments.service.js

@@ -10,6 +10,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { deviceLeaseKey } from "../devices/keys.js";
+import { MachinesService } from "../devices/machines.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -17,9 +19,10 @@ import { afterCommit } from "../infra/database/after-commit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
+import { LockService } from "../infra/lock/lock.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
-import { SandboxProviders } from "../sandbox/providers.js";
+import { DEVICE_PROVIDER, isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
 import { environmentNotFound, SandboxService } from "../sandbox/sandbox.service.js";
 import { EnvironmentAccess, environmentProvider, environmentUnavailable, } from "./access.js";
 const isUniqueViolation = (e, constraint) => typeof e === "object" &&
@@ -28,7 +31,8 @@ const isUniqueViolation = (e, constraint) => typeof e === "object" &&
     e.constraint === constraint;
 const nameTaken = () => new ApiError("environment.name_taken", "You already have an environment with this name");
 /**
- * Personal cloud environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §9): a
+ * Personal environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §6; §9):
+ * cloud ones on the deployment's sandbox provider and `device` ones on a connected machine; a
  * person's environments in an org, visible and usable only by their owner (anyone else gets
  * `environment.not_found`). Deleting one soft-deletes it and destroys its instance and files in a
  * `sandbox-destroy-for` job after the commit.
@@ -42,7 +46,11 @@ let EnvironmentsService = class EnvironmentsService {
     sandboxJobs;
     access;
     log;
-    constructor(db, txHost, config, providers, sandbox, sandboxJobs, access, log) {
+    locks;
+    machines;
+    constructor(db, txHost, config, providers, sandbox, sandboxJobs, access, log, 
+    /** Reads the device relay's lease (`online`). */
+    locks, machines) {
         this.db = db;
         this.txHost = txHost;
         this.config = config;
@@ -51,6 +59,8 @@ let EnvironmentsService = class EnvironmentsService {
         this.sandboxJobs = sandboxJobs;
         this.access = access;
         this.log = log;
+        this.locks = locks;
+        this.machines = machines;
     }
     /**
      * The person's live environments in the org, the default first, then by creation. With a
@@ -58,7 +68,7 @@ let EnvironmentsService = class EnvironmentsService {
      * spec §4.2 item 7; an existing one is only read).
      */
     async list(orgId, accountId) {
-        const cloudAvailable = this.providers.current() !== undefined;
+        const cloudAvailable = this.providers.cloud() !== undefined;
         const defaultId = cloudAvailable ? await this.ensureDefault(orgId, accountId) : null;
         const items = await this.views(orgId, accountId);
         const last = await this.db
@@ -99,9 +109,28 @@ let EnvironmentsService = class EnvironmentsService {
         return this.get(orgId, accountId, id);
     }
     async insert(orgId, accountId, name, actorTokenId, auditDetail) {
-        const current = this.providers.current();
+        const current = this.providers.cloud();
         if (!current)
             throw environmentUnavailable(null);
+        return this.insertNamed(orgId, accountId, name, "cloud", current.plugin, actorTokenId, auditDetail ?? {});
+    }
+    /**
+     * A new personal `device` environment for a machine being connected (provider `@device`; the
+     * machine row is the caller's). Joins the caller's transaction (the device authorization's).
+     * Counted against `environments.maxPersonal` (`environment.limit_reached`); a live name of the
+     * person's → `environment.name_taken`. Needs no cloud provider.
+     */
+    async createDevice(orgId, accountId, name) {
+        const id = await this.insertNamed(orgId, accountId, name, "device", DEVICE_PROVIDER, undefined, {
+            source: "device",
+        });
+        return { id };
+    }
+    /**
+     * Inserts a named personal environment under the person's membership lock, after the limit
+     * and name checks, and audits `environment.created`. Runs in the caller's transaction.
+     */
+    async insertNamed(orgId, accountId, name, source, provider, actorTokenId, auditDetail) {
         await this.lockMember(orgId, accountId);
         const { n } = await this.db
             .selectFrom("environments")
@@ -126,8 +155,8 @@ let EnvironmentsService = class EnvironmentsService {
                 owner_kind: "personal",
                 owner_account_id: accountId,
                 name,
-                source: "cloud",
-                provider: current.plugin,
+                source,
+                provider,
             })
                 .execute();
         }
@@ -152,7 +181,7 @@ let EnvironmentsService = class EnvironmentsService {
      * same {@link ApiError}s; a race still ends in `create`'s own refusal.
      */
     async checkCreate(orgId, accountId, name) {
-        if (!this.providers.current())
+        if (!this.providers.cloud())
             throw environmentUnavailable(null);
         const { n } = await this.db
             .selectFrom("environments")
@@ -179,9 +208,12 @@ let EnvironmentsService = class EnvironmentsService {
             .executeTakeFirstOrThrow();
         return Number(n);
     }
-    /** The refusals {@link resetFiles} would raise (not found, its provider not current), read only. */
+    /**
+     * The refusals {@link resetFiles} would raise (not found, its provider not current, a connected
+     * environment), read only.
+     */
     async checkReset(orgId, accountId, id) {
-        await this.access.usable(orgId, accountId, id);
+        refuseDeviceReset(await this.access.usable(orgId, accountId, id));
     }
     /** The refusals {@link rename} would raise, read without locks (see {@link checkCreate}). */
     async checkRename(orgId, accountId, id, name) {
@@ -228,7 +260,9 @@ let EnvironmentsService = class EnvironmentsService {
      * Deletes one of the person's live environments: soft delete, its IM default row cleared, and
      * after the commit a `sandbox-destroy-for` job (the worker waits for running commands, then
      * destroys the instance and the files). Conversations bound to it keep pointing at it; their
-     * sandbox tools then fail with `environment.not_found`.
+     * sandbox tools then fail with `environment.not_found`. A device environment's machine is
+     * revoked in the same transaction; after the commit it is told `stop { reason: "deleted" }`
+     * (while connected) and its connection is closed.
      */
     async remove(orgId, accountId, id, actorTokenId, auditDetail) {
         const before = await this.lockOwn(orgId, accountId, id);
@@ -243,6 +277,7 @@ let EnvironmentsService = class EnvironmentsService {
             .where("account_id", "=", accountId)
             .where("environment_id", "=", id)
             .execute();
+        await this.machines.revokeActive(id, "deleted");
         await audit(this.db.db, {
             actorAccountId: accountId,
             ...(actorTokenId !== undefined && { actorTokenId }),
@@ -261,12 +296,20 @@ let EnvironmentsService = class EnvironmentsService {
             }
         });
     }
+    /**
+     * Disconnects the machine of one of the person's own device environments (it must sign in
+     * again); see {@link MachinesService.revoke}.
+     */
+    async revokeMachine(orgId, accountId, id, actorTokenId) {
+        await this.machines.revoke(orgId, accountId, id, actorTokenId);
+    }
     /**
      * Starts one of the person's environments over with empty files (after
      * `environment.files_lost`): records the request (audit), then, after the commit, enqueues the
      * `sandbox-reset-files` job (deterministic id per environment), whose worker waits for running
      * commands and destroys any instance and the file system; the next use creates new ones. Its
-     * provider must be the current one (`environment.unavailable`). An enqueue failure is thrown
+     * provider must be the current one (`environment.unavailable`); a connected environment's files
+     * are its machine owner's (`environment.files_on_device`). An enqueue failure is thrown
      * (the request can be repeated: the reset is idempotent).
      */
     async resetFiles(orgId, accountId, id, actorTokenId, auditDetail) {
@@ -275,7 +318,7 @@ let EnvironmentsService = class EnvironmentsService {
     }
     /** The check and audit row of {@link resetFiles}, committed before the job is enqueued. */
     async recordReset(orgId, accountId, id, actorTokenId, auditDetail) {
-        await this.access.usable(orgId, accountId, id);
+        refuseDeviceReset(await this.access.usable(orgId, accountId, id));
         await audit(this.db.db, {
             actorAccountId: accountId,
             ...(actorTokenId !== undefined && { actorTokenId }),
@@ -307,7 +350,7 @@ let EnvironmentsService = class EnvironmentsService {
         return this.insertDefault(orgId, accountId);
     }
     async insertDefault(orgId, accountId) {
-        const current = this.providers.current();
+        const current = this.providers.cloud();
         if (!current)
             throw environmentUnavailable(null);
         await this.lockMember(orgId, accountId, "share");
@@ -439,7 +482,7 @@ let EnvironmentsService = class EnvironmentsService {
     }
     /** Its files or instance are kept by a provider that is not the current one. */
     stranded(f) {
-        const current = this.providers.current()?.plugin;
+        const current = this.providers.cloud()?.plugin;
         return current !== undefined && environmentProvider(f, current) !== current;
     }
     /** The person's live environments (or the one `id`) as views. */
@@ -447,12 +490,21 @@ let EnvironmentsService = class EnvironmentsService {
         const rows = await this.db
             .selectFrom("environments as e")
             .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .leftJoin("environment_machines as m", (j) => j.onRef("m.environment_id", "=", "e.id").on("m.revoked_at", "is", null))
             .select([
             "e.id",
             "e.name",
             "e.is_default",
+            "e.source",
             "e.provider",
             "e.created_at",
+            "m.id as machine_id",
+            "m.name as machine_name",
+            "m.os as machine_os",
+            "m.mode as machine_mode",
+            "m.program_version as machine_program_version",
+            "m.last_seen_at as machine_last_seen_at",
+            "m.session_isolation as machine_session_isolation",
             "i.provider as instance_provider",
             "i.fs_status",
             "i.handle",
@@ -471,7 +523,11 @@ let EnvironmentsService = class EnvironmentsService {
         if (rows.length === 0)
             return [];
         const limits = await this.sandbox.orgLimits(orgId);
-        const current = this.providers.current()?.plugin;
+        const current = this.providers.cloud()?.plugin;
+        // a device environment is online while a replica holds its machine's connection lease
+        const online = new Map(await Promise.all(rows
+            .filter((r) => r.source === "device")
+            .map(async (r) => [r.id, (await this.locks.holderOf(deviceLeaseKey(r.id))) !== null])));
         return rows.map((r) => {
             const provider = environmentProvider({
                 provider: r.provider,
@@ -485,10 +541,24 @@ let EnvironmentsService = class EnvironmentsService {
                 name: r.name,
                 isDefault: r.is_default,
                 ownerKind: "personal",
-                source: "cloud",
+                source: r.source,
                 provider,
-                available: current !== undefined && provider === current,
-                sessionIsolation: false,
+                available: provider !== null && isInternalProvider(provider)
+                    ? this.providers.forName(provider) !== undefined
+                    : current !== undefined && provider === current,
+                online: r.source === "device" ? (online.get(r.id) ?? false) : null,
+                machine: r.machine_id !== null && r.machine_name !== null && r.machine_os !== null
+                    ? {
+                        id: r.machine_id,
+                        name: r.machine_name,
+                        os: r.machine_os,
+                        mode: r.machine_mode,
+                        programVersion: r.machine_program_version,
+                        lastSeenAt: r.machine_last_seen_at?.toISOString() ?? null,
+                    }
+                    : null,
+                // a device environment's machine decides it; cloud environments have none in phase 2
+                sessionIsolation: r.machine_session_isolation ?? false,
                 filesLost: r.fs_status === "lost",
                 instance: live
                     ? {
@@ -560,6 +630,9 @@ let EnvironmentsService = class EnvironmentsService {
 __decorate([
     Transactional()
 ], EnvironmentsService.prototype, "insert", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "createDevice", null);
 __decorate([
     Transactional()
 ], EnvironmentsService.prototype, "renameIn", null);
@@ -581,6 +654,17 @@ EnvironmentsService = __decorate([
     __param(4, Inject(SandboxService)),
     __param(5, Inject(SandboxJobs)),
     __param(6, Inject(EnvironmentAccess)),
-    __param(7, Inject(KERNEL_LOGGER))
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, Inject(LockService)),
+    __param(9, Inject(MachinesService))
 ], EnvironmentsService);
 export { EnvironmentsService };
+/**
+ * Ruling R24: a connected environment's files are in a directory on its machine, which the
+ * platform never wipes; a lost directory comes back with `capybara-device logout` and a new `login` on the machine.
+ */
+function refuseDeviceReset(env) {
+    if (env.provider === DEVICE_PROVIDER) {
+        throw new ApiError("environment.files_on_device", "This environment's files are in a directory on its connected machine and cannot be reset from here. To start over, run capybara-device logout, then capybara-device login into this environment, on that machine.");
+    }
+}

package/dist/environments/legacy-cleanup.job.d.ts

@@ -27,7 +27,7 @@ export declare class LegacySandboxCleanupJob {
     readonly config: KernelConfigService;
     readonly lockService: LockService;
     readonly log: KernelLogger;
-    constructor(db: KernelDb, providers: Pick<SandboxProviders, "lookup">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    constructor(db: KernelDb, providers: Pick<SandboxProviders, "forName">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
     tick(signal?: AbortSignal): Promise<void>;
     /** One run (see the class); `signal` (the stop, or a lost run lock) is read between rows. */
     runOnce(now?: Date, signal?: AbortSignal): Promise<LegacyCleanupResult>;

package/dist/environments/legacy-cleanup.job.js

@@ -65,8 +65,8 @@ let LegacySandboxCleanupJob = class LegacySandboxCleanupJob {
             .select(["provider", (eb) => eb.fn.countAll().as("n")])
             .groupBy("provider")
             .execute();
-        const loaded = byProvider.filter((p) => this.providers.lookup(p.provider) !== undefined);
-        const unloaded = byProvider.filter((p) => this.providers.lookup(p.provider) === undefined);
+        const loaded = byProvider.filter((p) => this.providers.forName(p.provider) !== undefined);
+        const unloaded = byProvider.filter((p) => this.providers.forName(p.provider) === undefined);
         const kept = unloaded.reduce((sum, p) => sum + Number(p.n), 0);
         if (unloaded.length > 0 && now.getTime() % 3_600_000 < PERIOD_MS) {
             this.log.warn("legacy sandboxes kept: their provider is not loaded", {
@@ -89,7 +89,7 @@ let LegacySandboxCleanupJob = class LegacySandboxCleanupJob {
             if (signal?.aborted)
                 break;
             const name = `cap-${row.conversation_id}`;
-            const impl = this.providers.lookup(row.provider);
+            const impl = this.providers.forName(row.provider)?.impl;
             if (impl === undefined)
                 continue; // unloaded since the query: kept for a later tick
             const callSignal = () => signal
@@ -99,7 +99,7 @@ let LegacySandboxCleanupJob = class LegacySandboxCleanupJob {
                 await impl.destroyByName(name, callSignal());
                 await impl.destroyFileSystemByName(name, callSignal());
                 if (row.prev_provider !== null && row.prev_provider !== row.provider) {
-                    const prev = this.providers.lookup(row.prev_provider);
+                    const prev = this.providers.forName(row.prev_provider)?.impl;
                     if (prev !== undefined)
                         await prev.destroyByName(name, callSignal());
                     else {