@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/db/pool.d.ts

@@ -18,6 +18,11 @@ export declare function pgConnectOptions(cfg: {
  */
 export declare function createDb(url: string, poolMax: number, onError?: (err: Error) => void, opts?: {
     connectTimeoutMs?: number | undefined;
+    /**
+     * How long an idle client stays in the pool (pg's `idleTimeoutMillis`; unset = pg's 10 s).
+     * Every new client costs a TCP + auth handshake, several round trips to a distant database.
+     */
+    idleTimeoutMs?: number | undefined;
     /**
      * Error of a client while it is checked out: pg-pool drops its own listener on checkout, so
      * without this a backend killed between two statements is an uncaught exception.

package/dist/db/pool.js

@@ -22,6 +22,9 @@ export function createDb(url, poolMax, onError = (err) => console.error("[db] id
         connectionString: url,
         max: poolMax,
         ...pgConnectOptions(opts),
+        ...(opts.idleTimeoutMs !== undefined && { idleTimeoutMillis: opts.idleTimeoutMs }),
+        // a client kept idle longer must notice a dead peer (a dropped VPN, a NAT timeout) by itself
+        keepAlive: true,
     });
     pool.on("error", onError);
     pool.on("connect", (client) => client.on("error", opts.onClientError ?? onError));

package/dist/devices/access.d.ts

@@ -0,0 +1,66 @@
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+/** What decides a device's provider: its own record and its instance row's (if any). */
+export interface ProviderFacts {
+    /** `devices.provider`: the provider current when it was created. */
+    provider: string | null;
+    /** `device_instances.provider`; null without an instance row. */
+    instanceProvider: string | null;
+    /** The instance row's `fs_status`; null without an instance row. */
+    fsStatus: "none" | "ready" | "lost" | null;
+    /** The instance row records an instance handle. */
+    hasInstance: boolean;
+}
+/**
+ * The provider a device works with: a kernel-internal one (`@local`) as recorded; for a
+ * cloud device 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 deviceProvider(f: ProviderFacts, current: string | undefined): string | null;
+/** It has files or an instance at some provider (a file system, even a lost one, or a handle). */
+export declare const holdsResources: (f: ProviderFacts) => boolean;
+/** `device_instances.status`. */
+export type InstanceStatus = "none" | "creating" | "running" | "suspended" | "destroyed";
+/**
+ * For replacing a default (which one is the person's default): it holds healthy files or an
+ * instance, or an instance row is under way (`creating`, `running`, `suspended`: a first use may
+ * be creating the instance before any file system or handle is recorded). Lost files count as
+ * none here, unlike {@link holdsResources}, which decides the provider.
+ */
+export declare const inUseForDefault: (f: ProviderFacts & {
+    status: InstanceStatus | null;
+}) => boolean;
+/**
+ * The provider a former default belongs to (its label and the provider whose switch back restores
+ * it): the one holding its resources once it holds any, else the one it was demoted from (the
+ * marker). A former default demoted while empty and used afterwards keeps a stale marker; its
+ * resources decide. null for a device that is not a former default.
+ */
+export declare function demotedProvider(marker: string | null, f: ProviderFacts): string | null;
+/**
+ * The device's provider is not the current one, or there is no provider (503); for an
+ * internal provider (`@local`), this kernel does not serve it.
+ */
+export declare const deviceUnavailable: (provider: string | null) => ApiError;
+/**
+ * Who may use a device (spec §4.2 item 12): in phase 1 only the owner of a personal
+ * device. Anyone else gets `device.not_found`, never `forbidden`, so ids cannot be
+ * probed. Read live on every call (PG, no cache); phase 3 adds project membership.
+ */
+export declare class DeviceAccess {
+    private readonly db;
+    private readonly providers;
+    constructor(db: KernelDb, providers: Pick<SandboxProviders, "cloud" | "forName">);
+    /**
+     * The device if `accountId` may use it in `orgId` now: `device.not_found` when it is
+     * missing, deleted, in another org or someone else's; `device.unavailable` when its
+     * provider is not the current one (or there is none). A local device is usable while
+     * `@local` is registered: whether its machine is online is the relay's concern, not access.
+     */
+    usable(orgId: string, accountId: string, deviceId: string): Promise<{
+        id: string;
+        provider: string | null;
+    }>;
+}

package/dist/devices/access.js

@@ -0,0 +1,113 @@
+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 { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
+import { deviceNotFound } from "../sandbox/sandbox.service.js";
+/**
+ * The provider a device works with: a kernel-internal one (`@local`) as recorded; for a
+ * cloud device 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 deviceProvider(f, current) {
+    if (f.provider !== null && isInternalProvider(f.provider))
+        return f.provider;
+    if (holdsResources(f))
+        return f.instanceProvider;
+    return current ?? f.provider;
+}
+/** It has files or an instance at some provider (a file system, even a lost one, or a handle). */
+export const holdsResources = (f) => f.fsStatus !== null && (f.fsStatus !== "none" || f.hasInstance);
+/**
+ * For replacing a default (which one is the person's default): it holds healthy files or an
+ * instance, or an instance row is under way (`creating`, `running`, `suspended`: a first use may
+ * be creating the instance before any file system or handle is recorded). Lost files count as
+ * none here, unlike {@link holdsResources}, which decides the provider.
+ */
+export const inUseForDefault = (f) => f.fsStatus === "ready" ||
+    f.hasInstance ||
+    (f.status !== null && f.status !== "none" && f.status !== "destroyed");
+/**
+ * The provider a former default belongs to (its label and the provider whose switch back restores
+ * it): the one holding its resources once it holds any, else the one it was demoted from (the
+ * marker). A former default demoted while empty and used afterwards keeps a stale marker; its
+ * resources decide. null for a device that is not a former default.
+ */
+export function demotedProvider(marker, f) {
+    if (marker === null)
+        return null;
+    return (holdsResources(f) ? f.instanceProvider : null) ?? marker;
+}
+/**
+ * The device's provider is not the current one, or there is no provider (503); for an
+ * internal provider (`@local`), this kernel does not serve it.
+ */
+export const deviceUnavailable = (provider) => new ApiError("device.unavailable", provider === null
+    ? "No cloud sandbox is available in this deployment; ask the super admin to enable a sandbox plugin"
+    : isInternalProvider(provider)
+        ? `This device runs on a connected machine (${provider}), which this deployment does not serve`
+        : `This device 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 a device (spec §4.2 item 12): in phase 1 only the owner of a personal
+ * device. Anyone else gets `device.not_found`, never `forbidden`, so ids cannot be
+ * probed. Read live on every call (PG, no cache); phase 3 adds project membership.
+ */
+let DeviceAccess = class DeviceAccess {
+    db;
+    providers;
+    constructor(db, providers) {
+        this.db = db;
+        this.providers = providers;
+    }
+    /**
+     * The device if `accountId` may use it in `orgId` now: `device.not_found` when it is
+     * missing, deleted, in another org or someone else's; `device.unavailable` when its
+     * provider is not the current one (or there is none). A local device is usable while
+     * `@local` is registered: whether its machine is online is the relay's concern, not access.
+     */
+    async usable(orgId, accountId, deviceId) {
+        const row = await this.db
+            .selectFrom("devices as e")
+            .leftJoin("device_instances as i", "i.device_id", "e.id")
+            .select(["e.id", "e.provider", "i.provider as instance_provider", "i.fs_status", "i.handle"])
+            .where("e.id", "=", deviceId)
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!row)
+            throw deviceNotFound();
+        if (row.provider !== null && isInternalProvider(row.provider)) {
+            if (this.providers.forName(row.provider) === undefined) {
+                throw deviceUnavailable(row.provider);
+            }
+            return { id: row.id, provider: row.provider };
+        }
+        const current = this.providers.cloud()?.plugin;
+        const provider = deviceProvider({
+            provider: row.provider,
+            instanceProvider: row.instance_provider,
+            fsStatus: row.fs_status,
+            hasInstance: row.handle !== null,
+        }, current);
+        if (current === undefined || provider !== current)
+            throw deviceUnavailable(provider);
+        return { id: row.id, provider };
+    }
+};
+DeviceAccess = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(SandboxProviders))
+], DeviceAccess);
+export { DeviceAccess };

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

@@ -0,0 +1,75 @@
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { DeviceAccess } from "./access.js";
+import { DevicesService } from "./devices.service.js";
+/** `details[0].reason` of the error an anonymous IM conversation's sandbox call gets. */
+export declare const ANONYMOUS_NO_DEVICE = "anonymous";
+/** Anonymous IM senders have no device (spec §4.2 item 8): their sandbox tools are off. */
+export declare const anonymousNoDevice: () => ApiError;
+/** How a new conversation picks its device. */
+export interface NewConversationDevice {
+    /** The device the person chose (the composer's picker); checked with `usable`. */
+    deviceId?: string;
+    /** An IM thread: the person's IM default (`device_defaults`) when still usable. */
+    im?: boolean;
+}
+/**
+ * Which device a conversation works in (spec 2026-11-07-environments-design §4.1 items 1, 3;
+ * §4.2 items 8, 9, 12). A conversation is bound once, to a device of its owner
+ * (`conversations.account_id`): the one chosen at its first send, else the owner's IM default
+ * (IM threads), else the owner's default device. Its sub-agents use the root's. Access is
+ * checked when it is bound and again on every sandbox tool call ({@link forTool}); only the owner
+ * may use a personal device, so a conversation never reaches another person's.
+ */
+export declare class ConversationDevices {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly providers;
+    private readonly access;
+    private readonly devices;
+    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "cloud"> & Partial<Pick<SandboxProviders, "forName">>, access: Pick<DeviceAccess, "usable">, devices: Pick<DevicesService, "ensureDefault">);
+    /**
+     * The device a new conversation of `accountId` is bound to: the chosen one when it is
+     * usable by the person (else `device.not_found` / `device.unavailable`, and nothing
+     * is created); without a choice the IM default (IM only) or the person's default device.
+     * Null (unbound) for anonymous IM senders, and without a cloud sandbox provider when no usable
+     * IM default (a connected machine's device, say) applies.
+     */
+    forNew(orgId: string, accountId: string, pick?: NewConversationDevice): Promise<string | null>;
+    /**
+     * The device a sandbox tool call of the conversation tree rooted at `rootConversationId`
+     * enters, checked for its owner now. A conversation still unbound (created before
+     * devices, 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 device; a racing call binds it once.
+     * Throws `sandbox.unavailable` for a cloud device (or none to bind) without a cloud
+     * provider and for an anonymous IM conversation, and `device.not_found` /
+     * `device.unavailable` when the owner may not use it now. A conversation bound to a
+     * connected machine's device (`@local`) 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 device the conversation is bound to (an unbound IM thread:
+     * its owner's IM default) runs on a registered kernel provider (`@local`). A forbidden or gone
+     * device 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 device (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 `device.not_found`.
+     */
+    private defaultFor;
+    /** Binds an unbound conversation to `deviceId`; returns what it is bound to now. */
+    private bind;
+    /** The device runs on a kernel-internal provider (`@local`). */
+    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. */
+    private isImThread;
+}

package/dist/devices/conversation-devices.js

@@ -0,0 +1,230 @@
+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 { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
+import { deviceNotFound, sandboxUnavailable } from "../sandbox/sandbox.service.js";
+import { DeviceAccess } from "./access.js";
+import { DevicesService } from "./devices.service.js";
+/** `details[0].reason` of the error an anonymous IM conversation's sandbox call gets. */
+export const ANONYMOUS_NO_DEVICE = "anonymous";
+/** Anonymous IM senders have no device (spec §4.2 item 8): their sandbox tools are off. */
+export const anonymousNoDevice = () => new ApiError("sandbox.unavailable", "Anonymous IM senders have no device, so the sandbox is not available", [{ reason: ANONYMOUS_NO_DEVICE }]);
+/**
+ * Which device a conversation works in (spec 2026-11-07-environments-design §4.1 items 1, 3;
+ * §4.2 items 8, 9, 12). A conversation is bound once, to a device of its owner
+ * (`conversations.account_id`): the one chosen at its first send, else the owner's IM default
+ * (IM threads), else the owner's default device. Its sub-agents use the root's. Access is
+ * checked when it is bound and again on every sandbox tool call ({@link forTool}); only the owner
+ * may use a personal device, so a conversation never reaches another person's.
+ */
+let ConversationDevices = class ConversationDevices {
+    db;
+    txHost;
+    providers;
+    access;
+    devices;
+    constructor(db, txHost, providers, access, devices) {
+        this.db = db;
+        this.txHost = txHost;
+        this.providers = providers;
+        this.access = access;
+        this.devices = devices;
+    }
+    /**
+     * The device a new conversation of `accountId` is bound to: the chosen one when it is
+     * usable by the person (else `device.not_found` / `device.unavailable`, and nothing
+     * is created); without a choice the IM default (IM only) or the person's default device.
+     * Null (unbound) for anonymous IM senders, and without a cloud sandbox provider when no usable
+     * IM default (a connected machine's device, say) applies.
+     */
+    async forNew(orgId, accountId, pick = {}) {
+        if (pick.deviceId !== undefined) {
+            return (await this.access.usable(orgId, accountId, pick.deviceId)).id;
+        }
+        if (pick.im !== true && this.providers.cloud() === undefined)
+            return null;
+        if (await this.isAnonymous(orgId, accountId))
+            return null;
+        return this.defaultFor(orgId, accountId, pick.im === true);
+    }
+    /**
+     * The device a sandbox tool call of the conversation tree rooted at `rootConversationId`
+     * enters, checked for its owner now. A conversation still unbound (created before
+     * devices, 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 device; a racing call binds it once.
+     * Throws `sandbox.unavailable` for a cloud device (or none to bind) without a cloud
+     * provider and for an anonymous IM conversation, and `device.not_found` /
+     * `device.unavailable` when the owner may not use it now. A conversation bound to a
+     * connected machine's device (`@local`) does not need a cloud provider.
+     */
+    async forTool(orgId, rootConversationId) {
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select(["account_id", "device_id"])
+            .where("id", "=", rootConversationId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!conv)
+            throw deviceNotFound();
+        if (await this.isAnonymous(orgId, conv.account_id))
+            throw anonymousNoDevice();
+        let deviceId = conv.device_id;
+        if (deviceId === null) {
+            const im = await this.isImThread(rootConversationId);
+            const chosen = await this.defaultFor(orgId, conv.account_id, im);
+            if (chosen === null)
+                throw sandboxUnavailable();
+            deviceId = await this.bind(rootConversationId, chosen);
+        }
+        if (this.providers.cloud() === undefined && !(await this.isInternal(deviceId))) {
+            throw sandboxUnavailable();
+        }
+        return (await this.access.usable(orgId, conv.account_id, deviceId)).id;
+    }
+    /**
+     * Whether a sandbox tool call of the tree rooted at `rootConversationId` has a provider to run
+     * on, for tool listings (ruling R8; no binding, no access check, never throws): a cloud
+     * provider is loaded, or the device the conversation is bound to (an unbound IM thread:
+     * its owner's IM default) runs on a registered kernel provider (`@local`). A forbidden or gone
+     * device still counts: the call then says why.
+     */
+    async usableNow(orgId, rootConversationId) {
+        if (this.providers.cloud() !== undefined)
+            return true;
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select(["account_id", "device_id"])
+            .where("id", "=", rootConversationId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!conv)
+            return false;
+        let deviceId = conv.device_id;
+        if (deviceId === null) {
+            if (!(await this.isImThread(rootConversationId)))
+                return false;
+            const row = await this.db
+                .selectFrom("device_defaults")
+                .select("device_id")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", conv.account_id)
+                .executeTakeFirst();
+            if (!row)
+                return false;
+            deviceId = row.device_id;
+        }
+        const env = await this.db
+            .selectFrom("devices")
+            .select("provider")
+            .where("id", "=", deviceId)
+            .executeTakeFirst();
+        const provider = env?.provider ?? null;
+        return (provider !== null &&
+            isInternalProvider(provider) &&
+            this.providers.forName?.(provider) !== undefined);
+    }
+    /**
+     * The person's IM default when `im` and it is still theirs, live, in this org and usable (the
+     * table has no such guard), else their default device (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 `device.not_found`.
+     */
+    async defaultFor(orgId, accountId, im) {
+        if (im) {
+            const row = await this.db
+                .selectFrom("device_defaults")
+                .select("device_id")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .executeTakeFirst();
+            if (row) {
+                try {
+                    return (await this.access.usable(orgId, accountId, row.device_id)).id;
+                }
+                catch (e) {
+                    if (!isDeviceGone(e))
+                        throw e;
+                }
+            }
+        }
+        if (this.providers.cloud() === undefined)
+            return null;
+        try {
+            return await this.devices.ensureDefault(orgId, accountId);
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.code === "org.not_found")
+                throw deviceNotFound();
+            throw e;
+        }
+    }
+    /** Binds an unbound conversation to `deviceId`; returns what it is bound to now. */
+    async bind(conversationId, deviceId) {
+        await this.db
+            .updateTable("conversations")
+            .set({ device_id: deviceId })
+            .where("id", "=", conversationId)
+            .where("device_id", "is", null)
+            .execute();
+        const row = await this.db
+            .selectFrom("conversations")
+            .select("device_id")
+            .where("id", "=", conversationId)
+            .executeTakeFirstOrThrow();
+        return row.device_id ?? deviceId;
+    }
+    /** The device runs on a kernel-internal provider (`@local`). */
+    async isInternal(deviceId) {
+        const row = await this.db
+            .selectFrom("devices")
+            .select("provider")
+            .where("id", "=", deviceId)
+            .executeTakeFirst();
+        const provider = row?.provider ?? null;
+        return provider !== null && isInternalProvider(provider);
+    }
+    /** The account is the org's anonymous IM guest (no person behind it). */
+    async isAnonymous(orgId, accountId) {
+        const row = await this.db
+            .selectFrom("org_anonymous_accounts")
+            .select("account_id")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    /** The conversation is (or was) an IM thread's. */
+    async isImThread(conversationId) {
+        const row = await this.db
+            .selectFrom("channel_threads")
+            .select("id")
+            .where("conversation_id", "=", conversationId)
+            .limit(1)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+};
+__decorate([
+    Transactional()
+], ConversationDevices.prototype, "bind", null);
+ConversationDevices = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SandboxProviders)),
+    __param(3, Inject(DeviceAccess)),
+    __param(4, Inject(DevicesService))
+], ConversationDevices);
+export { ConversationDevices };
+const isDeviceGone = (e) => e instanceof ApiError && (e.code === "device.not_found" || e.code === "device.unavailable");

package/dist/devices/devices.controller.d.ts

@@ -0,0 +1,36 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type DeviceList, DevicesService, type DeviceView } from "./devices.service.js";
+import { type DeviceNameBody, type DeviceParams } from "./dto.js";
+/**
+ * A person's devices in an org (`/api/v1/orgs/:orgId/devices`, spec
+ * 2026-11-07-environments-design §9; `agents.use`, human users only: a service token gets 403).
+ * Phase 1 has personal cloud devices only, each visible to its owner alone: another member
+ * gets 404 `device.not_found`.
+ * - `GET /` → `{ items, defaultId, lastUsedId, cloudAvailable }` (`cloudAvailable`: there is a
+ *   current sandbox provider; ruling R4);
+ * - `POST / { name }` → 201 `{ device }`; `GET /:id`, `PATCH /:id { name }` → `{ device }`;
+ * - `DELETE /:id` → 202 (destroyed by a job after the response);
+ * - `POST /:id/files/reset` → 202 (the reset is enqueued: a worker empties the files, the next use
+ *   starts empty);
+ * - `DELETE /:id/machine` → 204: a local device's machine is disconnected (its credential
+ *   revoked; it must sign in again).
+ */
+export declare class DevicesController {
+    private readonly devices;
+    constructor(devices: DevicesService);
+    list(principal: Principal, org: OrgContext): Promise<DeviceList>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof DeviceNameBody>): Promise<{
+        device: DeviceView;
+    }>;
+    get(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<{
+        device: DeviceView;
+    }>;
+    rename(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>, body: z.infer<typeof DeviceNameBody>): Promise<{
+        device: DeviceView;
+    }>;
+    remove(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<void>;
+    resetFiles(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<void>;
+    revokeMachine(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<void>;
+}