@capybara-hq/kernel 0.1.0-rc.11 → 0.1.0-rc.13

package/dist/{environments/environments.service.d.ts → devices/devices.service.d.ts}

@@ -1,21 +1,21 @@
 import type { LocalizedName, SandboxLimits } from "@capybara-hq/plugin-sdk";
-import { MachinesService } from "../devices/machines.js";
 import { ExtensionDisplayNames } from "../extensions/display-name.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 { MachinesService } from "../local-devices/machines.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
 import { SandboxProviders } from "../sandbox/providers.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
-import { EnvironmentAccess } from "./access.js";
-/** An environment as its owner sees it (`GET /orgs/:orgId/environments`). */
-export interface EnvironmentView {
+import { DeviceAccess } from "./access.js";
+/** A device as its owner sees it (`GET /orgs/:orgId/devices`). */
+export interface DeviceView {
     id: string;
     /**
-     * null for the default environment (shown as 「个人环境」 / "Personal") and for a demoted default
-     * (shown as 「个人环境（Docker 沙箱）」 / "Personal (Docker sandbox)", from {@link demotedFrom}).
+     * null for the default device (shown as 「个人设备」 / "Personal") and for a demoted default
+     * (shown as 「个人设备（Docker 沙箱）」 / "Personal (Docker sandbox)", from {@link demotedFrom}).
      */
     name: string | null;
     isDefault: boolean;
@@ -24,7 +24,7 @@ export interface EnvironmentView {
      * demoted from, that extension's display name (null when it has none, e.g. uninstalled: show the
      * id), and its place among the person's unnamed former defaults of that provider (1, 2, … by
      * creation; a label shows " 2", " 3", … after the first). Switching back to that provider makes
-     * it the default again. null for every other environment.
+     * it the default again. null for every other device.
      */
     demotedFrom: {
         provider: string;
@@ -32,16 +32,16 @@ export interface EnvironmentView {
         ordinal: number;
     } | null;
     ownerKind: "personal";
-    /** `device`: a connected machine (provider `@device`). */
-    source: "cloud" | "device";
+    /** `local`: a machine connected with capybara-device (provider `@local`). */
+    source: "cloud" | "local";
     /** The provider keeping its files, or the one its first use will create them with. */
     provider: string | null;
-    /** Its provider is there: the deployment's current cloud provider, or `@device` registered. */
+    /** Its provider is there: the deployment's current cloud provider, or `@local` registered. */
     available: boolean;
-    /** A device environment: some replica holds its machine's connection now; null for cloud. */
+    /** A local device: 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;
+    /** A local device's connected machine (its unrevoked one); null for cloud or none. */
+    machine: DeviceMachineView | null;
     sessionIsolation: boolean;
     /** Its file system is gone at the provider; reset the files to use it again. */
     filesLost: boolean;
@@ -49,12 +49,12 @@ export interface EnvironmentView {
         status: "running" | "suspended";
         lastUsedAt: string;
     } | null;
-    /** The org's effective sandbox limits (phase 1 environments use them unchanged, spec §8.4). */
+    /** The org's effective sandbox limits (phase 1 devices use them unchanged, spec §8.4). */
     limits: SandboxLimits;
     createdAt: string;
 }
-/** The machine connected to a device environment, as its owner sees it. */
-export interface EnvironmentMachineView {
+/** The machine connected to a local device, as its owner sees it. */
+export interface DeviceMachineView {
     id: string;
     name: string;
     os: string;
@@ -62,24 +62,24 @@ export interface EnvironmentMachineView {
     programVersion: string | null;
     lastSeenAt: string | null;
 }
-/** The list response: the person's live environments in the org. */
-export interface EnvironmentList {
-    items: EnvironmentView[];
-    /** The person's default environment; null when there is none (no sandbox provider to make it). */
+/** The list response: the person's live devices in the org. */
+export interface DeviceList {
+    items: DeviceView[];
+    /** The person's default device; null when there is none (no sandbox provider to make it). */
     defaultId: string | null;
-    /** The environment of the person's most recently updated conversation that has a live one. */
+    /** The device of the person's most recently updated conversation that has a live one. */
     lastUsedId: string | null;
-    /** There is a current sandbox provider (new cloud environments can be made; ruling R4). */
+    /** There is a current sandbox provider (new cloud devices can be made; ruling R4). */
     cloudAvailable: boolean;
 }
 /**
- * Personal environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §6; §9):
+ * Personal devices (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
+ * person's devices in an org, visible and usable only by their owner (anyone else gets
+ * `device.not_found`). Deleting one soft-deletes it and destroys its instance and files in a
  * `sandbox-destroy-for` job after the commit.
  */
-export declare class EnvironmentsService {
+export declare class DevicesService {
     private readonly db;
     readonly txHost: TransactionHost;
     private readonly config;
@@ -92,39 +92,39 @@ export declare class EnvironmentsService {
     /** 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">, displayNames: Pick<ExtensionDisplayNames, "many">, log: Pick<KernelLogger, "warn">, 
+    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<DeviceAccess, "usable">, displayNames: Pick<ExtensionDisplayNames, "many">, 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,
+     * The person's live devices in the org, the default first, then by creation. With a
+     * current sandbox provider the default device is created first if missing (its first need,
      * spec §4.2 item 7; an existing one is only read).
      */
-    list(orgId: string, accountId: string): Promise<EnvironmentList>;
-    /** One of the person's live environments; anyone else's (or a missing one) → `not_found`. */
-    get(orgId: string, accountId: string, id: string): Promise<EnvironmentView>;
+    list(orgId: string, accountId: string): Promise<DeviceList>;
+    /** One of the person's live devices; anyone else's (or a missing one) → `not_found`. */
+    get(orgId: string, accountId: string, id: string): Promise<DeviceView>;
     /**
-     * A new personal cloud environment, ready at once (its instance and files are made on first
-     * use). Needs a current sandbox provider (`environment.unavailable`); a live name of the person's
-     * (case-insensitive) → `environment.name_taken`; `environments.maxPersonal` live ones (the
-     * default counts) → `environment.limit_reached`. Serialized per person by their membership row.
+     * A new personal cloud device, ready at once (its instance and files are made on first
+     * use). Needs a current sandbox provider (`device.unavailable`); a live name of the person's
+     * (case-insensitive) → `device.name_taken`; `devices.maxPersonal` live ones (the
+     * default counts) → `device.limit_reached`. Serialized per person by their membership row.
      */
     create(orgId: string, accountId: string, input: {
         name: string;
-    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<EnvironmentView>;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<DeviceView>;
     private insert;
     /**
-     * A new personal `device` environment for a machine being connected (provider `@device`; the
+     * A new personal local device for a machine being connected (provider `@local`; 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.
+     * Counted against `devices.maxPersonal` (`device.limit_reached`); a live name of the
+     * person's → `device.name_taken`. Needs no cloud provider.
      */
-    createDevice(orgId: string, accountId: string, name: string): Promise<{
+    createLocal(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.
+     * Inserts a named personal device under the person's membership lock, after the limit
+     * and name checks, and audits `device.created`. Runs in the caller's transaction.
      */
     private insertNamed;
     /**
@@ -133,54 +133,54 @@ export declare class EnvironmentsService {
      * same {@link ApiError}s; a race still ends in `create`'s own refusal.
      */
     checkCreate(orgId: string, accountId: string, name: string): Promise<void>;
-    /** How many of the person's conversations work in the environment (read only). */
+    /** How many of the person's conversations work in the device (read only). */
     boundConversations(orgId: string, accountId: string, id: string): Promise<number>;
     /**
      * The refusals {@link resetFiles} would raise (not found, its provider not current, a connected
-     * environment), read only.
+     * device), 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>;
     /**
-     * Renames one of the person's live environments (the default too); see {@link create}. A
+     * Renames one of the person's live devices (the default too); see {@link create}. A
      * renamed former default is the person's own from then on: it loses its demotion mark, so a
      * switch back to its provider no longer restores it.
      */
-    rename(orgId: string, accountId: string, id: string, name: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<EnvironmentView>;
+    rename(orgId: string, accountId: string, id: string, name: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<DeviceView>;
     private renameIn;
     /**
-     * Deletes one of the person's live environments: soft delete, its IM default row cleared, and
+     * Deletes one of the person's live devices: 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`. A device environment's machine is
+     * sandbox tools then fail with `device.not_found`. A local device'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
+     * Disconnects the machine of one of the person's own local devices (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
+     * Starts one of the person's devices over with empty files (after
+     * `device.files_lost`): records the request (audit), then, after the commit, enqueues the
+     * `sandbox-reset-files` job (deterministic id per device), 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`); a connected environment's files
-     * are its machine owner's (`environment.files_on_device`). An enqueue failure is thrown
+     * provider must be the current one (`device.unavailable`); a local device's files
+     * are its machine owner's (`device.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>;
     /** The check and audit row of {@link resetFiles}, committed before the job is enqueued. */
     private recordReset;
     /**
-     * The person's default environment in the org, created when missing (named by the UI, `name`
+     * The person's default device in the org, created when missing (named by the UI, `name`
      * NULL). An existing usable one is read without locking. A live default whose files or
      * instance are kept by a provider that is not the current one (a provider switch, spec §4.2
      * item 13) is stranded: it is demoted (marked with the provider it was demoted from; the UI
-     * names it 「个人环境（<provider display name>）」) and stays listed as unavailable and deletable.
+     * names it 「个人设备（<provider display name>）」) and stays listed as unavailable and deletable.
      * Its replacement is the person's former default demoted from the current provider when there
      * is one (switching back restores it, with its files), else a fresh default. A live default
      * not in use yet (no healthy files, no instance, none being created: {@link inUseForDefault})
@@ -189,7 +189,7 @@ export declare class EnvironmentsService {
      * belongs to the provider holding its resources once it holds any, else to the one it was
      * demoted from ({@link demotedProvider}), so one swapped out empty and used afterwards is
      * labelled and restored by where its files are.
-     * All of it in one transaction: switching back and forth never adds environments.
+     * All of it in one transaction: switching back and forth never adds devices.
      *
      * Replacing one first takes the person's membership row (`FOR SHARE`, after the org row), so an
      * offboarding that removes them cannot leave a live default behind; not a member (any more) →
@@ -197,13 +197,13 @@ export declare class EnvironmentsService {
      * defaults of the current provider are locked (`FOR NO KEY UPDATE`) and the live default re-read
      * after them, the partial unique index on the live default makes a racing insert do nothing, and
      * the select that follows reads the winner. Needs a current sandbox provider
-     * (`environment.unavailable`). It is the person's baseline, so it is created even at
-     * `environments.maxPersonal`.
+     * (`device.unavailable`). It is the person's baseline, so it is created even at
+     * `devices.maxPersonal`.
      */
     ensureDefault(orgId: string, accountId: string): Promise<string>;
     private insertDefault;
     /**
-     * Turns the live default into an ordinary environment marked as demoted from `provider`; a name
+     * Turns the live default into an ordinary device marked as demoted from `provider`; a name
      * the person gave it stays. Runs under the person's membership lock and the default row's lock,
      * before any other row becomes the default (the partial unique index).
      */
@@ -217,35 +217,35 @@ export declare class EnvironmentsService {
      */
     private formerDefaults;
     /**
-     * The person's IM default (what `/env` set): the environment their next new IM conversation
+     * The person's IM default (what `/device` set): the device their next new IM conversation
      * uses. Null when none was set, or the chosen one is deleted (the row is cleared with it).
      */
     imDefault(orgId: string, accountId: string): Promise<string | null>;
     /**
-     * Sets the person's IM default. Only one of their own live environments in the org, usable now
-     * (`environment.not_found` / `environment.unavailable` otherwise); the row is written by one
-     * statement that re-checks the environment is live. There is no row lock, so a delete racing
+     * Sets the person's IM default. Only one of their own live devices in the org, usable now
+     * (`device.not_found` / `device.unavailable` otherwise); the row is written by one
+     * statement that re-checks the device is live. There is no row lock, so a delete racing
      * past that check can leave a stale row; reads ignore it ({@link imDefault} joins on
      * `deleted_at IS NULL`).
      */
-    setImDefault(orgId: string, accountId: string, environmentId: string): Promise<void>;
+    setImDefault(orgId: string, accountId: string, deviceId: string): Promise<void>;
     /**
-     * The person's live default environment in the org, if any, with what decides its provider;
+     * The person's live default device in the org, if any, with what decides its provider;
      * `lock` takes its row (`FOR NO KEY UPDATE`; a racing demotion makes it read none).
      */
     private defaultOf;
     /** Its files or instance are kept by a provider that is not the current one. */
     private stranded;
-    /** The person's live environments (or the one `id`) as views. */
+    /** The person's live devices (or the one `id`) as views. */
     private views;
     /**
-     * Serializes the person's environment writes in the org: the org row (`FOR SHARE`), then their
+     * Serializes the person's device writes in the org: the org row (`FOR SHARE`), then their
      * membership row (`FOR NO KEY UPDATE`, or `FOR SHARE` with `mode` share: enough to keep the
      * membership from being removed meanwhile), the order member removal locks them in. Not a
      * member (any more) → `org.not_found`, as the org guard answers.
      */
     private lockMember;
-    /** Locks one of the person's live environments (after their membership); else `not_found`. */
+    /** Locks one of the person's live devices (after their membership); else `not_found`. */
     private lockOwn;
     private assertNameFree;
 }