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

package/dist/sandbox/sandbox.service.d.ts

@@ -3,7 +3,7 @@ import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
 import { type KernelConfig } from "../config/schema.js";
-import type { EnvironmentInstancesTable } from "../db/kernel-schema.js";
+import type { DeviceInstancesTable } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -16,13 +16,13 @@ export interface SandboxUseInfo {
     /** This call created the instance (first use, or a rebuild). */
     fresh: boolean;
     /**
-     * The environment had an instance before that is no longer there (destroyed after inactivity,
+     * The device had an instance before that is no longer there (destroyed after inactivity,
      * gone at the provider, or rebuilt by another holder since this holder last used it): this is a
      * new instance on the kept files, so earlier processes are gone.
      */
     restarted: boolean;
     /**
-     * The environment's files were reset since this holder last used it (on request, or after they
+     * The device's files were reset since this holder last used it (on request, or after they
      * were lost): earlier files are gone too. Set only when true; `restarted` is then false.
      */
     filesReset?: true;
@@ -35,17 +35,17 @@ export interface SandboxUseInfo {
 /** Who uses the sandbox in {@link SandboxService.withSandbox}. */
 export interface SandboxUseContext {
     orgId: string;
-    environmentId: string;
+    deviceId: string;
     /** The agent conversation using it (a sub-agent's own for a child): what it last saw is tracked. */
     holderConversationId: string;
     /** Passed with every `exec` (audit and attribution). */
     actor: SandboxActor;
 }
 export type { SandboxProviderEntry } from "./providers.js";
-type Row = Selectable<EnvironmentInstancesTable>;
+type Row = Selectable<DeviceInstancesTable>;
 type ExecArgs = Parameters<SandboxProvider["exec"]>[1];
 /**
- * One instance of an environment: its handle and the row's `created_at`, which the fenced write
+ * One instance of a device: its handle and the row's `created_at`, which the fenced write
  * after every `create` sets. The handle alone is not enough: sandbox-docker's handle is the
  * instance name, the same after a rebuild (spec §10.10).
  */
@@ -80,20 +80,20 @@ export type IfRunningResult<T> = {
     kind: "not_running";
     status: Row["status"] | "gone";
 }
-/** The environment now records another instance (a rebuild). */
+/** The device now records another instance (a rebuild). */
  | {
     kind: "other_instance";
 };
-/** The provider-side name of an environment's file system and instance. */
-export declare const environmentResourceName: (environmentId: string) => string;
-/** The environment is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
-export declare const environmentNotFound: () => ApiError;
+/** The provider-side name of a device's file system and instance. */
+export declare const deviceResourceName: (deviceId: string) => string;
+/** The device is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
+export declare const deviceNotFound: () => ApiError;
 /**
- * The environment's file system is gone at the provider (409); never replaced silently. On a
- * connected machine (`device`, details `[{ source: "device" }]`) the directory is the machine
- * owner's: `capybara-device logout`, then `login` into the environment, recreates it (ruling R24).
+ * The device's file system is gone at the provider (409); never replaced silently. On a
+ * connected machine (`local`, details `[{ source: "local" }]`) the directory is the machine
+ * owner's: `capybara-device logout`, then `login` into the device, recreates it (ruling R24).
  */
-export declare const environmentFilesLost: (device?: boolean) => ApiError;
+export declare const deviceFilesLost: (local?: boolean) => ApiError;
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -115,19 +115,19 @@ export declare function sandboxConfigWarnings(cfg: Pick<KernelConfig, "runtime"
 /** No sandbox provider (503). */
 export declare const sandboxUnavailable: () => ApiError;
 /**
- * The kernel's sandbox service over the `sandbox@2` provider, keyed by **environment** (spec
- * 2026-11-07-environments-design §4.2, §5.1): one file system kept until the environment is
+ * The kernel's sandbox service over the `sandbox@2` provider, keyed by **device** (spec
+ * 2026-11-07-environments-design §4.2, §5.1): one file system kept until the device is
  * deleted, plus one instance attached to it that comes and goes; all conversations bound to the
- * environment (and their sub-agents) share both.
+ * device (and their sub-agents) share both.
  *
  * - **Lazy creation**: the first {@link withSandbox} creates the file system
- *   (`createFileSystem`, name `cap-env-<environmentId>`) and then the instance on it; state lives
- *   in `environment_instances`. A file system gone at the provider is never replaced silently:
- *   `fs_status` becomes `lost` and uses fail with `environment.files_lost` until
+ *   (`createFileSystem`, name `cap-device-<deviceId>`) and then the instance on it; state lives
+ *   in `device_instances`. A file system gone at the provider is never replaced silently:
+ *   `fs_status` becomes `lost` and uses fail with `device.files_lost` until
  *   {@link resetFileSystem}.
- * - **Leases** (phase C, spec §10, {@link SandboxLeases}), keyed by environment id: using an
+ * - **Leases** (phase C, spec §10, {@link SandboxLeases}), keyed by device id: using an
  *   instance recorded `running` with the current provider takes a **shared** lease, so up to
- *   `sandbox.maxConcurrentCommands` holders (all sessions of the environment) run at once. Every
+ *   `sandbox.maxConcurrentCommands` holders (all sessions of the device) run at once. Every
  *   lifecycle change (create, resume, rebuild, suspend, destroy, reset) takes the **exclusive**
  *   lease, alone; a caller that needs one on the use path sets the intent so new shared leases wait
  *   for it, and downgrades to a shared lease to run its own command once the instance runs.
@@ -140,9 +140,9 @@ export declare const sandboxUnavailable: () => ApiError;
  *   provider calls.
  * - **Suspension and destruction**: the sweeps (`SandboxSweepJobs`, crons) call
  *   {@link suspendIdle} / {@link destroyInactive}; they try the exclusive lease once and skip an
- *   environment with any holder; one past `maxRunningMinutes` gets the intent for a short window
+ *   device with any holder; one past `maxRunningMinutes` gets the intent for a short window
  *   (about a second) so the suspension can get in when its commands end. Inactivity destroys only
- *   the instance (files kept); a deleted environment or org loses its files too.
+ *   the instance (files kept); a deleted device or org loses its files too.
  * - **Transparent recovery**: a suspended instance is resumed on next use; when `resume` returns
  *   `gone`, the instance was destroyed, or `fn` throws `SandboxGoneError` (retried once), a new
  *   instance is created on the kept files and `restarted` is true. Several holders hitting `gone`
@@ -150,7 +150,7 @@ export declare const sandboxUnavailable: () => ApiError;
  * - **Takeover** (spec §10.5; environments spec §4.2): every holder records itself in
  *   `capk:sandbox-holders:<env>` (again before each `exec`) and its commands carry its lease token
  *   as `tag`. An acquirer that finds a record without a live lease (a crashed holder) kills only
- *   that holder's commands (`killTagged`): other conversations of the environment may be running
+ *   that holder's commands (`killTagged`): other conversations of the device may be running
  *   commands. `killAll` runs only under the exclusive lease, before the downgrade, on an instance
  *   this holder just resumed from `suspended` (nobody else can hold it; a provider that keeps
  *   memory across a pause brings old commands back); it also covers crashed holders' records,
@@ -160,16 +160,16 @@ export declare const sandboxUnavailable: () => ApiError;
  *   row's `created_at` (set by the fenced write after each `create`); the handle alone is the same
  *   after a rebuild on providers whose handle is the instance name (sandbox-docker).
  *
- * - **Provider per environment** (environments spec §6): each call resolves the provider from
- *   the environment's `environments.provider` ({@link providerForEnvironment}): a `device`
- *   environment runs on the kernel-internal `@device` provider (never the cloud one), a cloud
- *   environment on the loaded `sandbox@2` extension. A `@device` instance is never suspended or
- *   destroyed for inactivity; a deleted `@device` environment (or one of a deleted org) is
+ * - **Provider per device** (environments spec §6): each call resolves the provider from
+ *   the device's `devices.provider` ({@link providerForDevice}): a `device`
+ *   device runs on the kernel-internal `@local` provider (never the cloud one), a cloud
+ *   device on the loaded `sandbox@2` extension. A `@local` instance is never suspended or
+ *   destroyed for inactivity; a deleted `@local` device (or one of a deleted org) is
  *   destroyed by the sweep like any other.
  *
- * Files kept by another provider than the current one make the environment unusable
- * (`environment.unavailable`) until that provider is back; deleting it still works while that
- * provider is loaded ({@link SandboxProviders.forName}). Without the environment's provider
+ * Files kept by another provider than the current one make the device unusable
+ * (`device.unavailable`) until that provider is back; deleting it still works while that
+ * provider is loaded ({@link SandboxProviders.forName}). Without the device's provider
  * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
  * replicas share it through PG and Redis.
  */
@@ -195,48 +195,48 @@ export declare class SandboxService {
     private get pollMs();
     /**
      * Whether there is a cloud sandbox provider (a loaded `sandbox@2` extension). For gates that have
-     * no environment yet (tool listing, skill files); a call on an environment asks
+     * no device yet (tool listing, skill files); a call on a device asks
      * {@link availableFor}.
      */
     get cloudAvailable(): boolean;
-    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
-    availableFor(environmentId: string): Promise<boolean>;
+    /** Whether the device's provider is there (`@local` registered, or a cloud provider). */
+    availableFor(deviceId: string): Promise<boolean>;
     /**
-     * The provider the environment works with, read from its row ({@link providerForEnvironment});
-     * a missing row (or one of another org, with `orgId`) reads as a cloud environment, whose use
+     * The provider the device works with, read from its row ({@link providerForDevice});
+     * a missing row (or one of another org, with `orgId`) reads as a cloud device, whose use
      * then fails as not found.
      */
     private providerOf;
     /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
     private require;
-    /** Concurrent holders of one environment (`sandbox.maxConcurrentCommands`, read at every use). */
+    /** Concurrent holders of one device (`sandbox.maxConcurrentCommands`, read at every use). */
     private get cap();
     /**
      * The org's effective sandbox limits (spec §8.4): the deployment's `sandbox.limits`, egress
      * narrowed by the org setting `sandboxEgress` (Ruling M19), cpu / memory per the super admin's
-     * org override (C19 / Ruling M16). Instances are created with them; phase 1 environments use
+     * org override (C19 / Ruling M16). Instances are created with them; phase 1 devices use
      * them unchanged.
      */
     orgLimits(orgId: string): Promise<SandboxLimits>;
     /**
-     * The environment's instance state as shown to people (read only, no lease): `running` /
+     * The device's instance state as shown to people (read only, no lease): `running` /
      * `suspended` and the last use. No instance, a destroyed one, or one stuck in `creating` (being
      * created, or a failed create the next use retries) is null.
      */
-    status(orgId: string, environmentId: string): Promise<{
+    status(orgId: string, deviceId: string): Promise<{
         status: "running" | "suspended";
         lastUsedAt: Date;
     } | null>;
     /**
-     * The instance the environment records now (its `created_at`), while it has one that runs or is
+     * The instance the device records now (its `created_at`), while it has one that runs or is
      * suspended; null otherwise. Read without a lease: a caller inside `withSandbox` reads the
      * instance its own lease keeps.
      */
-    currentInstance(environmentId: string): Promise<{
+    currentInstance(deviceId: string): Promise<{
         createdAt: Date;
     } | null>;
     /**
-     * Runs `fn` on the environment's instance only while it runs the instance created at
+     * Runs `fn` on the device's instance only while it runs the instance created at
      * `instance.createdAt` (background tasks, spec 2026-11-05-background-bash-design §4.3). It never
      * creates, resumes or rebuilds one: an instance that is missing, suspended, being created or
      * destroyed (or recorded with another provider) is `not_running`, one that records another
@@ -247,17 +247,17 @@ export declare class SandboxService {
      * to `fn` aborts with `signal` or when the lease is lost. Errors of `fn` (`SandboxGoneError`
      * too) are thrown as they are.
      */
-    ifRunning<T>(environmentId: string, instance: {
+    ifRunning<T>(deviceId: string, instance: {
         createdAt: Date;
     }, fn: (p: TaggedProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<IfRunningResult<T>>;
     /**
-     * A short lease on one path of the environment around the kernel's own read-modify-write of
+     * A short lease on one path of the device around the kernel's own read-modify-write of
      * that file (spec §10.4); waits up to 30 s, then throws `SandboxPathBusyError`. Its `signal`
      * aborts when a renewal finds it lost.
      */
-    pathLease(environmentId: string, path: string, signal: AbortSignal): Promise<SandboxPathLease>;
+    pathLease(deviceId: string, path: string, signal: AbortSignal): Promise<SandboxPathLease>;
     /**
-     * Runs `fn` on the environment's instance: take a lease → make sure the instance runs (file
+     * Runs `fn` on the device's instance: take a lease → make sure the instance runs (file
      * system, create / resume / rebuild, under the exclusive lease) → `fn` under a shared lease →
      * update `last_used_at` → release.
      * - Waiting longer than `sandbox.lockWaitSeconds` throws `sandbox.busy` (409); `signal` aborts
@@ -268,7 +268,7 @@ export declare class SandboxService {
      * - When `fn` throws `SandboxGoneError` (the instance is gone) the instance is rebuilt on the
      *   kept files (or the one another holder rebuilt is taken) and `fn` runs once more with
      *   `restarted: true`; a second `gone` is thrown. Other errors are thrown as they are.
-     * - Lost files throw `environment.files_lost` (409), also when `fn` throws
+     * - Lost files throw `device.files_lost` (409), also when `fn` throws
      *   `FileSystemGoneError` (the files are then recorded lost, ruling R24).
      * - When `ctx.holderConversationId` last used another instance (another holder rebuilt it
      *   meanwhile), `info.restarted` is true, so it learns its processes are gone (final review m5).
@@ -278,7 +278,7 @@ export declare class SandboxService {
      * Ruling R24: an operation on the held instance `e` found its file system gone. Records
      * `fs_status = 'lost'` while the row still records that instance on its file system (the
      * instance handle stays, so a reset still destroys it), moving the fence on, and returns
-     * `environment.files_lost` to throw. Uses then fail until the files are reset (a connected
+     * `device.files_lost` to throw. Uses then fail until the files are reset (a connected
      * machine: until a new login, which resets the row). A failed write only logs.
      */
     private filesGone;
@@ -288,7 +288,7 @@ export declare class SandboxService {
      * holder last used another instance under the same reset count `e` is marked restarted (files
      * kept); under another count it is marked `filesReset` instead. The count, not the provider's
      * file system id, tells them apart: a provider may give the new file system the old id
-     * (sandbox-docker's volumes are named after the environment). Best effort: a Redis error only
+     * (sandbox-docker's volumes are named after the device). Best effort: a Redis error only
      * logs.
      */
     private seenBy;
@@ -335,7 +335,7 @@ export declare class SandboxService {
     private kill;
     /**
      * Suspends running instances idle longer than `suspendAfterIdleMinutes` or running continuously
-     * longer than `maxRunningMinutes`. Skips an environment with any holder; one past
+     * longer than `maxRunningMinutes`. Skips a device with any holder; one past
      * `maxRunningMinutes` gets the intent for one poll window (about a second) first. Returns how
      * many it suspended. Called every minute by the `sandbox-suspend-idle` cron.
      */
@@ -343,30 +343,30 @@ export declare class SandboxService {
     /**
      * Destruction sweep: an instance unused for longer than `destroyAfterInactiveDays` is destroyed
      * (the instance only; the file system is kept and the next use builds a new instance on it); an
-     * environment that was deleted, or whose org was deleted, loses its instance and its file system
-     * and its row is deleted (as {@link destroyEnvironment} does). Environments with any holder are
-     * skipped. Inactivity never destroys a `@device` instance; a gone `@device` environment is
-     * destroyed like any other while `@device` is registered. Returns how many it destroyed. Called
+     * device that was deleted, or whose org was deleted, loses its instance and its file system
+     * and its row is deleted (as {@link destroyDevice} does). Devices with any holder are
+     * skipped. Inactivity never destroys a `@local` instance; a gone `@local` device is
+     * destroyed like any other while `@local` is registered. Returns how many it destroyed. Called
      * hourly by the `sandbox-destroy-inactive` cron.
      */
     destroyInactive(now: Date): Promise<number>;
     /**
-     * Destroys the environment's instance, then its file system, then deletes its instance row
-     * (environment deletion, offboarding); nothing to do without a row. Waits for the exclusive lease
+     * Destroys the device's instance, then its file system, then deletes its instance row
+     * (device deletion, offboarding); nothing to do without a row. Waits for the exclusive lease
      * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without the
-     * environment's provider it throws and the row stays, marked `sweep_failed_at` (the job is
-     * retried, and the destruction sweep finishes a deleted environment once the provider is back).
+     * device's provider it throws and the row stays, marked `sweep_failed_at` (the job is
+     * retried, and the destruction sweep finishes a deleted device once the provider is back).
      * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
      * stays.
      */
-    destroyEnvironment(environmentId: string): Promise<void>;
+    destroyDevice(deviceId: string): Promise<void>;
     /**
-     * Starts the environment over with empty files (after `environment.files_lost`, or on request):
-     * under the exclusive lease (waited for like {@link destroyEnvironment}) destroys any instance and
+     * Starts the device over with empty files (after `device.files_lost`, or on request):
+     * under the exclusive lease (waited for like {@link destroyDevice}) destroys any instance and
      * the file system (a `lost` one is only dropped), and records no file system; the next use
      * creates a new one. Nothing to do without a row. Throws `sandbox.unavailable` without a provider.
      */
-    resetFileSystem(environmentId: string): Promise<void>;
+    resetFileSystem(deviceId: string): Promise<void>;
     /**
      * Under the exclusive lease (before the downgrade), on an instance just resumed from
      * `suspended`: kills every command left in it (`killAll`), crashed holders' (`dead`, already
@@ -392,13 +392,13 @@ export declare class SandboxService {
     private candidates;
     /**
      * One try at the exclusive lease: null → false; else runs `fn`. With `overdue` (past
-     * `maxRunningMinutes`) a busy environment gets the intent for about a second, so new commands
+     * `maxRunningMinutes`) a busy device gets the intent for about a second, so new commands
      * wait briefly and the sweep gets in if the running ones end. Failures are warned, recorded in
      * `sweep_failed_at` (sorted last next time) and return false.
      */
     private tryLocked;
     /**
-     * Under the exclusive lease: make the environment's instance run. `gone`: the instance a holder
+     * Under the exclusive lease: make the device's instance run. `gone`: the instance a holder
      * found gone; when it is still the recorded one it is rebuilt, when another holder already
      * rebuilt it the new one is used.
      */
@@ -407,14 +407,14 @@ export declare class SandboxService {
      * Under the lease: fenced reset to `creating`, the file system when there is none
      * (`createFileSystem`, its handle written fenced), then the instance on it, then a fenced write
      * of the instance handle. `FileSystemGoneError` from `create` records `fs_status = 'lost'` and
-     * throws `environment.files_lost`. When the instance handle cannot be written (lease lost), the
+     * throws `device.files_lost`. When the instance handle cannot be written (lease lost), the
      * new instance is destroyed (best effort) before {@link SandboxLockLostError} is thrown.
      */
     private create;
     /**
-     * Destroys the file system another provider may have made under the environment's name without
+     * Destroys the file system another provider may have made under the device's name without
      * the kernel recording it (`destroyFileSystemByName`; not there is success). That provider not
-     * loaded, or a failure, is only warned (the files may leak there) so the environment stays
+     * loaded, or a failure, is only warned (the files may leak there) so the device stays
      * usable; an abort is thrown.
      */
     private dropUnrecordedFiles;
@@ -438,20 +438,20 @@ export declare class SandboxService {
     private destroyFiles;
     /**
      * Under the lease: `instance` destroys the instance and marks the row `destroyed` (the file
-     * system stays); `environment` also destroys the file system and deletes the row.
+     * system stays); `device` also destroys the file system and deletes the row.
      */
     private destroyRow;
     /** Due for suspension: made by this provider, running, and idle or running for too long. */
     private suspendDue;
-    /** The provider of an instance row: an internal one (`@device`) by name, else the cloud one. */
+    /** The provider of an instance row: an internal one (`@local`) by name, else the cloud one. */
     private rowProvider;
     /**
-     * A row the idle sweeps may touch: not on a kernel-internal provider (`@device` instances live on
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@local` instances live on
      * people's machines and are never suspended or destroyed for inactivity).
      */
     private cloudRow;
-    /** The environment was deleted, or its org was: the instance and the files go. */
-    private environmentGone;
+    /** The device was deleted, or its org was: the instance and the files go. */
+    private deviceGone;
     /** Due for instance destruction: an instance (or a create in progress) unused for too long. */
     private instanceDue;
 }