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

package/dist/devices/relay.js

@@ -0,0 +1,373 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { randomUUID } from "node:crypto";
+import { DeviceProtocolError, FileSystemGoneError, parseDeviceFrame, parseOpResult, SandboxGoneError, ToolError, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_BUS, KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
+import { environmentNotFound } from "../sandbox/sandbox.service.js";
+import { deviceLeaseKey, deviceReqKey, deviceReqTopic, deviceResKey, deviceResTopic, } from "./keys.js";
+import { DeviceTargets } from "./targets.js";
+/** The environment's connected machine is not connected (no replica holds its lease). */
+export const environmentOffline = () => new ApiError("environment.offline", "The connected machine of this environment is offline. Start capybara-device on that machine, or pick another environment.");
+/**
+ * The environment's machine was disconnected (revoked, signed out): 403 `environment.forbidden`
+ * with `details: [{ reason: "machine_revoked" }]`, so the tools tell the model what to ask for.
+ */
+export const machineRevoked = () => new ApiError("environment.forbidden", "The connected machine of this environment was disconnected. Run capybara-device logout, then capybara-device login on it, or pick another environment.", [{ reason: "machine_revoked" }]);
+/** The text a machine's `error` result reaches the model with (ruling R28). */
+export const ON_MACHINE_PREFIX = "On the connected machine: ";
+/** The longest one lease check of a waiting caller may take before it counts as "unknown". */
+export const LEASE_CHECK_TIMEOUT_MS = 2000;
+/** How often a waiting caller checks that a replica still holds the machine's connection. */
+export const HOLDER_POLL_MS = 5000;
+/**
+ * How much longer than the caller's wait a queued request lives: giving up must still find an
+ * untaken request on the list (an expired one would look taken and get a needless cancel).
+ */
+export const LIST_TTL_MARGIN_MS = 30_000;
+/**
+ * Appends one frame to the request list and makes sure the list lives at least `ARGV[2]` ms
+ * (never shortens the TTL a request with a longer deadline set). Atomic, so the list never exists
+ * without a TTL.
+ */
+const PUSH_WITH_TTL = `
+redis.call('RPUSH', KEYS[1], ARGV[1])
+if redis.call('PTTL', KEYS[1]) < tonumber(ARGV[2]) then
+  redis.call('PEXPIRE', KEYS[1], ARGV[2])
+end
+return 1
+`;
+/**
+ * Gives up on a request (ruling R15): removes the exact request frame `ARGV[1]` from the list; only
+ * when it is no longer queued (the machine already took it) appends the cancel `ARGV[2]`, with the
+ * TTL rule of {@link PUSH_WITH_TTL}. Returns 1 when a cancel was queued.
+ */
+const GIVE_UP = `
+if redis.call('LREM', KEYS[1], 1, ARGV[1]) > 0 then
+  return 0
+end
+redis.call('RPUSH', KEYS[1], ARGV[2])
+if redis.call('PTTL', KEYS[1]) < tonumber(ARGV[3]) then
+  redis.call('PEXPIRE', KEYS[1], ARGV[3])
+end
+return 1
+`;
+/** Why a call stopped waiting without a result. */
+const ABORTED = Symbol("aborted");
+const GRACE_EXPIRED = Symbol("grace expired");
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * The caller side of the device relay (environments spec §13.4). A request goes onto the
+ * environment's Redis list (`capk:device-req:<environmentId>`) and is announced on
+ * `device.req.<environmentId>`; whichever gateway replica holds the machine's lease drains the
+ * list and forwards the frames to the machine.
+ *
+ * **The holder's half of the wire** (Task 6 follows it): items on the list are `KernelReq` or
+ * `KernelCancel` frames as JSON text, to be parsed with `parseDeviceFrame(item, "kernel")`; the
+ * nudge's payload is `{ id }`. For each `res` frame the machine sends, the holder writes the frame
+ * (the JSON text as validated by `parseDeviceFrame(…, "device")`) under
+ * `capk:device-res:<requestId>` with a TTL and publishes the same frame object on
+ * `device.res.<requestId>`.
+ *
+ * The caller subscribes to its result topic before pushing and reads the result key once after,
+ * and once more before giving up (the run-abort pattern; a publish lost while the subscriber
+ * reconnects is still found). It waits within its own call for at most `deadlineMs` plus
+ * `environments.device.reconnectGraceSeconds`; when the lease disappears meanwhile (checked every
+ * {@link HOLDER_POLL_MS}) the wait ends at most one grace later. A result produced while the
+ * machine was disconnected arrives after it reconnects. Giving up (grace, abort, a bad result)
+ * removes the request from the list, or queues a `cancel` when the machine already took it
+ * (ruling R15). Nothing is kept in process memory beyond the call.
+ */
+let DeviceRelay = class DeviceRelay {
+    redis;
+    bus;
+    locks;
+    config;
+    log;
+    targets;
+    constructor(redis, bus, locks, config, log, targets) {
+        this.redis = redis;
+        this.bus = bus;
+        this.locks = locks;
+        this.config = config;
+        this.log = log;
+        this.targets = targets;
+    }
+    /** Whether a gateway replica holds the machine's connection now. */
+    async holderLive(environmentId) {
+        return (await this.locks.holderOf(deviceLeaseKey(environmentId))) !== null;
+    }
+    /**
+     * Queues `op` for the machine without waiting for an answer (ruling R14: `stop`). The caller
+     * checks {@link holderLive} first; the frame waits on the list for the grace like any request.
+     */
+    async send(environmentId, op, args, deadlineMs) {
+        const id = randomUUID();
+        const d = Math.max(1, Math.ceil(deadlineMs));
+        const req = { type: "req", id, op, args, deadlineMs: d };
+        await this.push(environmentId, JSON.stringify(req), this.graceMs() + d + LIST_TTL_MARGIN_MS);
+        await this.bus.publish(deviceReqTopic(environmentId), { id });
+    }
+    /**
+     * Runs `op` on the environment's machine and returns its validated result. Throws
+     * `environment.offline` when no replica holds the machine at send time or when the wait ran
+     * out, but `environment.forbidden` ({@link machineRevoked}) when the machine was revoked and
+     * `environment.not_found` when the environment was deleted (checked whenever the connection is
+     * missing, ruling R27); the machine's failures map to `SandboxGoneError` (`gone`),
+     * `FileSystemGoneError` (`fs_gone`) or a `ToolError` (`policy`, and `error` prefixed
+     * {@link ON_MACHINE_PREFIX}); an invalid answer throws a `DeviceProtocolError`. On abort the
+     * abort reason is thrown.
+     */
+    async call(environmentId, op, args, opts) {
+        const { signal } = opts;
+        signal.throwIfAborted();
+        if (!(await this.holderLive(environmentId))) {
+            throw this.goneError(await this.targetState(environmentId)) ?? environmentOffline();
+        }
+        signal.throwIfAborted();
+        const id = randomUUID();
+        const deadlineMs = Math.max(1, Math.ceil(opts.deadlineMs));
+        const graceMs = this.graceMs();
+        const listTtlMs = graceMs + deadlineMs + LIST_TTL_MARGIN_MS;
+        const reqJson = JSON.stringify({ type: "req", id, op, args, deadlineMs });
+        let settle;
+        const outcome = new Promise((resolve) => {
+            let done = false;
+            settle = (r) => {
+                if (done)
+                    return;
+                done = true;
+                resolve(r);
+            };
+        });
+        const onStored = (raw) => {
+            if (raw !== null)
+                settle(this.parseRes(raw, id));
+        };
+        const onAbort = () => settle({ error: ABORTED });
+        const unsubscribe = await this.bus.subscribe(deviceResTopic(id), (payload) => {
+            onStored(JSON.stringify(payload));
+        });
+        let timer;
+        let stopped = false;
+        try {
+            signal.addEventListener("abort", onAbort, { once: true });
+            // aborted while subscribing: nothing was sent yet
+            signal.throwIfAborted();
+            await this.push(environmentId, reqJson, listTtlMs);
+            this.nudge(environmentId, id);
+            onStored(await this.redis.get(deviceResKey(id)));
+            // wait until the result, the abort, or `giveUpAt`. The lease is checked every poll: its loss
+            // caps `giveUpAt` at one grace from then (never extending it); a reconnect within that grace
+            // restores the full wait, so a long command whose machine blipped keeps its deadline
+            const fullGiveUpAt = Date.now() + deadlineMs + graceMs;
+            let giveUpAt = fullGiveUpAt;
+            let capped = false;
+            const tick = async () => {
+                if (stopped)
+                    return;
+                try {
+                    // a stalled Redis must not hold the give-up back: no answer in time means "unknown"
+                    const live = await this.leaseCheck(environmentId);
+                    if (live === true && capped) {
+                        capped = false;
+                        giveUpAt = fullGiveUpAt;
+                    }
+                    else if (live === false && !capped) {
+                        capped = true;
+                        giveUpAt = Math.min(giveUpAt, Date.now() + graceMs);
+                    }
+                    if (live === false) {
+                        // a revoked machine or a deleted environment never comes back: fail at once
+                        const gone = this.goneError(await this.targetState(environmentId));
+                        if (gone) {
+                            settle({ error: gone });
+                            return;
+                        }
+                    }
+                }
+                catch (e) {
+                    this.log.warn("device relay lease check failed", { environmentId, error: errMsg(e) });
+                }
+                if (stopped)
+                    return;
+                if (Date.now() >= giveUpAt) {
+                    // a last look at the key: the publish may have been lost while the subscriber reconnected
+                    this.redis.get(deviceResKey(id)).then((raw) => (raw !== null ? onStored(raw) : settle({ error: GRACE_EXPIRED })), () => settle({ error: GRACE_EXPIRED }));
+                    return;
+                }
+                schedule();
+            };
+            const schedule = () => {
+                if (stopped)
+                    return;
+                const wait = Math.max(0, Math.min(HOLDER_POLL_MS, giveUpAt - Date.now()));
+                timer = setTimeout(() => void tick(), wait);
+            };
+            schedule();
+            const r = await outcome;
+            stopped = true;
+            clearTimeout(timer);
+            if ("res" in r) {
+                await this.quietly("delete the result", environmentId, () => this.redis.del(deviceResKey(id)));
+                return this.resultOf(op, r.res);
+            }
+            if (r.error instanceof Error) {
+                // a bad answer: drop it, give the request up, report the protocol error
+                await this.quietly("delete the result", environmentId, () => this.redis.del(deviceResKey(id)));
+            }
+            await this.giveUp(environmentId, id, reqJson, listTtlMs);
+            if (r.error === ABORTED)
+                throw signal.reason;
+            if (r.error === GRACE_EXPIRED)
+                throw environmentOffline();
+            throw r.error;
+        }
+        finally {
+            stopped = true;
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            await this.quietly("unsubscribe", environmentId, unsubscribe);
+        }
+    }
+    /** {@link holderLive}, or undefined when it takes longer than {@link LEASE_CHECK_TIMEOUT_MS}. */
+    async leaseCheck(environmentId) {
+        let timer;
+        const check = this.holderLive(environmentId);
+        check.catch(() => { }); // a late failure after the timeout is not unhandled
+        try {
+            return await Promise.race([
+                check,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(undefined), LEASE_CHECK_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * The environment's state ({@link DeviceTargets}), or undefined when it cannot be read within
+     * {@link LEASE_CHECK_TIMEOUT_MS} (a failure only logs: the caller keeps its other rules).
+     */
+    async targetState(environmentId) {
+        let timer;
+        const read = this.targets.state(environmentId);
+        read.catch(() => { });
+        try {
+            return await Promise.race([
+                read,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(undefined), LEASE_CHECK_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        catch (e) {
+            this.log.warn("device relay could not read the environment state", {
+                environmentId,
+                error: errMsg(e),
+            });
+            return undefined;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** The error of a state that never comes back; undefined for `active` or unknown. */
+    goneError(state) {
+        if (state === "deleted")
+            return environmentNotFound();
+        if (state === "revoked")
+            return machineRevoked();
+        return undefined;
+    }
+    graceMs() {
+        return this.config.get().environments.device.reconnectGraceSeconds * 1000;
+    }
+    async push(environmentId, frame, ttlMs) {
+        await this.redis.eval(PUSH_WITH_TTL, 1, deviceReqKey(environmentId), frame, String(ttlMs));
+    }
+    /** Announces new frames to the holder; a lost nudge is picked up on the holder's next drain. */
+    nudge(environmentId, id) {
+        this.bus.publish(deviceReqTopic(environmentId), { id }).catch((e) => {
+            this.log.warn("device relay nudge failed", { environmentId, error: errMsg(e) });
+        });
+    }
+    /** Removes the request from the list, or queues a cancel when the machine took it (R15). */
+    async giveUp(environmentId, id, reqJson, ttlMs) {
+        const cancel = JSON.stringify({ type: "cancel", id });
+        await this.quietly("give the request up", environmentId, async () => {
+            const queued = await this.redis.eval(GIVE_UP, 1, deviceReqKey(environmentId), reqJson, cancel, String(ttlMs));
+            if (queued === 1)
+                this.nudge(environmentId, id);
+        });
+    }
+    /** Runs a side step whose failure must not replace the call's outcome: logged, swallowed. */
+    async quietly(what, environmentId, fn) {
+        try {
+            await fn();
+        }
+        catch (e) {
+            this.log.warn(`device relay could not ${what}`, { environmentId, error: errMsg(e) });
+        }
+    }
+    /** A stored / published `res` frame for request `id`, or the protocol error it carries. */
+    parseRes(raw, id) {
+        try {
+            const f = parseDeviceFrame(raw, "device");
+            if (f.type !== "res" || f.id !== id) {
+                return { error: new DeviceProtocolError("the connected machine sent an unexpected frame") };
+            }
+            return { res: f };
+        }
+        catch (e) {
+            return {
+                error: e instanceof DeviceProtocolError
+                    ? e
+                    : new DeviceProtocolError(`the connected machine sent an invalid frame: ${errMsg(e)}`),
+            };
+        }
+    }
+    resultOf(op, res) {
+        if (res.ok) {
+            try {
+                return parseOpResult(op, res.result);
+            }
+            catch (e) {
+                throw new DeviceProtocolError(`The connected machine sent an invalid ${op} result: ${errMsg(e)}`);
+            }
+        }
+        const { kind, message } = res.error;
+        switch (kind) {
+            case "gone":
+                throw new SandboxGoneError(message);
+            case "fs_gone":
+                throw new FileSystemGoneError(message);
+            case "policy":
+                throw new ToolError(`Refused by the machine's local policy: ${message}`);
+            default:
+                throw new ToolError(`${ON_MACHINE_PREFIX}${message}`);
+        }
+    }
+};
+DeviceRelay = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KERNEL_BUS)),
+    __param(2, Inject(LockService)),
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(KERNEL_LOGGER)),
+    __param(5, Inject(DeviceTargets))
+], DeviceRelay);
+export { DeviceRelay };

package/dist/devices/targets.d.ts

@@ -0,0 +1,28 @@
+import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * Whether a device environment can still be served: `active` (live and an unrevoked machine),
+ * `revoked` (live, no active machine: disconnected or signed out) or `deleted` (missing or
+ * deleted, or its org deleted).
+ */
+export type DeviceTargetState = "active" | "revoked" | "deleted";
+/** Whether two sets of roots name the same three directories. */
+export declare const sameRoots: (a: SandboxRoots, b: SandboxRoots) => boolean;
+/**
+ * Reads a device environment and its machine from PG for the relay and the `@device` provider.
+ * The relay asks {@link state} when a machine has no connection, so a revoked machine or a deleted
+ * environment fails a waiting call at once instead of after the reconnect grace (ruling R27).
+ * Kept apart from `MachinesService` (which depends on the relay) so there is no dependency cycle.
+ */
+export declare class DeviceTargets {
+    private readonly db;
+    constructor(db: KernelDb);
+    state(environmentId: string): Promise<DeviceTargetState>;
+    /** The org of a live environment, or null (missing or deleted). */
+    orgOf(environmentId: string): Promise<string | null>;
+    /**
+     * The roots the environment's active machine last reported in its hello frame, or null (no
+     * active machine, or none reported yet).
+     */
+    machineRoots(environmentId: string): Promise<SandboxRoots | null>;
+}

package/dist/devices/targets.js

@@ -0,0 +1,73 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelDb } from "../infra/database/kernel-db.js";
+const ROOT_KEYS = ["workspace", "skills", "tmp"];
+/** Whether two sets of roots name the same three directories. */
+export const sameRoots = (a, b) => ROOT_KEYS.every((k) => a[k] === b[k]);
+/**
+ * Reads a device environment and its machine from PG for the relay and the `@device` provider.
+ * The relay asks {@link state} when a machine has no connection, so a revoked machine or a deleted
+ * environment fails a waiting call at once instead of after the reconnect grace (ruling R27).
+ * Kept apart from `MachinesService` (which depends on the relay) so there is no dependency cycle.
+ */
+let DeviceTargets = class DeviceTargets {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async state(environmentId) {
+        const row = await this.db
+            .selectFrom("environments as e")
+            .innerJoin("orgs as o", "o.id", "e.org_id")
+            .leftJoin("environment_machines as m", (j) => j.onRef("m.environment_id", "=", "e.id").on("m.revoked_at", "is", null))
+            .select(["e.id", "m.id as machine_id"])
+            .where("e.id", "=", environmentId)
+            .where("e.deleted_at", "is", null)
+            .where("o.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!row)
+            return "deleted";
+        return row.machine_id === null ? "revoked" : "active";
+    }
+    /** The org of a live environment, or null (missing or deleted). */
+    async orgOf(environmentId) {
+        const row = await this.db
+            .selectFrom("environments")
+            .select("org_id")
+            .where("id", "=", environmentId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return row?.org_id ?? null;
+    }
+    /**
+     * The roots the environment's active machine last reported in its hello frame, or null (no
+     * active machine, or none reported yet).
+     */
+    async machineRoots(environmentId) {
+        const row = await this.db
+            .selectFrom("environment_machines")
+            .select("roots")
+            .where("environment_id", "=", environmentId)
+            .where("revoked_at", "is", null)
+            .executeTakeFirst();
+        const r = row?.roots;
+        if (!r || typeof r !== "object")
+            return null;
+        if (!ROOT_KEYS.every((k) => typeof r[k] === "string"))
+            return null;
+        return r;
+    }
+};
+DeviceTargets = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], DeviceTargets);
+export { DeviceTargets };

package/dist/environments/access.d.ts

@@ -13,12 +13,16 @@ export interface ProviderFacts {
     hasInstance: boolean;
 }
 /**
- * The provider an environment works with: the one keeping its files or instance once it has any
- * (they are never migrated, spec §4.2 item 13); before that, the current provider (its first use
- * creates them there), else the one recorded at creation. The same rule as `SandboxService`'s use.
+ * The provider an environment works with: a kernel-internal one (`@device`) as recorded; for a
+ * cloud environment the one keeping its files or instance once it has any (they are never
+ * migrated, spec §4.2 item 13); before that, the current cloud provider (its first use creates
+ * them there), else the one recorded at creation. The same rule as `SandboxService`'s use.
  */
 export declare function environmentProvider(f: ProviderFacts, current: string | undefined): string | null;
-/** The environment's provider is not the current one, or there is no provider (503). */
+/**
+ * The environment's provider is not the current one, or there is no provider (503); for an
+ * internal provider (`@device`), this kernel does not serve it.
+ */
 export declare const environmentUnavailable: (provider: string | null) => ApiError;
 /**
  * Who may use an environment (spec §4.2 item 12): in phase 1 only the owner of a personal
@@ -28,11 +32,12 @@ export declare const environmentUnavailable: (provider: string | null) => ApiErr
 export declare class EnvironmentAccess {
     private readonly db;
     private readonly providers;
-    constructor(db: KernelDb, providers: Pick<SandboxProviders, "current">);
+    constructor(db: KernelDb, providers: Pick<SandboxProviders, "cloud" | "forName">);
     /**
      * The environment if `accountId` may use it in `orgId` now: `environment.not_found` when it is
      * missing, deleted, in another org or someone else's; `environment.unavailable` when its
-     * provider is not the current one (or there is none).
+     * provider is not the current one (or there is none). A `device` environment is usable while
+     * `@device` is registered: whether its machine is online is the relay's concern, not access.
      */
     usable(orgId: string, accountId: string, environmentId: string): Promise<{
         id: string;

package/dist/environments/access.js

@@ -10,23 +10,31 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
-import { SandboxProviders } from "../sandbox/providers.js";
+import { isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
 import { environmentNotFound } from "../sandbox/sandbox.service.js";
 /**
- * The provider an environment works with: the one keeping its files or instance once it has any
- * (they are never migrated, spec §4.2 item 13); before that, the current provider (its first use
- * creates them there), else the one recorded at creation. The same rule as `SandboxService`'s use.
+ * The provider an environment works with: a kernel-internal one (`@device`) as recorded; for a
+ * cloud environment the one keeping its files or instance once it has any (they are never
+ * migrated, spec §4.2 item 13); before that, the current cloud provider (its first use creates
+ * them there), else the one recorded at creation. The same rule as `SandboxService`'s use.
  */
 export function environmentProvider(f, current) {
+    if (f.provider !== null && isInternalProvider(f.provider))
+        return f.provider;
     const holdsResources = f.fsStatus !== null && (f.fsStatus !== "none" || f.hasInstance);
     if (holdsResources)
         return f.instanceProvider;
     return current ?? f.provider;
 }
-/** The environment's provider is not the current one, or there is no provider (503). */
+/**
+ * The environment's provider is not the current one, or there is no provider (503); for an
+ * internal provider (`@device`), this kernel does not serve it.
+ */
 export const environmentUnavailable = (provider) => new ApiError("environment.unavailable", provider === null
     ? "No cloud sandbox is available in this deployment; ask the super admin to enable a sandbox plugin"
-    : `This environment is kept by the sandbox provider ${provider}, which is not the current provider; it can be used again once ${provider} is the deployment's sandbox provider`);
+    : isInternalProvider(provider)
+        ? `This environment runs on a connected machine (${provider}), which this deployment does not serve`
+        : `This environment is kept by the sandbox provider ${provider}, which is not the current provider; it can be used again once ${provider} is the deployment's sandbox provider`);
 /**
  * Who may use an environment (spec §4.2 item 12): in phase 1 only the owner of a personal
  * environment. Anyone else gets `environment.not_found`, never `forbidden`, so ids cannot be
@@ -42,7 +50,8 @@ let EnvironmentAccess = class EnvironmentAccess {
     /**
      * The environment if `accountId` may use it in `orgId` now: `environment.not_found` when it is
      * missing, deleted, in another org or someone else's; `environment.unavailable` when its
-     * provider is not the current one (or there is none).
+     * provider is not the current one (or there is none). A `device` environment is usable while
+     * `@device` is registered: whether its machine is online is the relay's concern, not access.
      */
     async usable(orgId, accountId, environmentId) {
         const row = await this.db
@@ -57,7 +66,13 @@ let EnvironmentAccess = class EnvironmentAccess {
             .executeTakeFirst();
         if (!row)
             throw environmentNotFound();
-        const current = this.providers.current()?.plugin;
+        if (row.provider !== null && isInternalProvider(row.provider)) {
+            if (this.providers.forName(row.provider) === undefined) {
+                throw environmentUnavailable(row.provider);
+            }
+            return { id: row.id, provider: row.provider };
+        }
+        const current = this.providers.cloud()?.plugin;
         const provider = environmentProvider({
             provider: row.provider,
             instanceProvider: row.instance_provider,

package/dist/environments/conversation-environments.d.ts

@@ -29,12 +29,13 @@ export declare class ConversationEnvironments {
     private readonly providers;
     private readonly access;
     private readonly environments;
-    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "current">, access: Pick<EnvironmentAccess, "usable">, environments: Pick<EnvironmentsService, "ensureDefault">);
+    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "cloud"> & Partial<Pick<SandboxProviders, "forName">>, access: Pick<EnvironmentAccess, "usable">, environments: Pick<EnvironmentsService, "ensureDefault">);
     /**
      * 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.
      */
     forNew(orgId: string, accountId: string, pick?: NewConversationEnvironment): Promise<string | null>;
     /**
@@ -42,18 +43,31 @@ export declare 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.
      */
     forTool(orgId: string, rootConversationId: string): Promise<string>;
+    /**
+     * 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.
+     */
+    usableNow(orgId: string, rootConversationId: string): Promise<boolean>;
     /**
      * 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`.
      */
     private defaultFor;
     /** Binds an unbound conversation to `environmentId`; returns what it is bound to now. */
     private bind;
+    /** The environment runs on a kernel-internal provider (`@device`). */
+    private isInternal;
     /** The account is the org's anonymous IM guest (no person behind it). */
     private isAnonymous;
     /** The conversation is (or was) an IM thread's. */