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

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

@@ -1,4 +1,4 @@
-import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider, type SandboxRoots } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
@@ -21,6 +21,11 @@ export interface SandboxUseInfo {
      * new instance on the kept files, so earlier processes are gone.
      */
     restarted: boolean;
+    /**
+     * The instance's roots ({@link rootsOf} of its handle): every model-visible path is built from
+     * them (environments spec §13.1; a connected machine's real paths).
+     */
+    roots: SandboxRoots;
 }
 /** Who uses the sandbox in {@link SandboxService.withSandbox}. */
 export interface SandboxUseContext {
@@ -78,8 +83,12 @@ export type IfRunningResult<T> = {
 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 environment's file system is gone at the provider (409); never replaced silently. */
-export declare const environmentFilesLost: () => 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).
+ */
+export declare const environmentFilesLost: (device?: 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).
@@ -146,18 +155,25 @@ 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
+ *   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.lookup}). Without a provider {@link available} is false and
- * uses throw `sandbox.unavailable` (503). No in-process state: replicas share it through PG and
- * Redis.
+ * provider is loaded ({@link SandboxProviders.forName}). Without the environment's provider
+ * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
+ * replicas share it through PG and Redis.
  */
 export declare class SandboxService {
     private readonly db;
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     private readonly redis;
     private readonly leases;
-    /** The `sandbox@2` provider (read at every call: providers are ready after the extension load). */
+    /** The providers (read at every call: providers are ready after the extension load). */
     private readonly providers;
     private readonly config;
     private readonly log;
@@ -166,14 +182,28 @@ export declare class SandboxService {
     constructor(db: KernelDb, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis: Pick<Redis, "set">, leases: SandboxLeases, 
-    /** The `sandbox@2` provider (read at every call: providers are ready after the extension load). */
-    providers: Pick<SandboxProviders, "current" | "lookup">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
+    /** The providers (read at every call: providers are ready after the extension load). */
+    providers: Pick<SandboxProviders, "cloud" | "forName">, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "info" | "warn">, 
     /** Background tasks lost while their process may live on (killed after a resume). */
     background: Pick<BackgroundTaskStore, "pendingKills" | "clearKill">);
     /** Poll interval while waiting for a lease (the leases' own). */
     private get pollMs();
-    /** Whether there is a sandbox provider. */
-    get available(): boolean;
+    /**
+     * 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
+     * {@link availableFor}.
+     */
+    get cloudAvailable(): boolean;
+    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
+    availableFor(environmentId: 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
+     * 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). */
     private get cap();
     /**
@@ -233,11 +263,20 @@ 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).
+     * - Lost files throw `environment.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).
      */
     withSandbox<T>(ctx: SandboxUseContext, fn: (h: SandboxHandle, p: HeldProvider, info: SandboxUseInfo, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<T>;
+    /**
+     * 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
+     * machine: until a new login, which resets the row). A failed write only logs.
+     */
+    private filesGone;
     /**
      * Records that `holder` uses the instance of `e` (`capk:sandbox-seen:<env>:<holder>` =
      * `<created_at>:<file system id>`, with a TTL of the inactivity destruction plus a day). When the
@@ -258,7 +297,10 @@ export declare class SandboxService {
     private readRow;
     /** The instance row belongs to another org: reported as not found, so ids cannot be probed. */
     private foreign;
-    /** Recorded running with the current provider, and not the instance found gone. */
+    /**
+     * Recorded running with the current provider on files not lost (lost ones go through the
+     * exclusive path, which refuses them), and not the instance found gone.
+     */
     private usable;
     /**
      * Under a just-taken shared lease: confirms the row is still `accept`ed (else releases and
@@ -295,15 +337,19 @@ export declare class SandboxService {
      * (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. Returns how many it destroyed. Called hourly by the `sandbox-destroy-inactive` cron.
+     * 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
+     * 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
-     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without a
-     * provider it only warns (the destruction sweep finishes a deleted environment later). Files kept
-     * by another provider that is not loaded cannot be destroyed: it throws and the row stays.
+     * (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).
+     * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
+     * stays.
      */
     destroyEnvironment(environmentId: string): Promise<void>;
     /**
@@ -329,7 +375,6 @@ export declare class SandboxService {
      * and leaves the flags of this instance's tasks for the next resume.
      */
     private killPendingTasks;
-    private require;
     /**
      * A fenced write: only while the lease holds and the row's generation is still the one read
      * under it (and incremented); otherwise {@link SandboxLockLostError}.
@@ -390,6 +435,13 @@ export declare class SandboxService {
     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. */
+    private rowProvider;
+    /**
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@device` 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;
     /** Due for instance destruction: an instance (or a create in progress) unused for too long. */

package/dist/sandbox/sandbox.service.js

@@ -8,7 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { isFileSystemGoneError, isSandboxGoneError, } from "@capybara-hq/plugin-sdk";
+import { isFileSystemGoneError, isSandboxGoneError, rootsOf, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql, } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
@@ -21,7 +21,7 @@ import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { effectiveSandboxEgress, effectiveSandboxLimits, readOrgSettings, } from "../orgs/settings.service.js";
 import { canonicalJson } from "../tools/canonical-json.js";
 import { SandboxLeases, SandboxLockLostError, sandboxBusy, } from "./leases.js";
-import { SandboxProviders } from "./providers.js";
+import { DEVICE_PROVIDER, providerForEnvironment, SandboxProviders, } from "./providers.js";
 // Moved to leases.ts (phase C); re-exported for existing importers
 export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
 /** Margin (ms) of a holder record's TTL beyond the longest command: by then the in-sandbox limit has ended its commands. */
@@ -47,8 +47,14 @@ const opSignal = (lease) => AbortSignal.any([lease.signal, AbortSignal.timeout(S
 export const environmentResourceName = (environmentId) => `cap-env-${environmentId}`;
 /** The environment is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
 export const environmentNotFound = () => new ApiError("environment.not_found", "This environment does not exist or was deleted.");
-/** The environment's file system is gone at the provider (409); never replaced silently. */
-export const environmentFilesLost = () => new ApiError("environment.files_lost", "The environment's files are gone; reset its files from the environments page to start with an empty workspace.");
+/**
+ * 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).
+ */
+export const environmentFilesLost = (device = false) => device
+    ? new ApiError("environment.files_lost", "The environment's directory is gone from its connected machine; run capybara-device logout, then capybara-device login into this environment, on that machine to recreate it.", [{ source: "device" }])
+    : new ApiError("environment.files_lost", "The environment's files are gone; reset its files from the environments page to start with an empty workspace.");
 /**
  * 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).
@@ -185,11 +191,18 @@ async function inPool(items, limit, fn) {
  *   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
+ *   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.lookup}). Without a provider {@link available} is false and
- * uses throw `sandbox.unavailable` (503). No in-process state: replicas share it through PG and
- * Redis.
+ * provider is loaded ({@link SandboxProviders.forName}). Without the environment's provider
+ * {@link availableFor} is false and uses throw `sandbox.unavailable` (503). No in-process state:
+ * replicas share it through PG and Redis.
  */
 let SandboxService = class SandboxService {
     db;
@@ -202,7 +215,7 @@ let SandboxService = class SandboxService {
     constructor(db, 
     /** The record of the instance each holder last used (`capk:sandbox-seen:…`). */
     redis, leases, 
-    /** The `sandbox@2` provider (read at every call: providers are ready after the extension load). */
+    /** The providers (read at every call: providers are ready after the extension load). */
     providers, config, log, 
     /** Background tasks lost while their process may live on (killed after a resume). */
     background) {
@@ -218,9 +231,38 @@ let SandboxService = class SandboxService {
     get pollMs() {
         return this.leases.pollMs;
     }
-    /** Whether there is a sandbox provider. */
-    get available() {
-        return this.providers.current() !== undefined;
+    /**
+     * 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
+     * {@link availableFor}.
+     */
+    get cloudAvailable() {
+        return this.providers.cloud() !== undefined;
+    }
+    /** Whether the environment's provider is there (`@device` registered, or a cloud provider). */
+    async availableFor(environmentId) {
+        return (await this.providerOf(environmentId)) !== undefined;
+    }
+    /**
+     * 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
+     * then fails as not found.
+     */
+    async providerOf(environmentId, orgId) {
+        const row = await this.db
+            .selectFrom("environments")
+            .select("provider")
+            .where("id", "=", environmentId)
+            .$if(orgId !== undefined, (q) => q.where("org_id", "=", orgId))
+            .executeTakeFirst();
+        return providerForEnvironment(this.providers, row?.provider ?? null);
+    }
+    /** {@link providerOf}, or `sandbox.unavailable` (503) without it. */
+    async require(environmentId, orgId) {
+        const p = await this.providerOf(environmentId, orgId);
+        if (!p)
+            throw sandboxUnavailable();
+        return p;
     }
     /** Concurrent holders of one environment (`sandbox.maxConcurrentCommands`, read at every use). */
     get cap() {
@@ -290,7 +332,7 @@ let SandboxService = class SandboxService {
      * too) are thrown as they are.
      */
     async ifRunning(environmentId, instance, fn, signal = new AbortController().signal) {
-        const p = this.require();
+        const p = await this.require(environmentId);
         const env = environmentId;
         const deadline = Date.now() + this.config.get().sandbox.lockWaitSeconds * 1000;
         const token = randomUUID();
@@ -319,7 +361,14 @@ let SandboxService = class SandboxService {
                     try {
                         const impl = tagged(p.impl, lease.token, undefined, () => this.register(env, lease.token));
                         const sig = AbortSignal.any([signal, lease.signal]);
-                        return { kind: "ran", value: await fn(impl, e.handle, sig) };
+                        try {
+                            return { kind: "ran", value: await fn(impl, e.handle, sig) };
+                        }
+                        catch (err) {
+                            if (isFileSystemGoneError(err))
+                                throw await this.filesGone(env, p, e);
+                            throw err;
+                        }
                     }
                     finally {
                         await this.leave(env, e);
@@ -353,12 +402,13 @@ let SandboxService = 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).
+     * - Lost files throw `environment.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).
      */
     async withSandbox(ctx, fn, signal) {
-        const p = this.require();
+        const p = await this.require(ctx.environmentId, ctx.orgId);
         const env = ctx.environmentId;
         const holder = ctx.holderConversationId;
         let e = await this.seenBy(env, holder, await this.enter(ctx, p, signal, null));
@@ -367,6 +417,8 @@ let SandboxService = class SandboxService {
                 return await this.runAs(e, ctx, p, fn, signal);
             }
             catch (err) {
+                if (isFileSystemGoneError(err))
+                    throw await this.filesGone(env, p, e);
                 if (!isSandboxGoneError(err))
                     throw err;
                 this.log.info("sandbox instance is gone during use; recreating", { environmentId: env });
@@ -374,13 +426,47 @@ let SandboxService = class SandboxService {
                 const prev = e;
                 await this.leave(env, prev);
                 e = await this.seenBy(env, holder, await this.enter(ctx, p, signal, gone));
-                return await this.runAs({ ...e, info: { fresh: true, restarted: true } }, ctx, p, fn, signal);
+                try {
+                    return await this.runAs({ ...e, info: { fresh: true, restarted: true } }, ctx, p, fn, signal);
+                }
+                catch (err2) {
+                    if (isFileSystemGoneError(err2))
+                        throw await this.filesGone(env, p, e);
+                    throw err2;
+                }
             }
         }
         finally {
             await this.leave(env, e);
         }
     }
+    /**
+     * 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
+     * machine: until a new login, which resets the row). A failed write only logs.
+     */
+    async filesGone(env, p, e) {
+        this.log.warn("environment file system is gone at the provider; its files are lost", {
+            environmentId: env,
+            provider: p.plugin,
+        });
+        try {
+            await this.db
+                .updateTable("environment_instances")
+                .set((eb) => ({ fs_status: "lost", generation: eb("generation", "+", 1) }))
+                .where("environment_id", "=", env)
+                .where("fs_status", "=", "ready")
+                // `createdAt` is the row's value read back in milliseconds
+                .where(sql `date_trunc('milliseconds', created_at)`, "=", new Date(e.createdAt))
+                .execute();
+        }
+        catch (err) {
+            this.log.warn("cannot record lost environment files", { environmentId: env, err });
+        }
+        return environmentFilesLost(p.plugin === DEVICE_PROVIDER);
+    }
     /**
      * Records that `holder` uses the instance of `e` (`capk:sandbox-seen:<env>:<holder>` =
      * `<created_at>:<file system id>`, with a TTL of the inactivity destruction plus a day). When the
@@ -415,7 +501,7 @@ let SandboxService = class SandboxService {
         const sig = AbortSignal.any([signal, e.lease.signal]);
         const env = ctx.environmentId;
         const impl = tagged(p.impl, e.lease.token, ctx.actor, () => this.register(env, e.lease.token));
-        return fn(e.handle, impl, e.info, sig);
+        return fn(e.handle, impl, { ...e.info, roots: rootsOf(e.handle) }, sig);
     }
     /**
      * Becomes a holder: loops until it has a shared lease on a running instance, or `sandbox.busy`.
@@ -480,10 +566,14 @@ let SandboxService = class SandboxService {
     foreign(_ctx) {
         return environmentNotFound();
     }
-    /** Recorded running with the current provider, and not the instance found gone. */
+    /**
+     * Recorded running with the current provider on files not lost (lost ones go through the
+     * exclusive path, which refuses them), and not the instance found gone.
+     */
     usable(row, p, gone) {
         return (row !== undefined &&
             row.status === "running" &&
+            row.fs_status !== "lost" &&
             row.provider === p.plugin &&
             row.handle !== null &&
             !isInstance(row, gone));
@@ -624,7 +714,8 @@ let SandboxService = class SandboxService {
      * many it suspended. Called every minute by the `sandbox-suspend-idle` cron.
      */
     async suspendIdle(now) {
-        const p = this.providers.current();
+        // cloud only: suspendDue keeps to this provider's rows, so `@device` is never suspended here
+        const p = this.providers.cloud();
         if (!p)
             return 0;
         const due = this.suspendDue(now, p.plugin);
@@ -666,31 +757,45 @@ let SandboxService = class SandboxService {
      * (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. Returns how many it destroyed. Called hourly by the `sandbox-destroy-inactive` cron.
+     * 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
+     * hourly by the `sandbox-destroy-inactive` cron.
      */
     async destroyInactive(now) {
-        const p = this.providers.current();
-        if (!p)
-            return 0;
+        const p = this.providers.cloud();
+        const device = this.providers.forName(DEVICE_PROVIDER) !== undefined;
         let n = 0;
-        const gone = (eb) => this.environmentGone(eb);
-        await inPool(await this.candidates(gone), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
-            const done = await this.tryLocked(id, async (lease) => {
-                const row = await this.db
-                    .selectFrom("environment_instances")
-                    .selectAll()
-                    .where("environment_id", "=", id)
-                    .where(gone)
-                    .executeTakeFirst();
-                if (!row)
-                    return false;
-                await this.destroyRow(row, p, lease, "environment");
-                return true;
+        // Gone environments (deleted, or of a deleted org) on every provider that is here, `@device`
+        // too (its destroy calls never need the machine online); rows whose provider is missing wait.
+        const here = (eb) => eb.or([
+            ...(p ? [this.cloudRow(eb)] : []),
+            ...(device ? [eb("provider", "=", DEVICE_PROVIDER)] : []),
+        ]);
+        const gone = (eb) => eb.and([here(eb), this.environmentGone(eb)]);
+        if (p || device) {
+            await inPool(await this.candidates(gone), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
+                const done = await this.tryLocked(id, async (lease) => {
+                    const row = await this.db
+                        .selectFrom("environment_instances")
+                        .selectAll()
+                        .where("environment_id", "=", id)
+                        .where(gone)
+                        .executeTakeFirst();
+                    const owner = row && this.rowProvider(row);
+                    if (!row || !owner)
+                        return false;
+                    await this.destroyRow(row, owner, lease, "environment");
+                    return true;
+                });
+                if (done)
+                    n++;
             });
-            if (done)
-                n++;
-        });
-        const idle = this.instanceDue(now);
+        }
+        // inactivity destroys cloud instances only: `@device` instances are never swept
+        if (!p)
+            return n;
+        const due = this.instanceDue(now);
+        const idle = (eb) => eb.and([this.cloudRow(eb), due(eb)]);
         await inPool(await this.candidates(idle), SWEEP_CONCURRENCY, async ({ environment_id: id }) => {
             const done = await this.tryLocked(id, async (lease) => {
                 const row = await this.db
@@ -712,9 +817,11 @@ let SandboxService = class SandboxService {
     /**
      * 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
-     * (with intent, so running commands finish and new ones wait) up to 10 minutes. Without a
-     * provider it only warns (the destruction sweep finishes a deleted environment later). Files kept
-     * by another provider that is not loaded cannot be destroyed: it throws and the row stays.
+     * (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).
+     * Files kept by another provider that is not loaded cannot be destroyed: it throws and the row
+     * stays.
      */
     async destroyEnvironment(environmentId) {
         const row = await this.db
@@ -724,10 +831,15 @@ let SandboxService = class SandboxService {
             .executeTakeFirst();
         if (!row)
             return;
-        const p = this.providers.current();
+        const p = await this.providerOf(environmentId);
         if (!p) {
-            this.log.warn("cannot destroy environment: no sandbox provider", { environmentId });
-            return;
+            await this.db
+                .updateTable("environment_instances")
+                .set({ sweep_failed_at: sql `now()` })
+                .where("environment_id", "=", environmentId)
+                .execute();
+            throw new Error(`cannot destroy environment ${environmentId}: its sandbox provider is not there; ` +
+                "the destruction sweep retries it");
         }
         const lease = await this.leases.acquireExclusive(environmentId, AbortSignal.timeout(EXCLUSIVE_WAIT_MS), undefined, { intent: true });
         try {
@@ -750,7 +862,7 @@ let SandboxService = class SandboxService {
      * creates a new one. Nothing to do without a row. Throws `sandbox.unavailable` without a provider.
      */
     async resetFileSystem(environmentId) {
-        const p = this.require();
+        const p = await this.require(environmentId);
         const lease = await this.leases.acquireExclusive(environmentId, AbortSignal.timeout(EXCLUSIVE_WAIT_MS), undefined, { intent: true });
         try {
             const row = await this.db
@@ -839,12 +951,6 @@ let SandboxService = class SandboxService {
         }
         await this.background.clearKill(cleared.map((r) => r.id));
     }
-    require() {
-        const p = this.providers.current();
-        if (!p)
-            throw sandboxUnavailable();
-        return p;
-    }
     /**
      * A fenced write: only while the lease holds and the row's generation is still the one read
      * under it (and incremented); otherwise {@link SandboxLockLostError}.
@@ -968,7 +1074,7 @@ let SandboxService = class SandboxService {
         // kept running (a stalled sweep) then fails its next write.
         await this.fenced(held, id, fence, {});
         if (row.fs_status === "lost")
-            throw environmentFilesLost();
+            throw environmentFilesLost(p.plugin === DEVICE_PROVIDER);
         if (row.provider !== null &&
             row.provider !== p.plugin &&
             (row.fs_status !== "none" || row.handle !== null)) {
@@ -1080,7 +1186,7 @@ let SandboxService = class SandboxService {
                 provider: p.plugin,
             });
             await this.fenced(held, id, fence, { fs_status: "lost", status: "none" });
-            throw environmentFilesLost();
+            throw environmentFilesLost(p.plugin === DEVICE_PROVIDER);
         }
         let createdAt;
         try {
@@ -1115,7 +1221,7 @@ let SandboxService = class SandboxService {
      * usable; an abort is thrown.
      */
     async dropUnrecordedFiles(id, provider, signal) {
-        const old = this.providers.lookup(provider);
+        const old = this.providers.forName(provider)?.impl;
         if (!old) {
             this.log.warn("environment file system may have been made by a provider that is not loaded; it may leak", { environmentId: id, provider });
             return;
@@ -1138,7 +1244,7 @@ let SandboxService = class SandboxService {
      * false; otherwise warns and returns true (the record must be kept).
      */
     async retire(id, provider, handle, signal) {
-        const old = this.providers.lookup(provider);
+        const old = this.providers.forName(provider)?.impl;
         if (old) {
             try {
                 await old.destroy(handle, AbortSignal.any([signal, AbortSignal.timeout(SWEEP_OP_TIMEOUT_MS)]));
@@ -1175,7 +1281,7 @@ let SandboxService = class SandboxService {
         }
         else if (!row.handle && row.status === "creating") {
             // the provider may have built it already: only the name finds it
-            const impl = owner === p.plugin ? p.impl : this.providers.lookup(owner);
+            const impl = owner === p.plugin ? p.impl : this.providers.forName(owner)?.impl;
             await impl?.destroyByName(environmentResourceName(id), signal);
         }
         if (row.prev_handle && row.prev_provider && !("prev_handle" in prev)) {
@@ -1194,7 +1300,7 @@ let SandboxService = class SandboxService {
     async destroyFiles(row, p, signal, lenient = false) {
         const id = row.environment_id;
         const owner = row.provider ?? p.plugin;
-        const impl = owner === p.plugin ? p.impl : this.providers.lookup(owner);
+        const impl = owner === p.plugin ? p.impl : this.providers.forName(owner)?.impl;
         if (!impl) {
             if (row.fs_handle === null)
                 return;
@@ -1256,6 +1362,17 @@ let SandboxService = class SandboxService {
             eb.or([eb("last_used_at", "<", idleBefore), eb("running_since", "<", runningBefore)]),
         ]);
     }
+    /** The provider of an instance row: an internal one (`@device`) by name, else the cloud one. */
+    rowProvider(row) {
+        return providerForEnvironment(this.providers, row.provider);
+    }
+    /**
+     * A row the idle sweeps may touch: not on a kernel-internal provider (`@device` instances live on
+     * people's machines and are never suspended or destroyed for inactivity).
+     */
+    cloudRow(eb) {
+        return eb.or([eb("provider", "is", null), eb("provider", "not like", "@%")]);
+    }
     /** The environment was deleted, or its org was: the instance and the files go. */
     environmentGone(eb) {
         return eb.or([

package/dist/tools/builtins/sandbox/bash.d.ts

@@ -9,8 +9,8 @@ export declare const BASH_DESCRIPTION_MAX_CHARS = 120;
 export declare const BASH_SPILL_CHARS = 30000;
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。`workspace`: the instance's workspace root.
  */
-export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean): string;
+export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean, workspace?: string): string;
 /** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export declare function sandboxBashTool(deps: SandboxToolDeps): BuiltinTool;